wsb 0.253.6349

//! The only process this crate starts.
//!
//! A child that inherits this process's terminal writes straight past the
//! sink. In human mode that is exactly right — a build's output belongs on the
//! screen as it happens. Under `--jsonl` it is a promise broken:
//! raw bytes in the middle of a stream a consumer is parsing as JSONL.
//!
//! So every child is built here. The type mirrors [`std::process::Command`]'s
//! builder surface, and differs in one place: when the caller has NOT said
//! what to do with a stream, and the run is JSONL, that stream is
//! captured and re-emitted as [`Record::SubprocessOutput`] instead of going to
//! the terminal.
//!
//! What the caller DID say is honoured exactly. A child whose output is
//! silenced with `Stdio::null()` stays silent, and one whose output the caller
//! collects with [`Command::output`] still hands it back — the format of the
//! run must not change which bytes a command decides to show.

use std::ffi::OsStr;
use std::io;
use std::path::Path;
use std::process::{Child, ExitStatus, Output, Stdio};
use std::time::Instant;

use super::record::{Record, Stream};
use super::sink;

#[cfg(unix)]
fn exit_signal(status: &ExitStatus) -> Option<i32> {
    use std::os::unix::process::ExitStatusExt;
    status.signal()
}

/// Whether a child's streams are read by this process rather than handed the
/// terminal: always when output is JSONL (raw bytes would break the stream),
/// and on a terminal only for a child that asked to be transcribed while the
/// run is writing a log — a child that did not ask may need the terminal
/// itself, and one with no log to go to gains nothing from being read.
fn reads_streams(jsonl: bool, transcribed: bool, transcribing: bool) -> bool {
    jsonl || (transcribed && transcribing)
}

/// A child process, built and run the one way this crate runs one.
pub struct Command {
    inner: std::process::Command,
    /// Whether the caller decided what happens to stdout. When it has not,
    /// and output is being packaged, this stream is captured.
    stdout_set: bool,
    stderr_set: bool,
    /// Whether a run on a terminal also records this child's output into the
    /// run's log. See [`Command::transcribed`].
    transcribed: bool,
}

impl Command {
    /// Build a command for `program`.
    ///
    /// Not public: every command in this crate comes from
    /// [`crate::git_backend::command_without_repo_scope`], which additionally
    /// strips the git environment a child must never inherit. A second
    /// constructor would be a second answer to "what does a child inherit".
    pub(crate) fn new(program: impl AsRef<OsStr>) -> Self {
        Self {
            inner: std::process::Command::new(program),
            stdout_set: false,
            stderr_set: false,
            transcribed: false,
        }
    }

    /// Record this child's output into the run's log as well as showing it.
    ///
    /// On a terminal a child ordinarily writes straight to it, so nothing it
    /// says reaches the log: a release whose suite failed left a log with no
    /// trace of why. A transcribed child's streams are read line by line,
    /// written to the terminal as they arrive and recorded as they are. It is
    /// the caller's choice because a child that needs the terminal itself — a
    /// shell, an editor, a progress display — must not have it taken away; a
    /// build, a test run and an upload do not need one.
    pub fn transcribed(&mut self) -> &mut Self {
        self.transcribed = true;
        self
    }

    pub fn arg(&mut self, arg: impl AsRef<OsStr>) -> &mut Self {
        self.inner.arg(arg);
        self
    }

    pub fn args<I, S>(&mut self, args: I) -> &mut Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<OsStr>,
    {
        self.inner.args(args);
        self
    }

    pub fn env(&mut self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>) -> &mut Self {
        self.inner.env(key, value);
        self
    }

    pub fn envs<I, K, V>(&mut self, vars: I) -> &mut Self
    where
        I: IntoIterator<Item = (K, V)>,
        K: AsRef<OsStr>,
        V: AsRef<OsStr>,
    {
        self.inner.envs(vars);
        self
    }

    pub fn env_remove(&mut self, key: impl AsRef<OsStr>) -> &mut Self {
        self.inner.env_remove(key);
        self
    }

    /// What this command would hand its child, as it has been configured.
    ///
    /// For asking whether a child is told something it needs — which is a
    /// question about the command, and the only alternative is to run one and
    /// read what it printed, which tests the child rather than the decision.
    pub fn configured_env(&self) -> Vec<(String, Option<String>)> {
        self.inner
            .get_envs()
            .map(|(name, value)| {
                (
                    name.to_string_lossy().into_owned(),
                    value.map(|v| v.to_string_lossy().into_owned()),
                )
            })
            .collect()
    }

    pub fn current_dir(&mut self, dir: impl AsRef<Path>) -> &mut Self {
        self.inner.current_dir(dir);
        self
    }

    pub fn stdin(&mut self, cfg: impl Into<Stdio>) -> &mut Self {
        self.inner.stdin(cfg);
        self
    }

    pub fn stdout(&mut self, cfg: impl Into<Stdio>) -> &mut Self {
        self.stdout_set = true;
        self.inner.stdout(cfg);
        self
    }

    pub fn stderr(&mut self, cfg: impl Into<Stdio>) -> &mut Self {
        self.stderr_set = true;
        self.inner.stderr(cfg);
        self
    }

    /// Run the child on a unix process's own terms before it starts.
    ///
    /// # Safety
    ///
    /// The closure runs between fork and exec, where only async-signal-safe
    /// calls are legal. Same contract as [`std::os::unix::process::CommandExt::pre_exec`].
    #[cfg(unix)]
    pub unsafe fn pre_exec<F>(&mut self, f: F) -> &mut Self
    where
        F: FnMut() -> io::Result<()> + Send + Sync + 'static,
    {
        use std::os::unix::process::CommandExt;
        self.inner.pre_exec(f);
        self
    }

    /// Put this child in a group of its own, still attached to the terminal.
    ///
    /// The weaker half of [`Self::detached`], and the one a test suite wants: a
    /// backgrounded pytest that probes the terminal stops on SIGTTIN unless it
    /// is out of the foreground group, and a Ctrl-C meant for the runner should
    /// not scatter across every suite mid-write. What it must NOT do is take
    /// the console away — `detached` does that, and on Windows a build tool
    /// with no console behaves differently from one with a console nobody is
    /// typing at.
    ///
    /// Here rather than at the call site for the same reason `detached` is:
    /// process construction is this type's job, and the two call sites that
    /// reached for `pre_exec` themselves were also the two that would not
    /// compile for Windows.
    #[cfg(unix)]
    pub fn in_its_own_group(&mut self) -> &mut Self {
        use std::os::unix::process::CommandExt;
        // SAFETY: setsid takes no arguments, touches no memory of this
        // process, and is async-signal-safe — which is the whole reason it is
        // one of the calls permitted between fork and exec.
        unsafe {
            self.inner.pre_exec(|| {
                if libc::setsid() == -1 {
                    return Err(io::Error::last_os_error());
                }
                Ok(())
            });
        }
        self
    }

    /// Windows has no sessions. A process group is what Ctrl-C is delivered
    /// to, so a child in one of its own is a child the terminal cannot reach —
    /// the same statement, in the terms that platform has.
    #[cfg(windows)]
    pub fn in_its_own_group(&mut self) -> &mut Self {
        use std::os::windows::process::CommandExt;
        const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
        self.inner.creation_flags(CREATE_NEW_PROCESS_GROUP);
        self
    }

    /// Replace this process with the program.
    ///
    /// Only returns if the program could not be started; the error is what
    /// went wrong. Under `--jsonl` the process is NOT replaced:
    /// exec hands the terminal to a program that knows nothing about the
    /// format this run promised, and every byte after it would arrive
    /// unpackaged. There the child is run captured instead and this process
    /// exits with its status — the same outcome for anything watching, with
    /// the output still in the stream.
    #[cfg(unix)]
    pub fn exec(&mut self) -> io::Error {
        if !sink::is_jsonl() {
            use std::os::unix::process::CommandExt;
            return self.inner.exec();
        }
        match self.status() {
            Ok(status) => {
                let code = status.code().unwrap_or_else(|| {
                    // Killed by a signal: report the shell's convention so the
                    // exit code still says what happened.
                    128 + exit_signal(&status).unwrap_or(0)
                });
                std::process::exit(sink::finish(code));
            }
            Err(error) => error,
        }
    }

    /// What this command does to the environment its child inherits.
    ///
    /// Exposed because the isolation tests assert on it: the variables that
    /// aim a git command at a repository must be CLEARED on every child, and
    /// a test that could not see the clearing could not hold the rule.
    pub fn get_envs(&self) -> std::process::CommandEnvs<'_> {
        self.inner.get_envs()
    }

    /// The argument vector, for reporting.
    pub fn argv(&self) -> Vec<String> {
        let mut argv = vec![self.inner.get_program().to_string_lossy().into_owned()];
        argv.extend(
            self.inner
                .get_args()
                .map(|arg| arg.to_string_lossy().into_owned()),
        );
        argv
    }

    fn cwd(&self) -> Option<String> {
        self.inner
            .get_current_dir()
            .map(|dir| dir.display().to_string())
    }

    /// Run to completion and report how it ended.
    ///
    /// In human mode this is [`std::process::Command::status`] exactly: the
    /// child gets this process's terminal. When output is being packaged, the
    /// streams the caller did not configure are captured and re-emitted, and
    /// the ones it did are left alone.
    /// Put this child in its own session, and out of the terminal's reach.
    ///
    /// For a process that must OUTLIVE the command that starts it — the
    /// workspace daemon. Without it the daemon dies with the shell that
    /// happened to start it and takes the terminal's Ctrl-C with it, which is
    /// the opposite of what a daemon is for.
    ///
    /// Here rather than at the call site because this is process construction,
    /// and process construction is this type's job: a caller reaching for
    /// `std::process::Command` to get at `pre_exec` is a caller stepping
    /// outside the one place that decides what a child inherits.
    #[cfg(unix)]
    pub fn detached(&mut self) -> &mut Self {
        use std::os::unix::process::CommandExt;
        // SAFETY: setsid takes no arguments, touches no memory of this
        // process, and is async-signal-safe — which is the whole reason it is
        // one of the calls permitted between fork and exec.
        unsafe {
            self.inner.pre_exec(|| {
                if libc::setsid() == -1 {
                    return Err(io::Error::last_os_error());
                }
                Ok(())
            });
        }
        self
    }

    /// Windows has no sessions; the equivalent is a process with no console
    /// and its own group, so the terminal's Ctrl-C does not reach it.
    #[cfg(windows)]
    pub fn detached(&mut self) -> &mut Self {
        use std::os::windows::process::CommandExt;
        const DETACHED_PROCESS: u32 = 0x0000_0008;
        const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
        self.inner
            .creation_flags(DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP);
        self
    }

    pub fn status(&mut self) -> io::Result<ExitStatus> {
        let jsonl = sink::is_jsonl();
        if !reads_streams(jsonl, self.transcribed, sink::transcribing()) {
            return self.inner.status();
        }
        // On a terminal the lines read are also written to it, as the child
        // would have; in JSONL they are records and nothing else.
        let echo = !jsonl;

        let id = sink::next_subprocess_id();
        let argv = self.argv();
        let cwd = self.cwd();
        let started = Instant::now();

        let capture_stdout = !self.stdout_set;
        let capture_stderr = !self.stderr_set;
        if capture_stdout {
            self.inner.stdout(Stdio::piped());
        }
        if capture_stderr {
            self.inner.stderr(Stdio::piped());
        }

        let mut child = self.inner.spawn()?;
        sink::emit(Record::SubprocessStarted {
            id,
            argv,
            cwd,
            pid: child.id(),
        });

        let out_reader = capture_stdout.then(|| {
            let pipe = child.stdout.take().expect("stdout was configured as piped");
            std::thread::spawn(move || sink::pump(id, Stream::Stdout, pipe, echo))
        });
        let err_reader = capture_stderr.then(|| {
            let pipe = child.stderr.take().expect("stderr was configured as piped");
            std::thread::spawn(move || sink::pump(id, Stream::Stderr, pipe, echo))
        });

        let status = child.wait()?;
        // Both pipes are drained before the child is reported finished: a
        // process exiting does not mean its last lines have been read.
        if let Some(reader) = out_reader {
            let _ = reader.join();
        }
        if let Some(reader) = err_reader {
            let _ = reader.join();
        }

        sink::finished_child(id, &status, started);
        Ok(status)
    }

    /// Run to completion and hand back what it wrote.
    ///
    /// The bytes belong to the caller in both modes — this captures either
    /// way, so nothing reaches the terminal to package. The run is still
    /// announced, because "wsb is waiting on cargo" is exactly what a consumer
    /// watching a long operation needs to know.
    pub fn output(&mut self) -> io::Result<Output> {
        if !sink::is_jsonl() {
            return self.inner.output();
        }
        let id = sink::next_subprocess_id();
        let started = Instant::now();
        // Spawned and waited on here rather than through `Command::output`,
        // which owns the child and never lets go of it: the pid is only
        // knowable between those two steps, and a running child nobody can
        // name is a running child nobody can stop. The redirections are the
        // ones `output` sets for itself.
        self.inner.stdin(Stdio::null());
        self.inner.stdout(Stdio::piped());
        self.inner.stderr(Stdio::piped());
        let child = self.inner.spawn()?;
        sink::emit(Record::SubprocessStarted {
            id,
            argv: self.argv(),
            cwd: self.cwd(),
            pid: child.id(),
        });
        let result = child.wait_with_output();
        if let Ok(output) = &result {
            sink::finished_child(id, &output.status, started);
        }
        result
    }

    /// Start the child and return it, without waiting.
    ///
    /// The caller owns the pipes from here, so it owns reporting what comes
    /// out of them. Announced for the same reason as [`Command::output`].
    pub fn spawn(&mut self) -> io::Result<Child> {
        if !sink::is_jsonl() {
            return self.inner.spawn();
        }
        let id = sink::next_subprocess_id();
        // Announced AFTER the spawn, because a spawn that fails started
        // nothing — the announcement used to come first and left a child
        // reported as running that never existed.
        let child = self.inner.spawn()?;
        sink::emit(Record::SubprocessStarted {
            id,
            argv: self.argv(),
            cwd: self.cwd(),
            pid: child.id(),
        });
        Ok(child)
    }

    /// Start a program this process wrote a moment ago.
    ///
    /// `ETXTBSY` — "Text file busy" — is what the kernel answers when a file
    /// open for writing is executed, and a multithreaded process that both
    /// writes executables and spawns children hits it without doing anything
    /// wrong. One thread creates the file and writes it; another thread forks
    /// for a child of its own, and that fork duplicates every open descriptor
    /// including the write handle to the new file. Between that fork and the
    /// child's `exec` — microseconds — the file is open for writing in a
    /// process that exists, so executing it fails.
    ///
    /// The descriptor is close-on-exec, so the window shuts by itself. It is
    /// not a condition to report to anyone and not one anything can prevent
    /// from this side: `posix_spawn` avoids it, and setting a working
    /// directory or an environment on a child is enough to make the standard
    /// library fall back to `fork`.
    ///
    /// So it is waited out, and ONLY it. Every other refusal — a file that is
    /// not executable, an interpreter that is not there, a path that is wrong
    /// — is returned at once and unchanged, because those do not stop being
    /// true and a retry would only make them take longer to report.
    ///
    /// Found by TEST9916 failing about once in twenty full runs of the test
    /// binary with `ExecutableFileBusy`, on a hook written four lines above.
    pub fn spawn_just_written(&mut self) -> io::Result<Child> {
        // Five attempts over roughly fifty milliseconds. The window is one
        // `fork`-to-`exec`, so the first retry almost always wins; the rest
        // are for a machine under a load heavy enough to stretch it.
        for attempt in 0..5 {
            match self.spawn() {
                Err(busy) if busy.kind() == io::ErrorKind::ExecutableFileBusy => {
                    std::thread::sleep(std::time::Duration::from_millis(2 << attempt));
                }
                other => return other,
            }
        }
        self.spawn()
    }
}

#[cfg(test)]
mod spawn_tests {
    use super::*;

    /// TEST12322: a transcribed child's output reaches the run's log on a
    /// terminal too; any other child keeps the terminal.
    ///
    /// On a terminal every child wrote straight to it, so a release whose
    /// suite failed left a log with no trace of why.
    #[test]
    fn test12322_a_transcribed_child_is_read_into_the_log() {
        assert!(reads_streams(false, true, true), "a transcribed child with a log is read");
        assert!(!reads_streams(false, false, true), "an untranscribed child keeps the terminal");
        assert!(!reads_streams(false, true, false), "nothing to record into: left on the terminal");
        assert!(reads_streams(true, false, false), "JSONL reads every child");
    }

    /// TEST11530: a program whose file is still open for writing is waited
    /// for, not reported as broken.
    ///
    /// The condition, arranged exactly: a writable descriptor is held open on
    /// the executable while a spawn is attempted, and released from another
    /// thread a moment later. That is the same state a fork in a sibling
    /// thread leaves the file in, and it is why TEST9916 failed about once in
    /// twenty full runs with `ExecutableFileBusy` on a hook written four lines
    /// above it.
    #[cfg(unix)]
    #[test]
    fn test11530_a_busy_executable_is_waited_for() {
        use std::io::Write;
        use std::os::unix::fs::PermissionsExt;

        let dir = tempfile::tempdir().expect("a scratch directory");
        let program = dir.path().join("program");
        let mut written = std::fs::File::create(&program).expect("the file is created");
        written.write_all(b"#!/bin/sh\nexit 0\n").expect("written");
        written.flush().expect("flushed");
        std::fs::set_permissions(&program, std::fs::Permissions::from_mode(0o755))
            .expect("executable");

        // Still open for writing. A kernel that enforces `ETXTBSY` refuses to
        // execute it in this state, which is exactly what a sibling thread's
        // fork does to a file this thread has just created.
        //
        // NOT EVERY KERNEL DOES. macOS 27 executes a file that is open for
        // writing, so the condition cannot be arranged here at all — and this
        // used to fail on every run of the suite on such a machine, reporting
        // the retry logic as broken when what was broken was the fixture's
        // assumption about the operating system.
        //
        // Skipped rather than asserted, and only after CHECKING that the state
        // is unreachable. A skip written as an OS name would go stale the
        // moment a release changed its mind, in either direction; this asks.
        let arranged = Command::new(&program).spawn(); // SPAWNS-NO-GIT: a fixture executable this test just wrote into a temporary directory
        match arranged {
            Err(busy) if busy.kind() == std::io::ErrorKind::ExecutableFileBusy => {}
            Ok(mut ran) => {
                // The kernel does not hold this against us. There is no busy
                // executable to wait for, so there is nothing here to prove.
                let _ = ran.wait();
                return;
            }
            Err(other) => panic!(
                "the fixture failed for a reason that is not the one under test: {other}"
            ),
        }

        let holder = std::thread::spawn(move || {
            std::thread::sleep(std::time::Duration::from_millis(15));
            drop(written);
        });
        let mut child = Command::new(&program) // SPAWNS-NO-GIT: the same temporary fixture, through the retrying spawn
            .spawn_just_written()
            .expect("a busy executable is waited for, not refused");
        assert!(child.wait().expect("it finishes").success());
        holder.join().expect("the descriptor is released");
    }

    /// TEST11531: every other refusal is returned at once and unchanged.
    ///
    /// The whole point of naming the errno. A retry loop that swallowed "no
    /// such file" would turn a wrong path into a slow wrong path, and the
    /// message a reader gets would be about waiting rather than about the
    /// file that is not there.
    #[test]
    fn test11531_a_refusal_that_is_not_busy_is_returned_immediately() {
        let dir = tempfile::tempdir().expect("a scratch directory");
        let missing = dir.path().join("not-here");

        let started = std::time::Instant::now();
        let error = Command::new(&missing) // SPAWNS-NO-GIT: a path inside a temporary directory that deliberately does not exist
            .spawn_just_written()
            .map(|_| ())
            .expect_err("a program that does not exist cannot be spawned");
        assert_eq!(error.kind(), std::io::ErrorKind::NotFound, "{error}");
        assert!(
            started.elapsed() < std::time::Duration::from_millis(50),
            "a refusal that will never change was retried for {:?}",
            started.elapsed()
        );
    }
}