crumbkit-process 0.6.1

Runs a child program in a process group of its own and reads its output within byte limits and a deadline
Documentation
use std::time::{Duration, Instant};

use super::super::{Cancel, Capture, Outcome, RunOptions, StopReason, WholeCapture, run};
use crate::testing::{cmd, gone, pid_file, pid_in, remove, started_grandchild};
use crate::{Scope, Status};

/// Keeps up to 1 MiB of standard output whole.
const WHOLE: WholeCapture = Capture::whole(1 << 20);

/// Returns the standard output of a run as text.
fn text(bytes: &[u8]) -> String {
    String::from_utf8_lossy(bytes).into_owned()
}

#[test]
fn a_child_gives_its_exit_code_and_its_standard_output() {
    let finished = run(cmd("echo out& exit 3"), &RunOptions::new().stdout(WHOLE)).unwrap();

    assert_eq!(finished.outcome(), Outcome::Ended(Status::Code(3)));
    assert_eq!(finished.status(), Some(Status::Code(3)));
    assert_eq!(finished.stdout().bytes(), b"out\r\n");
}

#[test]
fn a_cancelled_child_whose_job_was_ended_gives_exit_code_1() {
    let cancel = Cancel::new();
    let canceller = std::thread::spawn({
        let cancel = cancel.clone();
        move || {
            std::thread::sleep(Duration::from_millis(500));
            cancel.cancel();
        }
    });

    let finished = run(
        cmd("ping -n 120 127.0.0.1 >NUL"),
        &RunOptions::new().stdout(WHOLE).cancel(&cancel),
    )
    .unwrap();

    canceller.join().unwrap();
    assert_eq!(finished.outcome(), Outcome::Stopped(StopReason::Cancelled));
    assert_eq!(finished.status(), Some(Status::Code(1)));
}

#[test]
fn ending_the_job_when_the_child_exits_ends_a_grandchild_that_holds_standard_output() {
    // The grandchild sleeps 120 s while it holds standard output, so a run
    // that waited for it would take that long. PowerShell can take several
    // seconds to start on a cold machine, so the bound leaves room for that.
    let file = pid_file("job-ends");
    let started = Instant::now();

    let finished = run(
        cmd(&started_grandchild(&file, 120)),
        &RunOptions::new().stdout(WHOLE),
    )
    .unwrap();

    let took = started.elapsed();
    remove(&file);
    let out = text(finished.stdout().bytes());
    assert_eq!(finished.outcome(), Outcome::Ended(Status::Code(0)));
    assert!(out.contains("started"), "{out:?}");
    assert!(!out.contains("woke"), "{out:?}");
    let grandchild = pid_in(finished.stdout().bytes());
    assert!(took < Duration::from_secs(60), "the run took {took:?}");
    assert!(
        gone(grandchild),
        "the grandchild {grandchild} outlived the run"
    );
}

#[test]
fn in_the_child_scope_the_run_waits_for_a_grandchild_that_holds_standard_output() {
    // With no job, the grandchild outlives the child, and the reader of
    // standard output waits until the grandchild closes it by exiting.
    let file = pid_file("child-scope");
    let started = Instant::now();

    let finished = run(
        cmd(&started_grandchild(&file, 3)),
        &RunOptions::new().stdout(WHOLE).scope(Scope::Child),
    )
    .unwrap();

    let took = started.elapsed();
    remove(&file);
    let out = text(finished.stdout().bytes());
    assert_eq!(finished.outcome(), Outcome::Ended(Status::Code(0)));
    assert!(out.contains("started"), "{out:?}");
    assert!(
        out.contains("woke"),
        "the grandchild did not outlive the child: {out:?}"
    );
    assert!(took >= Duration::from_secs(3), "the run took {took:?}");
    let grandchild = pid_in(finished.stdout().bytes());
    assert!(
        gone(grandchild),
        "the grandchild {grandchild} is still running"
    );
}

#[test]
fn a_deadline_ends_the_job_with_the_grandchild_in_it() {
    let file = pid_file("deadline");
    let script = format!(
        "{} & ping -n 120 127.0.0.1 >NUL",
        started_grandchild(&file, 120)
    );
    let started = Instant::now();

    let finished = run(
        cmd(&script),
        &RunOptions::new()
            .stdout(WHOLE)
            .deadline(Instant::now() + Duration::from_secs(20)),
    )
    .unwrap();

    let took = started.elapsed();
    remove(&file);
    let out = text(finished.stdout().bytes());
    assert_eq!(finished.outcome(), Outcome::TimedOut);
    assert!(out.contains("started"), "{out:?}");
    let grandchild = pid_in(finished.stdout().bytes());
    assert!(took < Duration::from_secs(60), "the run took {took:?}");
    assert!(
        gone(grandchild),
        "the grandchild {grandchild} outlived the run"
    );
}

#[test]
fn a_run_past_its_overdue_time_reports_once_and_waits_for_the_child_to_exit() {
    let (sender, reports) = std::sync::mpsc::channel();
    let options = RunOptions::new().stdout(WHOLE).overdue(
        Instant::now() + Duration::from_millis(200),
        move |overdue| {
            sender.send(overdue).unwrap();
        },
    );

    let finished = run(cmd("ping -n 4 127.0.0.1 >NUL& echo done"), &options).unwrap();

    assert_eq!(finished.outcome(), Outcome::Ended(Status::Code(0)));
    assert!(finished.was_overdue());
    assert_eq!(finished.stdout().bytes(), b"done\r\n");
    assert!(reports.try_recv().is_ok());
    assert!(reports.try_recv().is_err());
}

#[test]
fn a_child_that_exits_before_its_overdue_time_is_never_reported() {
    let options = RunOptions::new().overdue(Instant::now() + Duration::from_secs(60), |_| {
        panic!("reported")
    });

    let finished = run(cmd("exit 4"), &options).unwrap();

    assert_eq!(finished.outcome(), Outcome::Ended(Status::Code(4)));
    assert!(!finished.was_overdue());
}