use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::time::{Duration, Instant};
use tokio::io::AsyncReadExt;
use tokio::process::Command;
#[derive(Debug, thiserror::Error)]
pub enum ProcessError {
#[error("cannot run '{program}': {source}")]
Spawn {
program: String,
#[source]
source: std::io::Error,
},
#[error("working directory {path} does not exist")]
MissingWorkingDirectory {
path: PathBuf,
},
#[error("cannot read output of '{program}': {source}")]
Io {
program: String,
#[source]
source: std::io::Error,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Outcome {
Exited(i32),
Signalled(i32),
TimedOut,
}
impl Outcome {
pub fn is_success(self) -> bool {
matches!(self, Outcome::Exited(0))
}
pub fn exit_code(self) -> Option<i32> {
match self {
Outcome::Exited(code) => Some(code),
_ => None,
}
}
pub fn signal_name(self) -> Option<&'static str> {
match self {
Outcome::Signalled(signal) => Some(signal_name(signal)),
_ => None,
}
}
pub fn description(self) -> String {
match self {
Outcome::Exited(0) => "exited successfully".to_owned(),
Outcome::Exited(code) => format!("exited with code {code}"),
Outcome::Signalled(signal) => {
format!("killed by signal {signal} ({})", signal_name(signal))
}
Outcome::TimedOut => "timed out".to_owned(),
}
}
}
pub fn signal_name(signal: i32) -> &'static str {
match signal {
1 => "SIGHUP",
2 => "SIGINT",
3 => "SIGQUIT",
4 => "SIGILL",
5 => "SIGTRAP",
6 => "SIGABRT",
7 => "SIGBUS",
8 => "SIGFPE",
9 => "SIGKILL",
11 => "SIGSEGV",
13 => "SIGPIPE",
14 => "SIGALRM",
15 => "SIGTERM",
_ => "unknown",
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommandSpec {
pub program: PathBuf,
pub args: Vec<String>,
pub working_directory: Option<PathBuf>,
pub timeout: Option<Duration>,
pub stdin: Option<String>,
pub env: Vec<(String, String)>,
}
impl CommandSpec {
pub fn new(program: impl Into<PathBuf>) -> Self {
Self {
program: program.into(),
args: Vec::new(),
working_directory: None,
timeout: None,
stdin: None,
env: Vec::new(),
}
}
pub fn arg(mut self, arg: impl Into<String>) -> Self {
self.args.push(arg.into());
self
}
pub fn args<I, S>(mut self, args: I) -> Self
where
I: IntoIterator<Item = S>,
S: Into<String>,
{
self.args.extend(args.into_iter().map(Into::into));
self
}
pub fn working_directory(mut self, path: impl Into<PathBuf>) -> Self {
self.working_directory = Some(path.into());
self
}
pub fn timeout(mut self, timeout: Duration) -> Self {
self.timeout = Some(timeout);
self
}
pub fn stdin(mut self, text: impl Into<String>) -> Self {
self.stdin = Some(text.into());
self
}
pub fn env(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
self.env.push((key.into(), value.into()));
self
}
pub fn display(&self) -> String {
let mut parts = vec![self.program.display().to_string()];
parts.extend(self.args.iter().map(|arg| {
if arg.contains(' ') {
format!("\"{arg}\"")
} else {
arg.clone()
}
}));
parts.join(" ")
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProcessOutput {
pub outcome: Outcome,
pub stdout: String,
pub stderr: String,
pub duration: Duration,
pub command: String,
}
impl ProcessOutput {
pub fn is_success(&self) -> bool {
self.outcome.is_success()
}
pub fn combined(&self) -> String {
let mut combined = self.stdout.clone();
if !self.stderr.is_empty() {
if !combined.is_empty() && !combined.ends_with('\n') {
combined.push('\n');
}
combined.push_str(&self.stderr);
}
combined
}
}
pub async fn run(spec: &CommandSpec) -> Result<ProcessOutput, ProcessError> {
let started = Instant::now();
let program = spec.program.display().to_string();
if let Some(directory) = &spec.working_directory {
if !directory.is_dir() {
return Err(ProcessError::MissingWorkingDirectory {
path: directory.clone(),
});
}
}
let mut command = Command::new(&spec.program);
command
.args(&spec.args)
.stdin(if spec.stdin.is_some() {
Stdio::piped()
} else {
Stdio::null()
})
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.kill_on_drop(true);
if let Some(directory) = &spec.working_directory {
command.current_dir(directory);
}
for (key, value) in &spec.env {
command.env(key, value);
}
let mut child = command.spawn().map_err(|source| ProcessError::Spawn {
program: program.clone(),
source,
})?;
if let (Some(text), Some(mut pipe)) = (spec.stdin.as_ref(), child.stdin.take()) {
use tokio::io::AsyncWriteExt;
let _ = pipe.write_all(text.as_bytes()).await;
let _ = pipe.shutdown().await;
}
let mut stdout_pipe = child.stdout.take();
let mut stderr_pipe = child.stderr.take();
let stdout_task = tokio::spawn(async move {
let mut buffer = Vec::new();
if let Some(pipe) = stdout_pipe.as_mut() {
let _ = pipe.read_to_end(&mut buffer).await;
}
buffer
});
let stderr_task = tokio::spawn(async move {
let mut buffer = Vec::new();
if let Some(pipe) = stderr_pipe.as_mut() {
let _ = pipe.read_to_end(&mut buffer).await;
}
buffer
});
let (outcome, status) = match spec.timeout {
Some(limit) => match tokio::time::timeout(limit, child.wait()).await {
Ok(status) => (None, status),
Err(_) => {
let _ = child.start_kill();
let status = child.wait().await;
(Some(Outcome::TimedOut), status)
}
},
None => (None, child.wait().await),
};
let status = status.map_err(|source| ProcessError::Io {
program: program.clone(),
source,
})?;
let outcome = outcome.unwrap_or_else(|| outcome_from_status(&status));
let stdout = stdout_task.await.unwrap_or_default();
let stderr = stderr_task.await.unwrap_or_default();
Ok(ProcessOutput {
outcome,
stdout: String::from_utf8_lossy(&stdout).into_owned(),
stderr: String::from_utf8_lossy(&stderr).into_owned(),
duration: started.elapsed(),
command: spec.display(),
})
}
fn outcome_from_status(status: &std::process::ExitStatus) -> Outcome {
#[cfg(unix)]
{
use std::os::unix::process::ExitStatusExt;
if let Some(signal) = status.signal() {
return Outcome::Signalled(signal);
}
}
Outcome::Exited(status.code().unwrap_or(-1))
}
pub fn is_available(program: &Path) -> bool {
if program.components().count() > 1 {
return program.is_file();
}
let Some(path) = std::env::var_os("PATH") else {
return false;
};
std::env::split_paths(&path).any(|directory| directory.join(program).is_file())
}
#[cfg(test)]
mod tests {
use super::*;
const TRUE: &str = "/usr/bin/true";
const FALSE: &str = "/usr/bin/false";
fn exists(path: &str) -> bool {
Path::new(path).is_file()
}
#[tokio::test]
async fn a_successful_command_reports_success() {
if !exists(TRUE) {
return;
}
let output = run(&CommandSpec::new(TRUE)).await.expect("run");
assert_eq!(output.outcome, Outcome::Exited(0));
assert!(output.is_success());
}
#[tokio::test]
async fn a_failing_command_is_a_result_not_an_error() {
if !exists(FALSE) {
return;
}
let output = run(&CommandSpec::new(FALSE)).await.expect("run");
assert_eq!(output.outcome, Outcome::Exited(1));
assert!(!output.is_success());
}
#[tokio::test]
async fn standard_output_is_captured() {
let spec = CommandSpec::new("/usr/bin/printf").arg("hello world");
if !exists("/usr/bin/printf") {
return;
}
let output = run(&spec).await.expect("run");
assert_eq!(output.stdout, "hello world");
assert!(output.stderr.is_empty());
}
#[tokio::test]
async fn arguments_are_passed_without_shell_interpretation() {
if !exists("/usr/bin/printf") {
return;
}
let hostile = "%s\n";
let spec = CommandSpec::new("/usr/bin/printf")
.arg(hostile)
.arg("; rm -rf / && echo pwned `id` $(whoami)");
let output = run(&spec).await.expect("run");
assert_eq!(output.stdout, "; rm -rf / && echo pwned `id` $(whoami)\n");
}
#[tokio::test]
async fn a_missing_program_reports_a_spawn_error() {
let spec = CommandSpec::new("/nonexistent/definitely-not-here");
let error = run(&spec).await.expect_err("must fail");
assert!(matches!(error, ProcessError::Spawn { .. }));
assert!(error.to_string().contains("definitely-not-here"));
}
#[tokio::test]
async fn a_missing_working_directory_is_reported_before_spawning() {
if !exists(TRUE) {
return;
}
let spec = CommandSpec::new(TRUE).working_directory("/nonexistent/directory");
let error = run(&spec).await.expect_err("must fail");
assert!(matches!(
error,
ProcessError::MissingWorkingDirectory { .. }
));
}
#[tokio::test]
async fn a_runaway_process_is_killed_at_its_timeout() {
if !exists("/usr/bin/sleep") {
return;
}
let spec = CommandSpec::new("/usr/bin/sleep")
.arg("30")
.timeout(Duration::from_millis(150));
let started = Instant::now();
let output = run(&spec).await.expect("run");
assert_eq!(output.outcome, Outcome::TimedOut);
assert!(
started.elapsed() < Duration::from_secs(5),
"the timeout must actually stop the process"
);
}
#[tokio::test]
async fn a_process_finishing_inside_its_timeout_is_not_killed() {
if !exists(TRUE) {
return;
}
let spec = CommandSpec::new(TRUE).timeout(Duration::from_secs(30));
let output = run(&spec).await.expect("run");
assert_eq!(output.outcome, Outcome::Exited(0));
}
#[tokio::test]
async fn large_output_does_not_deadlock() {
if !exists("/usr/bin/yes") || !exists("/usr/bin/head") {
return;
}
let spec = CommandSpec::new("/usr/bin/head")
.args(["-c", "2000000", "/dev/zero"])
.timeout(Duration::from_secs(20));
let output = run(&spec).await.expect("run");
assert_eq!(output.outcome, Outcome::Exited(0));
assert_eq!(output.stdout.len(), 2_000_000);
}
#[tokio::test]
async fn standard_input_is_delivered() {
if !exists("/usr/bin/cat") {
return;
}
let spec = CommandSpec::new("/usr/bin/cat").stdin("mov rax, 60\n");
let output = run(&spec).await.expect("run");
assert_eq!(output.stdout, "mov rax, 60\n");
}
#[tokio::test]
async fn the_working_directory_is_honoured() {
let dir = tempfile::tempdir().expect("temp dir");
if !exists("/usr/bin/pwd") {
return;
}
let spec = CommandSpec::new("/usr/bin/pwd").working_directory(dir.path());
let output = run(&spec).await.expect("run");
let reported = std::fs::canonicalize(output.stdout.trim()).expect("canonicalize");
let expected = std::fs::canonicalize(dir.path()).expect("canonicalize");
assert_eq!(reported, expected);
}
#[tokio::test]
async fn environment_variables_are_passed_through() {
if !exists("/usr/bin/env") {
return;
}
let spec = CommandSpec::new("/usr/bin/env").env("RATASM_TEST_VALUE", "42");
let output = run(&spec).await.expect("run");
assert!(output.stdout.contains("RATASM_TEST_VALUE=42"));
}
#[tokio::test]
async fn a_signalled_process_reports_its_signal() {
if !exists("/usr/bin/sh") {
return;
}
let spec = CommandSpec::new("/usr/bin/sh").args(["-c", "kill -SEGV $$"]);
let output = run(&spec).await.expect("run");
assert_eq!(output.outcome, Outcome::Signalled(11));
assert_eq!(output.outcome.signal_name(), Some("SIGSEGV"));
assert!(output.outcome.description().contains("SIGSEGV"));
}
#[test]
fn outcome_descriptions_are_readable() {
assert_eq!(Outcome::Exited(0).description(), "exited successfully");
assert_eq!(Outcome::Exited(2).description(), "exited with code 2");
assert_eq!(Outcome::TimedOut.description(), "timed out");
assert!(Outcome::Signalled(8).description().contains("SIGFPE"));
assert_eq!(Outcome::Exited(3).exit_code(), Some(3));
assert_eq!(Outcome::TimedOut.exit_code(), None);
}
#[test]
fn the_display_string_is_readable_and_quotes_spaces() {
let spec = CommandSpec::new("nasm")
.args(["-f", "elf64"])
.arg("my source.asm");
assert_eq!(spec.display(), "nasm -f elf64 \"my source.asm\"");
}
#[test]
fn availability_finds_programs_on_the_path() {
assert!(is_available(Path::new("sh")) || is_available(Path::new("/bin/sh")));
assert!(!is_available(Path::new(
"definitely-not-a-real-program-xyz"
)));
assert!(!is_available(Path::new("/nonexistent/path/to/tool")));
}
#[test]
fn combined_output_joins_both_streams() {
let output = ProcessOutput {
outcome: Outcome::Exited(1),
stdout: "out".to_owned(),
stderr: "err".to_owned(),
duration: Duration::ZERO,
command: String::new(),
};
assert_eq!(output.combined(), "out\nerr");
}
#[test]
fn signal_names_cover_the_ones_a_debugger_sees() {
assert_eq!(signal_name(11), "SIGSEGV");
assert_eq!(signal_name(8), "SIGFPE");
assert_eq!(signal_name(4), "SIGILL");
assert_eq!(signal_name(5), "SIGTRAP");
assert_eq!(signal_name(6), "SIGABRT");
assert_eq!(signal_name(999), "unknown");
}
}