clingwrap 0.7.0

//! Run a [`Command`], handling errors in a way that is convenient for
//! the caller to handle. Specifically, the error type returned by
//! this module distinguishes between "program doesn't exist" and "no
//! permission to execute program" and "program ran, but failed". See
//! [`CommandError`] for all possible errors.
//!
//! # Example
//! ```
//! use std::process::Command;
//! use clingwrap::runner::*;
//! let mut cmd = Command::new("echo");
//! cmd.arg("hello").arg("world");
//! let mut runner = CommandRunner::new(cmd);
//! runner.capture_stdout();
//! match runner.execute() {
//!     Ok(output) => {
//!         let stdout = String::from_utf8_lossy(&output.stdout).to_string();
//!         assert_eq!(stdout, "hello world\n");
//!     }
//!     Err(err)  => eprintln!("{err}"),
//! }
//! ```

use std::{
    ffi::{OsStr, OsString},
    fs::File,
    io::{PipeReader, Read, Seek, Write, pipe},
    os::unix::ffi::OsStrExt,
    path::PathBuf,
    process::{Command, Output, Stdio},
};

// On Unix, we need this to find out which signal terminated the
// program.
#[cfg(unix)]
use std::os::unix::process::ExitStatusExt;

use log::trace;
use tempfile::tempfile;

// The list of bytes that are safe to not quote for a shell.
const SAFE_BYTES: &[u8] =
    b"abcdefghijklmnopqrstuvwxyABCDEFGHIJKLMNOPQRSTUVWXY01234567890-_./@=%:+,";

#[derive(Debug)]
enum Stdin {
    Null,
    Inherit,
    Feed(Vec<u8>),
}

/// Run a
/// [`Command`](https://doc.rust-lang.org/std/process/struct.Command.html)
/// that has already been set up and return a useful error type for
/// when anything goes wrong.
#[derive(Debug)]
pub struct CommandRunner {
    // The command to run.
    cmd: Command,

    // How should stdin be handled?
    stdin: Stdin,

    // Handle for reading from child stdout when we redirect it.
    // We need to keep it open it doesn't get closed.
    stdout: Option<PipeReader>,
}

impl CommandRunner {
    /// Create a new command runner.
    ///
    /// By default, the child process stdin will come from `/dev/null`
    /// or equivalent.
    pub fn new(cmd: Command) -> Self {
        trace!("new CommandRunner: {cmd:#?}");
        trace!("child process stdin is empty, stdout and stderr are inherited");
        Self {
            cmd,
            stdin: Stdin::Null,
            stdout: None,
        }
    }

    /// Let the child process inherit its stdin from the parent process.
    #[mutants::skip]
    pub fn inherit_stdin(&mut self) {
        trace!("run command so it inherits stdin from parent process");
        self.stdin = Stdin::Inherit;
    }

    /// Feed data to the child process via its stdin. This data is
    /// written to a temporary file, in this version, but that may
    /// change to a pipe in a future version of this module. By
    /// default, the child stdin is closed.
    pub fn feed_stdin(&mut self, data: impl Into<Vec<u8>>) {
        let data = data.into();
        trace!("feed child process stdin {} bytes of input", data.len());
        self.stdin = Stdin::Feed(data);
    }

    /// Set up the command to capture the child process stdout.
    /// This method is a convenience wrapper for [`Command:stdout`](std::process::Command::stdout).
    pub fn capture_stdout(&mut self) {
        trace!("capture child process stdout");
        self.cmd.stdout(Stdio::piped());
    }

    /// Set up the command to capture the child process stderr.
    /// This method is a convenience wrapper for [`Command:stderr`](std::process::Command::stderr).
    pub fn capture_stderr(&mut self) {
        trace!("capture child process stderr");
        self.cmd.stderr(Stdio::piped());
    }

    /// Set up the command to capture child process stdout and stderr as
    /// one combined stream. This means if the child writes to stdout,
    /// then to stderr, then to stdout again, the captured output stream
    /// has the tree writes interleaved.
    pub fn combine_stdouterr(&mut self) -> Result<(), CommandError> {
        trace!("capture child process combined stdout and stderr");
        let (r, w) = pipe().map_err(CommandError::PipeCapture)?;
        self.stdout = Some(r);
        self.cmd
            .stdout(w.try_clone().map_err(CommandError::PipeClone)?);
        self.cmd.stderr(w);
        Ok(())
    }

    /// Execute the command in a child process. Wait for it to terminate.
    #[mutants::skip]
    pub fn execute(mut self) -> Result<Output, CommandError> {
        if let Some(dirname) = self.cmd.get_current_dir() {
            if !dirname.exists() {
                return Err(CommandError::NoSuchDir(dirname.to_path_buf()));
            }
        }

        let program_name = self.cmd.get_program().to_os_string();

        match &self.stdin {
            Stdin::Null => {
                self.cmd.stdin(Stdio::null());
            }
            Stdin::Inherit => {
                self.cmd.stdin(Stdio::inherit());
            }
            Stdin::Feed(data) => {
                self.cmd
                    .stdin(write_temp_file(data).map_err(CommandError::Stdin)?);
            }
        }

        trace!("spawn child process");
        let r = self.cmd.spawn();
        let mut child = match r {
            // Child process started running OK.
            Ok(child) => child,

            // Program does not exist.
            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
                return Err(CommandError::NoSuchCommand(program_name));
            }

            // We lack permission to run program.
            Err(err) if err.kind() == std::io::ErrorKind::PermissionDenied => {
                return Err(CommandError::NoPermission(program_name));
            }

            // Other problem prevented the program from starting.
            Err(err) => {
                return Err(CommandError::Other {
                    program_name,
                    source: err,
                });
            }
        };

        trace!("wait for child process to terminate");
        let result = if let Some(mut combined) = self.stdout.take() {
            // We have to drop the `Command` here. Otherwise the child
            // process stdout has two write handles: one in the
            // `Command` and in the child process. This means we will
            // never hit EOF when reading child stdout via the read
            // end of the stdout pipe (`combined` here).
            std::mem::drop(self.cmd);
            let mut output = Vec::new();
            combined
                .read_to_end(&mut output)
                .map_err(CommandError::ReadCombined)?;
            match child.wait() {
                Err(err) => Err(err),
                Ok(status) => Ok(Output {
                    status,
                    stdout: output,
                    stderr: vec![],
                }),
            }
        } else {
            child.wait_with_output()
        };

        match result {
            // Child terminated, but it may have failed.
            Ok(output) => {
                // Did the child terminate due to a signal?
                #[cfg(unix)]
                if let Some(signal) = output.status.signal() {
                    return Err(CommandError::KilledBySignal {
                        program_name,
                        signal,
                    });
                }

                // Did the child terminate with a non-zero exit code?
                if let Some(code) = output.status.code() {
                    if code != 0 {
                        return Err(CommandError::command_failed(program_name, output));
                    }
                }

                // At this point we know the child terminated, because we
                // used `wait_with_output`. We also know that it didn't
                // fail, because it didn't get killed by a signal, and it
                // didn't have a non-zero exit code.
                assert!(output.status.success());

                Ok(output)
            }

            // Something unexpected went wrong.
            Err(err) => Err(CommandError::Other {
                program_name,
                source: err,
            }),
        }
    }
}

fn write_temp_file(data: &[u8]) -> Result<File, std::io::Error> {
    let mut tmp = tempfile()?;
    tmp.write_all(data)?;
    tmp.rewind()?;
    Ok(tmp)
}

/// All possible errors from using [`CommandRunner`].
#[derive(Debug, thiserror::Error)]
pub enum CommandError {
    /// The program is supposed to be run in a directory, but that
    /// directory does not exist.
    #[error("directory does not exist: {0}")]
    NoSuchDir(PathBuf),

    /// The program doesn't exist. Or, possibly, the program specifies
    /// an interpreter or shared library that does not exist. The
    /// operating system doesn't tell us which.
    #[error("command does not exist: {0:?}")]
    NoSuchCommand(OsString),

    /// The program exists, but we lack the permission to run it. On
    /// Unix, this means the program file lacks the x bit for us.
    #[error("no permission to run command: {0:?}")]
    NoPermission(OsString),

    /// The program ran, but terminated with a non-zero exit code. Note
    /// that this error variant includes any captured stdout and stderr
    /// output.
    #[error("command failed: {program_name:?}")]
    CommandFailed {
        /// Name of program.
        program_name: OsString,
        /// Output from program, if captured.
        output: Box<Output>,
    },

    /// The program ran, but was terminated by a signal.
    #[cfg(unix)]
    #[error("command {program_name:?} was terminated by signal number {signal:?}")]
    KilledBySignal {
        /// Name of program.
        program_name: OsString,
        /// Signal that caused program to terminate
        signal: i32,
    },

    /// There was some other error. There can be any number of errors,
    /// and over time they can vary. We can't know everything, so we
    /// have a catchall error variant to handle the unknowns.
    #[error("unknown error while running command: {program_name:?}")]
    Other {
        /// Name of program.
        program_name: OsString,
        /// Underlying error.
        #[source]
        source: std::io::Error,
    },

    /// Can't write data to be fed to stdin to a temporary file.
    #[error("failed to create temporary file for stdin")]
    Stdin(#[source] std::io::Error),

    /// Can't create an anonymous pipe for capturing stdout and stderr.
    #[error("failed to create pipe for capturing output")]
    PipeCapture(#[source] std::io::Error),

    /// Can't clone write end of pipe.
    #[error("failed to clone write end of anonymous pipe")]
    PipeClone(#[source] std::io::Error),

    /// Can't read combined output of child process.
    #[error("failed to read child process combined output")]
    ReadCombined(#[source] std::io::Error),
}

impl CommandError {
    fn command_failed<O: Into<OsString>>(program_name: O, output: Output) -> Self {
        Self::CommandFailed {
            program_name: program_name.into(),
            output: Box::new(output),
        }
    }
}

/// Quote an OS string so it's parsed as the input string in the Unix Bourne shell.
pub fn shell_quote(s: &OsStr) -> OsString {
    // We do not try to minimize quoting. Out approach is simple, and borrowed
    // from Python shlex.quote: a single quote is quoted using double quotes,
    // and everything else is quoted using single quotes. In addition, if the
    // input consists only of safe characters, it is not quoted at all.

    let out = if s.as_bytes().iter().all(|byte| SAFE_BYTES.contains(byte)) {
        // If input consists only of safe bytes, no need to quote.
        s.as_bytes().to_vec()
    } else {
        // There's at least one unsafe byte. Quote everything. We don't need
        // to track if we're inside single quotes: we're always inside them.

        const SINGLE: u8 = b'\'';

        let mut out = vec![SINGLE];

        for byte in s.as_bytes() {
            // If we encounter a single quote, end current single-quote part, insert
            // double-quoted single quote, and start a new single-quote part.
            if *byte == SINGLE {
                out.push(SINGLE);
                out.push(b'"');
                out.push(SINGLE);
                out.push(b'"');
                out.push(SINGLE);
            } else {
                out.push(*byte);
            }
        }
        out.push(SINGLE);

        out
    };

    unsafe { OsString::from_encoded_bytes_unchecked(out) }
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod test {
    use std::os::unix::ffi::OsStrExt;

    use tempfile::tempdir;

    use super::*;

    fn quote(bytes: &[u8]) -> Vec<u8> {
        shell_quote(OsStr::from_bytes(bytes))
            .into_encoded_bytes()
            .to_vec()
    }

    #[test]
    fn empty() {
        assert_eq!(quote(b""), b"");
    }

    #[test]
    fn quote_safe_bytes() {
        assert_eq!(quote(SAFE_BYTES), SAFE_BYTES);
    }

    #[test]
    fn minimal_quote_safe() {
        assert_eq!(quote(b"hello"), b"hello");
    }

    #[test]
    fn minimal_quote_unsafe() {
        assert_eq!(quote(b"hello world"), b"'hello world'");
    }

    #[test]
    fn single_quote() {
        assert_eq!(quote(b"'"), b"''\"'\"''");
    }

    #[test]
    fn mix() {
        assert_eq!(
            quote(b"it's a !#$ travesty"),
            b"'it'\"'\"'s a !#$ travesty'"
        );
    }

    #[test]
    fn run_inherit_stdin_combine_outputs() {
        let mut cmd = Command::new("echo");
        cmd.args(["hello", "world"]);
        let mut runner = CommandRunner::new(cmd);
        runner.combine_stdouterr().unwrap();
        let output = runner.execute().unwrap();
        eprintln!("{output:#?}");
        assert!(output.status.success());
        assert_eq!(output.stdout, b"hello world\n");
        assert!(output.stderr.is_empty());
    }

    #[test]
    fn run_feed_stdin_capture_outputs_separately() {
        let cmd = Command::new("cat");
        let mut runner = CommandRunner::new(cmd);
        runner.feed_stdin(b"hello");
        runner.capture_stdout();
        runner.capture_stderr();
        let output = runner.execute().unwrap();
        eprintln!("{output:#?}");
        assert!(output.status.success());
        assert_eq!(output.stdout, b"hello");
        assert!(output.stderr.is_empty());
    }

    #[test]
    fn capture_stderr() {
        let mut cmd = Command::new("sh");
        cmd.arg("-c");
        cmd.arg("echo foo 1>&2");

        let mut runner = CommandRunner::new(cmd);
        runner.capture_stderr();

        let output = runner.execute().unwrap();
        assert_eq!(output.stderr, b"foo\n");
    }

    #[test]
    fn run_non_exec() {
        let tmp = tempdir().unwrap();
        let bin = tmp.path().join("noexec.sh");
        std::fs::write(&bin, b"").unwrap();
        let cmd = Command::new(&bin);
        let runner = CommandRunner::new(cmd);
        let r = runner.execute();
        eprintln!("r={r:#?}");
        assert!(matches!(r, Err(CommandError::NoPermission(_))));
    }

    #[test]
    fn run_nonexistent() {
        let cmd = Command::new("./does-not-exist");
        let runner = CommandRunner::new(cmd);
        let r = runner.execute();
        eprintln!("r={r:#?}");
        assert!(matches!(r, Err(CommandError::NoSuchCommand(_))));
    }

    #[test]
    #[allow(clippy::panic)]
    fn current_dir_does_not_exist() {
        let dirname = PathBuf::from("/does/not/exist");
        let mut cmd = Command::new("true");
        cmd.current_dir(&dirname);
        let runner = CommandRunner::new(cmd);
        let r = runner.execute();
        eprintln!("r={r:#?}");
        match r {
            Err(CommandError::NoSuchDir(actual)) if actual == dirname => (),
            _ => panic!("unexpected result"),
        }
    }
}