Skip to main content

crumbkit_process/
run.rs

1//! The one-shot run: start a child, write its input, read its output within
2//! limits and a deadline, stop it when needed, and reap it.
3
4use std::fmt;
5use std::io;
6use std::process::{Command, Stdio};
7use std::sync::Arc;
8use std::thread::{Builder, Scope as Threads, ScopedJoinHandle};
9use std::time::{Duration, Instant};
10
11use crate::notice::Notice;
12use crate::{Cancel, Escalation, Exit, Group, Scope, Signal, Status, Stop, sys};
13
14mod output;
15mod pipes;
16
17#[cfg(test)]
18mod tests;
19
20use self::output::Keeper;
21pub use self::output::{Capture, Captured, OverLimit};
22use self::pipes::{Ends, Kept};
23
24/// How long a run keeps reading the child's pipes after it reaps the
25/// child. A descendant outside the child's scope that holds a pipe open
26/// holds the run no longer than this.
27pub const DRAIN_GRACE: Duration = Duration::from_secs(1);
28
29/// What the child reads on its standard input.
30#[derive(Clone, Debug, Default, PartialEq, Eq)]
31#[non_exhaustive]
32pub enum Input {
33    /// The null device, so the child reads the end of its input at once.
34    #[default]
35    Null,
36    /// These bytes, which a thread of the run writes and then closes. The
37    /// thread stops early when the child closes its input.
38    Bytes(Vec<u8>),
39    /// The tool's own standard input. On Unix a child in a group of its own
40    /// that reads a terminal is stopped by SIGTTIN, so a terminal suits
41    /// only [`Scope::Child`].
42    Inherit,
43}
44
45/// The settings of one [`run`]: the child's input, what it keeps of each
46/// output stream, when and how it stops the child, and the child's scope.
47///
48/// A `Run` that delivers a stream as lines serves one run, because the run
49/// ends the line queue when it returns.
50///
51/// The default reads nothing, keeps nothing, has no deadline and no cancel,
52/// kills at once when it stops the child, and starts the child in a group
53/// of its own.
54#[derive(Clone, Debug, Default)]
55pub struct Run {
56    stdin: Input,
57    stdout: Capture,
58    stderr: Capture,
59    deadline: Option<Instant>,
60    cancel: Option<Cancel>,
61    escalation: Escalation,
62    scope: Scope,
63}
64
65impl Run {
66    /// Returns the default settings.
67    #[must_use]
68    pub fn new() -> Self {
69        Self::default()
70    }
71
72    /// Sets what the child reads on its standard input.
73    #[must_use]
74    pub fn stdin(mut self, input: Input) -> Self {
75        self.stdin = input;
76        self
77    }
78
79    /// Sets what the run keeps of the child's standard output.
80    #[must_use]
81    pub fn stdout(mut self, capture: Capture) -> Self {
82        self.stdout = capture;
83        self
84    }
85
86    /// Sets what the run keeps of the child's standard error.
87    #[must_use]
88    pub fn stderr(mut self, capture: Capture) -> Self {
89        self.stderr = capture;
90        self
91    }
92
93    /// Sets the time at which the run stops a child that has not exited,
94    /// which then ends as [`Exit::TimedOut`].
95    #[must_use]
96    pub const fn deadline(mut self, deadline: Instant) -> Self {
97        self.deadline = Some(deadline);
98        self
99    }
100
101    /// Makes the run watch `cancel`, so [`Cancel::cancel`] stops it.
102    #[must_use]
103    pub fn cancel(mut self, cancel: &Cancel) -> Self {
104        self.cancel = Some(cancel.clone());
105        self
106    }
107
108    /// Sets the steps that stop the child.
109    #[must_use]
110    pub fn escalation(mut self, escalation: Escalation) -> Self {
111        self.escalation = escalation;
112        self
113    }
114
115    /// Sets which processes the run holds and signals.
116    #[must_use]
117    pub const fn scope(mut self, scope: Scope) -> Self {
118        self.scope = scope;
119        self
120    }
121
122    /// Tells the queue of each stream delivered as lines that the run began
123    /// to stop its child.
124    fn stopping(&self) {
125        self.stdout.stopping();
126        self.stderr.stopping();
127    }
128}
129
130/// How a run's child ended and what the run kept of its output.
131#[derive(Clone, Debug, PartialEq, Eq)]
132pub struct Finished {
133    exit: Exit,
134    status: Option<Status>,
135    stdout: Captured,
136    stderr: Captured,
137    first_stdout: Option<Duration>,
138}
139
140impl Finished {
141    /// Returns how the child ended.
142    #[must_use]
143    pub const fn exit(&self) -> Exit {
144        self.exit
145    }
146
147    /// Returns the child's own status as the run reaped it, or `None` when
148    /// the run started no child because its cancel was already cancelled.
149    ///
150    /// The status tells how the child ended even when the run stopped it.
151    /// A run whose cancel stopped a child that SIGINT ended gives
152    /// `Exit::Stopped(Stop::Cancelled)` and the status `Status::Signal(2)`,
153    /// whose [`Status::shell_code`] is 130. A child that handles the signal
154    /// and exits with a code of its own gives that code.
155    #[must_use]
156    pub const fn status(&self) -> Option<Status> {
157        self.status
158    }
159
160    /// Returns what the run kept of standard output.
161    #[must_use]
162    pub const fn stdout(&self) -> &Captured {
163        &self.stdout
164    }
165
166    /// Returns what the run kept of standard error.
167    #[must_use]
168    pub const fn stderr(&self) -> &Captured {
169        &self.stderr
170    }
171
172    /// Returns what the run kept of standard output and standard error.
173    #[must_use]
174    pub fn into_output(self) -> (Captured, Captured) {
175        (self.stdout, self.stderr)
176    }
177
178    /// Returns the time from the child's start to the first byte of its
179    /// standard output, or `None` when it printed none or the run discarded
180    /// standard output.
181    #[must_use]
182    pub const fn first_stdout(&self) -> Option<Duration> {
183        self.first_stdout
184    }
185}
186
187/// A run that could not start its child or follow it to its end.
188#[derive(Debug)]
189#[non_exhaustive]
190pub enum RunError {
191    /// The program does not exist or cannot be started.
192    Start(io::Error),
193    /// Waiting for the child, reaping it, reading its output or starting a
194    /// thread failed after it started. The child was stopped and reaped.
195    Run(io::Error),
196}
197
198impl fmt::Display for RunError {
199    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
200        f.write_str(match self {
201            Self::Start(_) => "cannot start the program",
202            Self::Run(_) => "cannot follow the program to its end",
203        })
204    }
205}
206
207impl std::error::Error for RunError {
208    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
209        match self {
210            Self::Start(error) | Self::Run(error) => Some(error),
211        }
212    }
213}
214
215/// Runs `command` with the settings of `run` and returns how it ended and
216/// what it printed.
217///
218/// The run sets the command's standard streams, starts it in the scope of
219/// [`Run::scope`], and waits until the child exits, the deadline passes,
220/// the cancel is cancelled, or a stream whose policy stops the child passes
221/// its limit. In the last three cases it stops the child with the
222/// [`Escalation`]. Once the child has exited, the run kills what is left of
223/// its group, reaps it, and reads its pipes for at most [`DRAIN_GRACE`]
224/// more. A run whose deadline passes after the child exited gives the
225/// child's own exit.
226///
227/// On Unix, for a child that the tool may signal, a run takes at most the
228/// time to its deadline, plus the graces of its escalation, plus
229/// [`DRAIN_GRACE`], as long as the caller reads the lines of each stream
230/// delivered as lines. Every thread that it starts is joined before it
231/// returns. On Windows a stop ends the job at once, and a reader waits for
232/// its pipe to close, which ending the job causes for every process in the
233/// job, so a process outside the job that holds a pipe holds the run.
234///
235/// A stream delivered as lines waits for the caller while its queue is
236/// full, and the child then waits on its full pipe. Once the run begins to
237/// stop the child, a full queue drops each line instead. The run ends each
238/// line queue when it returns, on every path.
239///
240/// # Errors
241///
242/// Returns [`RunError::Start`] when the program cannot be started, and
243/// [`RunError::Run`] when waiting for, reaping or reading the child fails.
244/// The child is stopped and reaped on every path.
245pub fn run(mut command: Command, run: &Run) -> Result<Finished, RunError> {
246    let _end = EndLines(run);
247    if run.cancel.as_ref().is_some_and(Cancel::is_cancelled) {
248        return Ok(Finished {
249            exit: Exit::Stopped(Stop::Cancelled),
250            status: None,
251            stdout: Captured::default(),
252            stderr: Captured::default(),
253            first_stdout: None,
254        });
255    }
256    let input = match &run.stdin {
257        Input::Null => Stdio::null(),
258        Input::Inherit => Stdio::inherit(),
259        Input::Bytes(_) => Stdio::piped(),
260    };
261    command
262        .stdin(input)
263        .stdout(run.stdout.stdio())
264        .stderr(run.stderr.stdio());
265    let started = Instant::now();
266    let mut group = Group::start(command, run.scope).map_err(RunError::Start)?;
267    let notice = Arc::new(Notice::default());
268    if let Some(cancel) = &run.cancel {
269        cancel.watch(&notice);
270    }
271    let ends = Ends::default();
272    let followed = std::thread::scope(|threads| {
273        let unwind = Unwind {
274            group: &mut group,
275            ends: &ends,
276            run,
277        };
278        follow(threads, &mut *unwind.group, &notice, &ends, run)
279    });
280    let (exit, status, stdout, stderr) = followed.map_err(RunError::Run)?;
281    Ok(Finished {
282        exit,
283        status: Some(status),
284        first_stdout: stdout.first.map(|first| first - started),
285        stdout: stdout.captured,
286        stderr: stderr.captured,
287    })
288}
289
290/// Ends the line queues of a run when the run returns, on every path.
291struct EndLines<'run>(&'run Run);
292
293impl Drop for EndLines<'_> {
294    fn drop(&mut self) {
295        self.0.stdout.end();
296        self.0.stderr.end();
297    }
298}
299
300/// Ends the threads of a run when [`follow`] returns, which matters when it
301/// panics: it kills the child unless the group has been reaped, makes the
302/// readers and the writer stop waiting on their pipes, and makes each line
303/// queue drop instead of waiting. The scope then joins every thread, and
304/// the group's drop reaps the child. On a normal return each of these has
305/// already happened or does nothing.
306struct Unwind<'a> {
307    group: &'a mut Group,
308    ends: &'a Ends,
309    run: &'a Run,
310}
311
312impl Drop for Unwind<'_> {
313    fn drop(&mut self) {
314        // A reaped group refuses the signal, so the kill never reaches a
315        // process id that another process may have taken.
316        let _ = self.group.signal(Signal::Kill);
317        self.ends.set(Instant::now());
318        self.run.stopping();
319    }
320}
321
322/// The threads of one run: the waiter, the readers and the writer.
323struct Started<'scope> {
324    waiter: ScopedJoinHandle<'scope, io::Result<()>>,
325    stdout: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
326    stderr: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
327    stdin: Option<ScopedJoinHandle<'scope, ()>>,
328}
329
330/// Follows the child of `group` to its end within `threads`, and returns
331/// its exit, its reaped status and what the readers kept.
332fn follow<'scope>(
333    threads: &'scope Threads<'scope, '_>,
334    group: &mut Group,
335    notice: &'scope Notice,
336    ends: &'scope Ends,
337    run: &'scope Run,
338) -> io::Result<(Exit, Status, Kept, Kept)> {
339    let pipes = (group.take_stdin(), group.take_stdout(), group.take_stderr());
340    let exit = group.waiter();
341    let waiter = match Builder::new().spawn_scoped(threads, move || {
342        let waited = exit.wait();
343        notice.set(|flags| flags.exited = true);
344        waited
345    }) {
346        Ok(waiter) => waiter,
347        Err(error) => {
348            let _ = group.signal(Signal::Kill);
349            let _ = group.reap();
350            return Err(error);
351        }
352    };
353    let mut started = Started {
354        waiter,
355        stdout: None,
356        stderr: None,
357        stdin: None,
358    };
359    let mut failure = start_pipes(threads, &mut started, pipes, notice, ends, run).err();
360    let stopped = if failure.is_some() {
361        stop(group, notice, &Escalation::default(), run);
362        None
363    } else {
364        control(group, notice, run)
365    };
366    let status = group.reap();
367    ends.set(
368        Instant::now()
369            .checked_add(DRAIN_GRACE)
370            .unwrap_or_else(Instant::now),
371    );
372    let exited = joined(started.waiter.join());
373    let stdout = started.stdout.map(|reader| joined(reader.join()));
374    let stderr = started.stderr.map(|reader| joined(reader.join()));
375    if let Some(writer) = started.stdin {
376        let _ = writer.join();
377    }
378    if let Some(failure) = failure.take() {
379        return Err(failure);
380    }
381    exited?;
382    let status = sys::status_of(status?);
383    let exit = stopped.unwrap_or_else(|| status.exit());
384    let unread = || Kept {
385        captured: Captured::default(),
386        first: None,
387    };
388    Ok((
389        exit,
390        status,
391        stdout.transpose()?.unwrap_or_else(unread),
392        stderr.transpose()?.unwrap_or_else(unread),
393    ))
394}
395
396/// Starts the readers of the child's output pipes and the writer of its
397/// input, and records each in `started`.
398fn start_pipes<'scope>(
399    threads: &'scope Threads<'scope, '_>,
400    started: &mut Started<'scope>,
401    (stdin, stdout, stderr): (
402        Option<std::process::ChildStdin>,
403        Option<std::process::ChildStdout>,
404        Option<std::process::ChildStderr>,
405    ),
406    notice: &'scope Notice,
407    ends: &'scope Ends,
408    run: &'scope Run,
409) -> io::Result<()> {
410    let over = || notice.set(|flags| flags.over_limit = true);
411    if let Some(stdout) = stdout {
412        let keeper = Keeper::new(&run.stdout);
413        started.stdout = Some(
414            Builder::new()
415                .spawn_scoped(threads, move || pipes::read(stdout, ends, keeper, over))?,
416        );
417    }
418    if let Some(stderr) = stderr {
419        let keeper = Keeper::new(&run.stderr);
420        started.stderr = Some(
421            Builder::new()
422                .spawn_scoped(threads, move || pipes::read(stderr, ends, keeper, over))?,
423        );
424    }
425    if let (Some(stdin), Input::Bytes(bytes)) = (stdin, &run.stdin) {
426        started.stdin =
427            Some(Builder::new().spawn_scoped(threads, move || pipes::write(stdin, bytes, ends))?);
428    }
429    Ok(())
430}
431
432/// Waits until the child exits or the run must stop it, stops it then, and
433/// returns the exit that the stop gives, or `None` when the child ended on
434/// its own. The child has exited when it returns, and is unreaped.
435fn control(group: &Group, notice: &Notice, run: &Run) -> Option<Exit> {
436    let flags = notice.wait(run.deadline, |flags| {
437        flags.exited || flags.cancelled || flags.over_limit
438    });
439    let exit = if flags.exited {
440        return None;
441    } else if flags.cancelled {
442        Exit::Stopped(Stop::Cancelled)
443    } else if flags.over_limit {
444        Exit::Stopped(Stop::OverLimit)
445    } else if group.has_exited().unwrap_or(false) {
446        // The deadline passed after the child exited and before the waiter
447        // said so, so the child's own exit stands.
448        notice.wait(None, |flags| flags.exited);
449        return None;
450    } else {
451        Exit::TimedOut
452    };
453    stop(group, notice, &run.escalation, run);
454    Some(exit)
455}
456
457/// Stops the child with `escalation`, and returns once the child has exited.
458/// First it tells each line queue of `run` that the run is stopping.
459///
460/// A signal that the operating system refuses is skipped, because the next
461/// step, and in the end the kill, still applies. A grace too long for an
462/// `Instant` waits without a limit.
463///
464/// RUST-10: the stop waits for the child's exit after the kill without a
465/// limit. That handles every child that the tool may signal, and it misses
466/// a child that the kill cannot reach, such as a setuid program that
467/// refuses the tool's signals with `EPERM`, which holds the run until it
468/// exits. A run that gives up on such a child and reports it replaces this
469/// when a caller needs one.
470fn stop(group: &Group, notice: &Notice, escalation: &Escalation, run: &Run) {
471    run.stopping();
472    if sys::GRACEFUL {
473        for (signal, grace) in escalation.steps() {
474            let _ = group.signal(signal);
475            if notice
476                .wait(Instant::now().checked_add(grace), |flags| flags.exited)
477                .exited
478            {
479                return;
480            }
481        }
482    }
483    let _ = group.signal(Signal::Kill);
484    notice.wait(None, |flags| flags.exited);
485}
486
487/// Returns a thread's result, or an error when the thread panicked, which
488/// only a broken invariant in the crate can cause.
489fn joined<T>(result: std::thread::Result<io::Result<T>>) -> io::Result<T> {
490    result.unwrap_or_else(|_| Err(io::Error::other("a thread of the run stopped")))
491}