convert-rs 0.2.0

Extensible file conversion library with graph routing and optional native tools
Documentation
//! Out-of-process execution for native conversion tools.
//!
//! This module is the only place in the crate that spawns a child process. It
//! never routes input through a shell: the program name and every argument are
//! passed as discrete values, so file paths and format strings cannot be
//! parsed as commands. Stdout and stderr are bounded, and a deadline kills and
//! reaps the child. These are resource guards, not a sandbox: native tools run
//! with this process's full privileges, so external conversions stay behind
//! [`crate::Policy::allow_external`] and trusted inputs only.

use std::path::Path;
use std::process::Stdio;
use std::time::Duration;

use tokio::io::{AsyncRead, AsyncReadExt};

use crate::{Error, Limits, Result};

/// Hard ceiling on captured stderr. Tool chatter beyond this is dropped.
const STDERR_CAP: u64 = 256 * 1024;
/// How many trailing stderr bytes to surface in a failure message.
const ERROR_TAIL: usize = 4096;
/// A short, self-contained deadline for a presence probe.
const PROBE_TIMEOUT: Duration = Duration::from_secs(10);
/// Read size while draining a tool pipe.
const CHUNK: usize = 8 * 1024;

/// Run `program` with `args`, capturing bounded output, honoring `limits`.
///
/// The child's stdin is closed, its stdout and stderr are drained concurrently
/// to avoid pipe deadlock, and the whole run is wrapped in `limits.timeout`. On
/// timeout, output overflow, or a nonzero exit the child is killed (via
/// `kill_on_drop`) and a descriptive [`Error`] is returned. A missing binary
/// surfaces as [`Error::Io`].
pub async fn run(
    backend: &str,
    program: &str,
    args: &[String],
    cwd: Option<&Path>,
    limits: &Limits,
) -> Result<()> {
    let mut command = tokio::process::Command::new(program);
    command
        .args(args)
        .stdin(Stdio::null())
        .stdout(Stdio::piped())
        .stderr(Stdio::piped())
        .kill_on_drop(true);
    if let Some(directory) = cwd {
        command.current_dir(directory);
    }
    let mut child = command.spawn().map_err(|error| {
        Error::Io(std::io::Error::new(
            error.kind(),
            format!("cannot start {program}: {error}"),
        ))
    })?;
    let stdout_stream = child
        .stdout
        .take()
        .ok_or_else(|| Error::Conversion(format!("{program} stdout was not captured")))?;
    let stderr_stream = child
        .stderr
        .take()
        .ok_or_else(|| Error::Conversion(format!("{program} stderr was not captured")))?;

    // Drain both pipes and reap the child within the same deadline. Dropping
    // the child on any early return kills it because kill_on_drop is set.
    let job = async {
        let (stdout, stderr, status) = tokio::join!(
            read_bounded(stdout_stream, limits.max_output_bytes),
            read_bounded(stderr_stream, STDERR_CAP),
            child.wait(),
        );
        Ok::<_, Error>((stdout?, stderr?, status.map_err(Error::Io)?))
    };
    let (stdout, stderr, status) = match tokio::time::timeout(limits.timeout, job).await {
        Ok(result) => result?,
        Err(_elapsed) => {
            let _ = child.start_kill();
            let _ = child.wait().await;
            return Err(Error::Timeout {
                backend: backend.to_owned(),
            });
        }
    };

    let code = status.code();
    if !status.success() {
        return Err(Error::Conversion(format!(
            "{program} ({backend}) exited with status {code:?}: {}",
            tail(&stderr)
        )));
    }
    let _ = stdout;
    Ok(())
}

/// Whether `program` exists on `PATH` and executes quickly enough to probe.
///
/// Presence is inferred from a successful spawn, not the exit code: tools print
/// usage and exit nonzero when called with an unknown flag. Any spawn error
/// (missing, not executable) reports false. A probe that hangs is killed.
pub async fn available(program: &str) -> bool {
    spawn_flag(program, "--version").await || spawn_flag(program, "-version").await
}

async fn spawn_flag(program: &str, flag: &str) -> bool {
    let mut command = tokio::process::Command::new(program);
    command
        .arg(flag)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .kill_on_drop(true);
    let Ok(mut child) = command.spawn() else {
        return false;
    };
    // Whether it exits cleanly or is killed for stalling, a successful spawn
    // only happens when the binary is really present and runnable.
    let _ = tokio::time::timeout(PROBE_TIMEOUT, child.wait()).await;
    true
}

async fn read_bounded<S>(stream: S, cap: u64) -> Result<Vec<u8>>
where
    S: AsyncRead + Unpin,
{
    let mut collected = Vec::new();
    let mut buffer = [0u8; CHUNK];
    let mut reader = stream;
    loop {
        let count = reader
            .read(&mut buffer)
            .await
            .map_err(|error| Error::Conversion(format!("failed reading tool output: {error}")))?;
        if count == 0 {
            break;
        }
        if (collected.len() + count) as u64 > cap {
            let room = cap.saturating_sub(collected.len() as u64);
            let room = usize::try_from(room).unwrap_or(usize::MAX).min(count);
            collected.extend_from_slice(&buffer[..room]);
            return Err(Error::Limit("external tool output exceeded its cap".into()));
        }
        collected.extend_from_slice(&buffer[..count]);
    }
    Ok(collected)
}

fn tail(bytes: &[u8]) -> String {
    let start = bytes.len().saturating_sub(ERROR_TAIL);
    String::from_utf8_lossy(&bytes[start..]).trim().to_owned()
}

#[cfg(test)]
#[allow(clippy::unwrap_used, clippy::expect_used)]
mod tests {
    use super::*;

    fn limits() -> Limits {
        Limits::default()
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_captures_success() {
        let output = run("test-probe", "true", &[], None, &limits()).await;
        assert!(output.is_ok());
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_maps_nonzero_exit() {
        let error = run("test-probe", "false", &[], None, &limits())
            .await
            .unwrap_err();
        assert!(matches!(error, Error::Conversion(_)), "{error:?}");
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_enforces_timeout() {
        let tight = Limits {
            timeout: Duration::from_millis(50),
            ..Limits::default()
        };
        let error = run("test-probe", "sleep", &["5".into()], None, &tight)
            .await
            .unwrap_err();
        assert!(matches!(error, Error::Timeout { .. }), "{error:?}");
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_bounds_collected_output() {
        let cap = Limits {
            max_output_bytes: 16,
            ..Limits::default()
        };
        let error = run(
            "test-probe",
            "head",
            &["-c".into(), "100000".into(), "/dev/zero".into()],
            None,
            &cap,
        )
        .await
        .unwrap_err();
        assert!(matches!(error, Error::Limit(_)), "{error:?}");
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn run_reports_missing_program_as_io() {
        let error = run(
            "test-probe",
            "definitely-not-installed-convert-rs-xyz",
            &[],
            None,
            &limits(),
        )
        .await
        .unwrap_err();
        assert!(matches!(error, Error::Io(_)), "{error:?}");
    }

    #[cfg(unix)]
    #[tokio::test]
    async fn available_detects_present_and_absent() {
        assert!(available("true").await);
        assert!(!available("definitely-not-installed-convert-rs-xyz").await);
    }
}