use std::io;
use std::process::{ExitStatus, Output, Stdio};
use std::time::Duration;
use tokio::io::{AsyncRead, AsyncReadExt};
use tokio::process::{Child, Command};
use tokio::time::Instant;
use crate::{CancellationToken, Error, OperationOptions, Result};
pub(crate) const STDERR_LIMIT: u64 = 1024 * 1024;
const TRUNCATED: &[u8] = b"\n[output truncated]\n";
#[derive(Default)]
pub(crate) struct Operation {
deadline: Option<(Instant, u64)>,
cancel: Option<CancellationToken>,
}
impl Operation {
pub(crate) fn new(options: OperationOptions) -> Self {
let deadline = options
.timeout_secs
.filter(|seconds| *seconds > 0)
.and_then(|seconds| {
Some((
Instant::now().checked_add(Duration::from_secs(seconds))?,
seconds,
))
});
Self {
deadline,
cancel: options.cancel_token,
}
}
fn check(&self) -> Result<()> {
if self
.cancel
.as_ref()
.is_some_and(CancellationToken::is_cancelled)
{
return Err(Error::Cancelled);
}
match self.deadline {
Some((deadline, seconds)) if Instant::now() >= deadline => Err(Error::Timeout(seconds)),
_ => Ok(()),
}
}
async fn wait<F: Future>(&self, future: F) -> Result<F::Output> {
let timeout = async {
match self.deadline {
Some((deadline, seconds)) => {
tokio::time::sleep_until(deadline).await;
seconds
}
None => std::future::pending().await,
}
};
let cancel = async {
match &self.cancel {
Some(cancel) => cancel.cancelled().await,
None => std::future::pending().await,
}
};
tokio::select! {
biased;
_ = cancel => Err(Error::Cancelled),
seconds = timeout => Err(Error::Timeout(seconds)),
result = future => Ok(result),
}
}
}
struct ProcessGroup {
leader: Child,
watcher: Child,
}
impl ProcessGroup {
fn spawn(command: &mut Command) -> io::Result<Self> {
let watcher = Command::new("/bin/sh")
.args(["-c", "read line; kill -s KILL 0"])
.stdin(Stdio::piped())
.stdout(Stdio::null())
.stderr(Stdio::null())
.process_group(0)
.kill_on_drop(true)
.spawn()?;
let group = watcher.id().expect("an unwaited child has an id") as libc::pid_t;
let leader = command.env("LC_ALL", "C").process_group(group).spawn()?;
Ok(Self { leader, watcher })
}
}
impl Drop for ProcessGroup {
fn drop(&mut self) {
if let (Some(_), Some(group)) = (self.leader.id(), self.watcher.id()) {
unsafe { libc::killpg(group as libc::pid_t, libc::SIGKILL) };
let _ = self.leader.start_kill();
}
}
}
pub(crate) async fn run<T>(
command: &mut Command,
operation: &Operation,
body: impl AsyncFnOnce(&mut Child) -> Result<T>,
) -> Result<(ExitStatus, T)> {
operation.check()?;
let mut process = ProcessGroup::spawn(command)?;
let value = operation.wait(body(&mut process.leader)).await??;
let status = operation.wait(process.leader.wait()).await??;
let _ = process.watcher.start_kill();
Ok((status, value))
}
pub(crate) async fn collect(reader: impl AsyncRead + Unpin, limit: u64) -> io::Result<Vec<u8>> {
let mut output = Vec::new();
let mut retained = reader.take(limit);
retained.read_to_end(&mut output).await?;
if tokio::io::copy(&mut retained.into_inner(), &mut tokio::io::sink()).await? > 0 {
output.extend_from_slice(TRUNCATED);
}
Ok(output)
}
pub(crate) async fn output(command: &mut Command, operation: &Operation) -> Result<Output> {
let command = command.stdout(Stdio::piped()).stderr(Stdio::piped());
let (status, (stdout, stderr)) = run(command, operation, async |child| {
let stdout = child.stdout.take().expect("stdout is piped");
let stderr = child.stderr.take().expect("stderr is piped");
tokio::try_join!(collect(stdout, u64::MAX), collect(stderr, STDERR_LIMIT))
.map_err(Error::Command)
})
.await?;
Ok(Output {
status,
stdout,
stderr,
})
}
pub(crate) async fn stderr_only(
command: &mut Command,
operation: &Operation,
) -> Result<(ExitStatus, Vec<u8>)> {
let command = command.stdout(Stdio::null()).stderr(Stdio::piped());
run(command, operation, async |child| {
let stderr = child.stderr.take().expect("stderr is piped");
collect(stderr, STDERR_LIMIT).await.map_err(Error::Command)
})
.await
}
#[cfg(test)]
pub(crate) mod tests {
use super::*;
use std::path::PathBuf;
pub(crate) struct Fixture {
directory: tempfile::TempDir,
}
impl Fixture {
pub(crate) fn new() -> Self {
Self {
directory: tempfile::tempdir().unwrap(),
}
}
pub(crate) fn path(&self, name: &str) -> PathBuf {
self.directory.path().join(name)
}
pub(crate) fn command(&self, script: &str) -> Command {
let mut command = Command::new("/bin/sh");
command
.args(["-c", script, "keyring-fixture"])
.arg(self.directory.path());
command
}
pub(crate) async fn ready(&self) {
let path = self.path("ready");
until(|| path.exists(), "fixture process did not become ready").await;
}
fn pid(&self, name: &str) -> u32 {
std::fs::read_to_string(self.path(name))
.unwrap()
.trim()
.parse()
.unwrap()
}
pub(crate) async fn stopped(&self) {
let mut names = vec!["parent"];
if self.path("grandchild").exists() {
names.push("grandchild");
}
for name in names {
let pid = self.pid(name);
until(|| !running(pid), "fixture process survived cleanup").await;
}
}
}
fn running(pid: u32) -> bool {
std::fs::read_to_string(format!("/proc/{pid}/stat")).is_ok_and(|stat| {
stat.rsplit_once(") ")
.is_some_and(|(_, rest)| !rest.starts_with('Z'))
})
}
async fn until(done: impl Fn() -> bool, failure: &str) {
tokio::time::timeout(Duration::from_secs(5), async {
while !done() {
tokio::time::sleep(Duration::from_millis(10)).await;
}
})
.await
.expect(failure);
}
pub(crate) const HUNG_GROUP: &str = r#"
echo $$ > "$1/parent"
sh -c 'echo $$ > "$1/grandchild"; touch "$1/ready"; exec sleep 60' keyring-grandchild "$1" &
wait
"#;
#[tokio::test]
async fn timeout_kills_a_child_and_grandchild_holding_stderr() {
let fixture = Fixture::new();
let operation = Operation::new(OperationOptions {
timeout_secs: Some(1),
cancel_token: None,
});
let result = tokio::time::timeout(
Duration::from_secs(5),
output(&mut fixture.command(HUNG_GROUP), &operation),
)
.await
.unwrap();
assert!(matches!(result, Err(Error::Timeout(1))), "{result:?}");
fixture.stopped().await;
}
#[tokio::test]
async fn timeout_covers_stderr_held_open_after_the_parent_exits() {
let fixture = Fixture::new();
let script = HUNG_GROUP.replace("\nwait\n", "\nexit 0\n");
assert_ne!(script, HUNG_GROUP);
let operation = Operation::new(OperationOptions {
timeout_secs: Some(1),
cancel_token: None,
});
let result = tokio::time::timeout(
Duration::from_secs(5),
output(&mut fixture.command(&script), &operation),
)
.await
.unwrap();
assert!(matches!(result, Err(Error::Timeout(1))), "{result:?}");
fixture.stopped().await;
}
#[tokio::test]
async fn cancellation_kills_the_process_group() {
let fixture = Fixture::new();
let cancel = CancellationToken::new();
let operation = Operation::new(OperationOptions {
timeout_secs: None,
cancel_token: Some(cancel.clone()),
});
let mut command = fixture.command(HUNG_GROUP);
let task = tokio::spawn(async move { output(&mut command, &operation).await });
fixture.ready().await;
cancel.cancel();
let result = tokio::time::timeout(Duration::from_secs(5), task)
.await
.unwrap()
.unwrap();
assert!(matches!(result, Err(Error::Cancelled)), "{result:?}");
fixture.stopped().await;
}
#[test]
fn cancellation_does_not_need_the_time_driver() {
let cancel = CancellationToken::new();
let operation = Operation::new(OperationOptions {
timeout_secs: None,
cancel_token: Some(cancel.clone()),
});
let canceller = std::thread::spawn(move || {
std::thread::sleep(Duration::from_millis(100));
cancel.cancel();
});
let result = tokio::runtime::Builder::new_current_thread()
.enable_io()
.build()
.unwrap()
.block_on(output(Command::new("sleep").arg("5"), &operation));
canceller.join().unwrap();
assert!(matches!(result, Err(Error::Cancelled)), "{result:?}");
}
#[tokio::test]
async fn cancellation_wins_over_a_ready_future() {
let cancel = CancellationToken::new();
cancel.cancel();
let operation = Operation::new(OperationOptions {
timeout_secs: None,
cancel_token: Some(cancel),
});
for _ in 0..64 {
let result = operation.wait(std::future::ready(())).await;
assert!(matches!(result, Err(Error::Cancelled)), "{result:?}");
}
}
#[tokio::test]
async fn aborting_output_kills_its_process_group() {
let fixture = Fixture::new();
let mut command = fixture.command(HUNG_GROUP);
let task = tokio::spawn(async move { output(&mut command, &Operation::default()).await });
fixture.ready().await;
task.abort();
assert!(task.await.unwrap_err().is_cancelled());
fixture.stopped().await;
}
#[tokio::test]
async fn losing_the_caller_kills_the_group() {
let fixture = Fixture::new();
let mut process = ProcessGroup::spawn(&mut fixture.command(HUNG_GROUP)).unwrap();
fixture.ready().await;
drop(process.watcher.stdin.take());
fixture.stopped().await;
}
#[tokio::test]
async fn stderr_is_drained_with_bounded_retained_output() {
let fixture = Fixture::new();
let operation = Operation::new(OperationOptions {
timeout_secs: Some(5),
cancel_token: None,
});
let script = format!("head -c {} /dev/zero >&2", 2 * STDERR_LIMIT);
let result = output(&mut fixture.command(&script), &operation)
.await
.unwrap();
assert!(result.status.success());
assert_eq!(
result.stderr.len() as u64,
STDERR_LIMIT + TRUNCATED.len() as u64
);
}
#[tokio::test]
async fn stdout_is_not_truncated() {
let fixture = Fixture::new();
let script = format!("head -c {} /dev/zero", 2 * STDERR_LIMIT);
let result = output(&mut fixture.command(&script), &Operation::default())
.await
.unwrap();
assert!(result.status.success());
assert_eq!(result.stdout.len() as u64, 2 * STDERR_LIMIT);
}
#[tokio::test]
async fn a_cancelled_operation_does_not_start_a_child() {
let fixture = Fixture::new();
let cancel = CancellationToken::new();
cancel.cancel();
let operation = Operation::new(OperationOptions {
timeout_secs: None,
cancel_token: Some(cancel),
});
let result = output(&mut Command::new(fixture.path("missing")), &operation).await;
assert!(matches!(result, Err(Error::Cancelled)), "{result:?}");
}
#[tokio::test]
async fn an_unrepresentable_timeout_means_no_timeout() {
let operation = Operation::new(OperationOptions {
timeout_secs: Some(u64::MAX),
cancel_token: None,
});
let result = output(&mut Command::new("true"), &operation).await.unwrap();
assert!(result.status.success());
}
#[tokio::test]
async fn a_failed_command_returns_its_status_and_output() {
let fixture = Fixture::new();
let result = output(
&mut fixture.command("echo out; echo boom >&2; exit 3"),
&Operation::default(),
)
.await
.unwrap();
assert_eq!(result.status.code(), Some(3));
assert_eq!(result.stdout, b"out\n");
assert_eq!(result.stderr, b"boom\n");
}
#[tokio::test]
async fn a_missing_program_is_a_command_error() {
let fixture = Fixture::new();
let result = output(
&mut Command::new(fixture.path("missing")),
&Operation::default(),
)
.await;
assert!(
matches!(&result, Err(Error::Command(e)) if e.kind() == io::ErrorKind::NotFound),
"{result:?}"
);
}
#[tokio::test]
async fn success_leaves_the_reaped_group_alone() {
let fixture = Fixture::new();
let script = r#"sleep 5 >/dev/null 2>&1 & echo $! > "$1/background""#;
let result = output(&mut fixture.command(script), &Operation::default())
.await
.unwrap();
assert!(result.status.success());
tokio::time::sleep(Duration::from_millis(200)).await;
let background = fixture.pid("background");
let alive = running(background);
std::process::Command::new("kill")
.arg(background.to_string())
.status()
.unwrap();
assert!(alive);
}
#[tokio::test]
async fn children_run_in_the_c_locale() {
let fixture = Fixture::new();
let mut command = fixture.command(r#"printf %s "$LC_ALL""#);
command.env("LC_ALL", "de_DE.UTF-8");
let result = output(&mut command, &Operation::default()).await.unwrap();
assert_eq!(result.stdout, b"C");
}
#[tokio::test]
async fn stderr_only_sends_stdout_to_dev_null() {
let fixture = Fixture::new();
let (status, stderr) = stderr_only(
&mut fixture.command(r#"readlink "/proc/$$/fd/1" >&2"#),
&Operation::default(),
)
.await
.unwrap();
assert!(status.success());
assert_eq!(stderr, b"/dev/null\n");
}
}