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::fs::File;
6use std::io;
7use std::process::{Command, Stdio};
8use std::sync::Arc;
9use std::thread::{Builder, Scope as Threads, ScopedJoinHandle};
10use std::time::{Duration, Instant};
11
12use zeroize::Zeroizing;
13
14use crate::notice::Notice;
15use crate::{Cancel, Escalation, Group, Outcome, Scope, Signal, Status, StopReason, sys};
16
17mod finished;
18mod output;
19mod pipes;
20mod spawn;
21
22#[cfg(test)]
23mod tests;
24
25pub use self::finished::{ChildFinished, RunError};
26pub use self::output::{Capture, Captured, LongLine, OverLimit};
27use self::output::{Keeper, OutputCopy};
28use self::pipes::{Ends, Kept};
29use self::spawn::AroundSpawn;
30pub use self::spawn::{Spawn, Spawned};
31
32/// How long a run keeps reading the child's pipes after it reaps the
33/// child. A descendant outside the child's scope that holds a pipe open
34/// holds the run no longer than this.
35pub const DRAIN_GRACE: Duration = Duration::from_secs(1);
36
37/// How long after the child exits a run on Unix waits for the child's group
38/// to be empty. On macOS the run also kills the group again while a live
39/// process is left. A process of the group that outlasts it is left behind
40/// and the run goes on to read the pipes: one that waits for a parent that
41/// never reaps it, or a live one that the tool may not signal, such as a
42/// setuid program.
43pub const REAP_GRACE: Duration = Duration::from_secs(1);
44
45/// What the child reads on its standard input.
46#[derive(Clone, Default)]
47#[non_exhaustive]
48pub enum Input {
49    /// The null device, so the child reads the end of its input at once.
50    #[default]
51    Null,
52    /// These bytes, which a thread of the run writes and then closes. The
53    /// thread stops early when the child closes its input.
54    ///
55    /// The buffer is cleared when it drops, so a secret given to a child
56    /// does not stay in the tool's memory after the settings are gone.
57    /// Each clone of the settings holds and clears its own copy. The
58    /// clearing covers this buffer only: it misses copies that the caller
59    /// made before and the pipe's buffer in the kernel. `Debug` prints the
60    /// length alone.
61    Bytes(Zeroizing<Vec<u8>>),
62    /// The tool's own standard input. On Unix a child in a group of its own
63    /// that reads a terminal is stopped by SIGTTIN, so a terminal suits
64    /// only [`Scope::Child`].
65    Inherit,
66    /// A file or the read end of a pipe, which a pipe becomes with
67    /// `File::from(OwnedFd::from(reader))` on Unix and
68    /// `File::from(OwnedHandle::from(reader))` on Windows. The child gets a duplicate that
69    /// shares the file's position, so it reads from the current position
70    /// and moves the position that the caller and any later run see. The
71    /// caller's `File` stays open.
72    File(Arc<File>),
73}
74
75impl fmt::Debug for Input {
76    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
77        match self {
78            Self::Null => f.write_str("Null"),
79            Self::Bytes(bytes) => f
80                .debug_tuple("Bytes")
81                .field(&format_args!("{} bytes", bytes.len()))
82                .finish(),
83            Self::Inherit => f.write_str("Inherit"),
84            Self::File(file) => f.debug_tuple("File").field(file).finish(),
85        }
86    }
87}
88
89/// The settings of one [`run`]: the child's input, what it keeps of each
90/// output stream, when and how it stops the child, and the child's scope.
91///
92/// A `RunOptions` value that delivers a stream as lines serves one run,
93/// because the run ends the line queue when it returns.
94///
95/// The default reads nothing, keeps nothing, has no deadline and no cancel,
96/// kills at once when it stops the child, and starts the child in a group
97/// of its own.
98#[derive(Clone, Debug, Default)]
99pub struct RunOptions {
100    stdin: Input,
101    stdout: Capture,
102    stderr: Capture,
103    deadline: Option<Instant>,
104    cancel: Option<Cancel>,
105    escalation: Escalation,
106    scope: Scope,
107    around_spawn: Option<AroundSpawn>,
108    stdout_copy: Option<OutputCopy>,
109    stderr_copy: Option<OutputCopy>,
110    report_survivors: bool,
111}
112
113impl RunOptions {
114    /// Returns the default settings.
115    #[must_use]
116    pub fn new() -> Self {
117        Self::default()
118    }
119
120    /// Sets what the child reads on its standard input.
121    #[must_use]
122    pub fn stdin(mut self, input: Input) -> Self {
123        self.stdin = input;
124        self
125    }
126
127    /// Sets what the run keeps of the child's standard output.
128    #[must_use]
129    pub fn stdout(mut self, capture: Capture) -> Self {
130        self.stdout = capture;
131        self
132    }
133
134    /// Sets what the run keeps of the child's standard error.
135    #[must_use]
136    pub fn stderr(mut self, capture: Capture) -> Self {
137        self.stderr = capture;
138        self
139    }
140
141    /// Sets the time at which the run stops a child that has not exited,
142    /// which then ends as [`Outcome::TimedOut`].
143    #[must_use]
144    pub const fn deadline(mut self, deadline: Instant) -> Self {
145        self.deadline = Some(deadline);
146        self
147    }
148
149    /// Makes the run watch `cancel`, so [`Cancel::cancel`] stops it.
150    #[must_use]
151    pub fn cancel(mut self, cancel: &Cancel) -> Self {
152        self.cancel = Some(cancel.clone());
153        self
154    }
155
156    /// Sets the steps that stop the child.
157    #[must_use]
158    pub fn escalation(mut self, escalation: Escalation) -> Self {
159        self.escalation = escalation;
160        self
161    }
162
163    /// Sets which processes the run holds and signals.
164    #[must_use]
165    pub const fn scope(mut self, scope: Scope) -> Self {
166        self.scope = scope;
167        self
168    }
169
170    /// Makes `hook` start the child, so the caller can hold a lock or change
171    /// process-wide state for exactly the length of the start.
172    ///
173    /// The run calls `hook` once, on the thread that called [`run`], and
174    /// never when its cancel was already cancelled. The hook does its work
175    /// before the start, calls [`Spawn::start`], does its work after the
176    /// start, and returns the [`Spawned`] that the start gave. The hook
177    /// surrounds the whole start, including the `forward` feature's lock.
178    ///
179    /// A hook that returns an error ends the run with [`RunError::Start`].
180    /// When the child had started, dropping its [`Spawned`] kills the child
181    /// and every process in its scope and reaps the child. A panic in the
182    /// hook does the same as it unwinds.
183    ///
184    /// The time the hook takes counts towards the deadline, and it is not
185    /// part of the time bound that [`run`] states. Time that the hook spends
186    /// after the start counts towards
187    /// [`first_stdout`](ChildFinished::first_stdout), because the run reads
188    /// the child's output only once the hook returns. A hook that waits for a
189    /// lock can check the deadline itself and return an error. With the
190    /// `forward` feature, a start waits forever once the tool has received
191    /// a signal, so a clean-up must not wait for a lock that the hook holds.
192    ///
193    /// ```no_run
194    /// use std::io;
195    /// use std::process::Command;
196    /// use std::sync::Mutex;
197    ///
198    /// use crumbkit_process::{RunOptions, run};
199    ///
200    /// static FORK_GATE: Mutex<()> = Mutex::new(());
201    ///
202    /// fn inherit(descriptors: bool) -> io::Result<()> {
203    ///     // Clears or sets CLOEXEC on the descriptors the child inherits.
204    ///     # let _ = descriptors;
205    ///     Ok(())
206    /// }
207    ///
208    /// let options = RunOptions::new().around_spawn(|spawn| {
209    ///     let _gate = FORK_GATE.lock().map_err(|_| io::Error::other("poisoned"))?;
210    ///     inherit(true)?;
211    ///     let spawned = spawn.start();
212    ///     inherit(false)?;
213    ///     spawned
214    /// });
215    /// # let _ = run(Command::new("true"), &options);
216    /// ```
217    #[must_use]
218    pub fn around_spawn(
219        mut self,
220        hook: impl Fn(Spawn) -> io::Result<Spawned> + Send + Sync + 'static,
221    ) -> Self {
222        self.around_spawn = Some(AroundSpawn::new(hook));
223        self
224    }
225
226    /// Calls `copy` with each chunk of standard output as the run reads it,
227    /// whatever the capture keeps, so a tool can show the output while the
228    /// run keeps a bounded copy. See [`RunOptions::stderr_copy`].
229    #[must_use]
230    pub fn stdout_copy(mut self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
231        self.stdout_copy = Some(OutputCopy::new(copy));
232        self
233    }
234
235    /// Calls `copy` with each chunk of standard error as the run reads it,
236    /// whatever the capture keeps.
237    ///
238    /// A chunk can end in the middle of a line or of a UTF-8 character. The
239    /// run does not read a stream with [`Capture::Inherit`], so its function
240    /// receives nothing.
241    /// Each stream's function runs on that stream's reader thread, so the
242    /// two streams can interleave. A function that blocks holds the reader:
243    /// the child then waits on its full pipe, and the run waits for the
244    /// function past the time bound that [`run`] states. A function that
245    /// panics gets no more chunks, the run reads the rest of the stream so
246    /// the child runs on, and the run ends with [`RunError::Run`].
247    #[must_use]
248    pub fn stderr_copy(mut self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
249        self.stderr_copy = Some(OutputCopy::new(copy));
250        self
251    }
252
253    /// Makes the run check, when the child ends by itself and before the run
254    /// kills what is left of the group, whether any other process in the
255    /// group still runs. [`ChildFinished::survivors`] gives the answer. The
256    /// run kills those processes as it always does.
257    ///
258    /// The check is off by default because on Linux it reads every process
259    /// in `/proc`. It reports on [`Scope::Group`] on Linux and macOS alone.
260    #[must_use]
261    pub const fn report_survivors(mut self) -> Self {
262        self.report_survivors = true;
263        self
264    }
265
266    /// Tells the queue of each stream delivered as lines that the run began
267    /// to stop its child.
268    fn stopping(&self) {
269        self.stdout.stopping();
270        self.stderr.stopping();
271    }
272
273    /// Tells the queue of each stream delivered as lines that the child has
274    /// exited, so a full queue drops lines once `deadline` has passed.
275    fn drain_until(&self, deadline: Instant) {
276        self.stdout.drain_until(deadline);
277        self.stderr.drain_until(deadline);
278    }
279}
280
281/// Runs `command` with the settings in `options` and returns how it ended and
282/// what it printed.
283///
284/// The run sets the command's standard streams, starts it in the scope of
285/// [`RunOptions::scope`], and waits until the child exits, the deadline passes,
286/// the cancel is cancelled, or a stream whose policy stops the child passes
287/// its limit. In the last three cases it stops the child with the
288/// [`Escalation`]. Once the child has exited, the run kills what is left of
289/// its group, reaps it, waits on Unix until the group is empty for at most
290/// [`REAP_GRACE`] after the exit, and reads its pipes for at most
291/// [`DRAIN_GRACE`] more. A run whose deadline passes after the child exited gives the
292/// child's own exit.
293///
294/// On Unix, for a child that the tool may signal, a run takes at most the
295/// time to its deadline, plus the graces of its escalation, plus
296/// [`REAP_GRACE`], plus [`DRAIN_GRACE`], plus the time that a hook of
297/// [`RunOptions::around_spawn`] takes, plus the time that a function of
298/// [`RunOptions::stdout_copy`] or [`RunOptions::stderr_copy`] blocks. Every
299/// thread that it starts is joined before it returns. On Windows a stop ends the job at once, and a reader waits for
300/// its pipe to close, which ending the job causes for every process in the
301/// job, so a process outside the job that holds a pipe holds the run.
302///
303/// A stream delivered as lines waits for the caller while its queue is
304/// full, and the child then waits on its full pipe. Once the run begins to
305/// stop the child, a full queue drops each line instead. After the child
306/// exits by itself, a full queue waits for the caller until the drain
307/// deadline, half of [`DRAIN_GRACE`] after the reap, and then drops each
308/// line while the reader goes on reading the pipe until [`DRAIN_GRACE`]
309/// after the reap. [`Lines::lost`](crate::Lines::lost) says which line a
310/// caller can rely on. The run ends each line queue when it returns, on
311/// every path.
312///
313/// # Errors
314///
315/// Returns [`RunError::Start`] when the program cannot be started, a hook
316/// of [`RunOptions::around_spawn`] fails, or an [`Input::File`] cannot be
317/// duplicated, and
318/// [`RunError::Run`] when waiting for, reaping or reading the child fails
319/// or a copy function panics.
320/// The child is stopped and reaped on every path.
321pub fn run(mut command: Command, options: &RunOptions) -> Result<ChildFinished, RunError> {
322    let _end = EndLines(options);
323    if options.cancel.as_ref().is_some_and(Cancel::is_cancelled) {
324        return Ok(ChildFinished {
325            outcome: Outcome::Stopped(StopReason::Cancelled),
326            status: None,
327            stdout: Captured::default(),
328            stderr: Captured::default(),
329            first_stdout: None,
330            survivors: false,
331        });
332    }
333    let input = match &options.stdin {
334        Input::Null => Stdio::null(),
335        Input::Inherit => Stdio::inherit(),
336        Input::Bytes(_) => Stdio::piped(),
337        Input::File(file) => Stdio::from(file.try_clone().map_err(RunError::Start)?),
338    };
339    command
340        .stdin(input)
341        .stdout(output_stdio(&options.stdout, options.stdout_copy.as_ref()))
342        .stderr(output_stdio(&options.stderr, options.stderr_copy.as_ref()));
343    let spawned = spawn::start(command, options.scope, options.around_spawn.as_ref())
344        .map_err(RunError::Start)?;
345    let (mut group, started) = spawned.into_parts();
346    let notice = Arc::new(Notice::default());
347    if let Some(cancel) = &options.cancel {
348        cancel.watch(&notice);
349    }
350    let ends = Ends::default();
351    let followed = std::thread::scope(|threads| {
352        let unwind = Unwind {
353            group: &mut group,
354            ends: &ends,
355            options,
356        };
357        follow(threads, &mut *unwind.group, &notice, &ends, options)
358    });
359    let (outcome, status, stdout, stderr, survivors) = followed.map_err(RunError::Run)?;
360    Ok(ChildFinished {
361        outcome,
362        status: Some(status),
363        first_stdout: stdout.first.map(|first| first - started),
364        survivors,
365        stdout: stdout.captured,
366        stderr: stderr.captured,
367    })
368}
369
370/// Returns the standard stream for an output with `capture` and `copy`. A
371/// copy needs a pipe even when the capture keeps nothing. An inherited
372/// stream stays the tool's own, so a copy of it receives nothing.
373fn output_stdio(capture: &Capture, copy: Option<&OutputCopy>) -> Stdio {
374    if copy.is_some() && !matches!(capture, Capture::Inherit) {
375        Stdio::piped()
376    } else {
377        capture.stdio()
378    }
379}
380
381/// Ends the line queues of a run when the run returns, on every path.
382struct EndLines<'run>(&'run RunOptions);
383
384impl Drop for EndLines<'_> {
385    fn drop(&mut self) {
386        self.0.stdout.end();
387        self.0.stderr.end();
388    }
389}
390
391/// Ends the threads of a run when [`follow`] returns, which matters when it
392/// panics: it kills the child unless the group has been reaped, makes the
393/// readers and the writer stop waiting on their pipes, and makes each line
394/// queue drop instead of waiting. The scope then joins every thread, and
395/// the group's drop reaps the child. On a normal return each of these has
396/// already happened or does nothing.
397struct Unwind<'a> {
398    group: &'a mut Group,
399    ends: &'a Ends,
400    options: &'a RunOptions,
401}
402
403impl Drop for Unwind<'_> {
404    fn drop(&mut self) {
405        // A reaped group refuses the signal, so the kill never reaches a
406        // process id that another process may have taken.
407        let _ = self.group.signal(Signal::Kill);
408        self.ends.set(Instant::now());
409        self.options.stopping();
410    }
411}
412
413/// The threads of one run: the waiter, the readers and the writer.
414struct Started<'scope> {
415    waiter: ScopedJoinHandle<'scope, io::Result<()>>,
416    stdout: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
417    stderr: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
418    stdin: Option<ScopedJoinHandle<'scope, ()>>,
419}
420
421/// Follows the child of `group` to its end within `threads`, and returns
422/// its exit, its reaped status and what the readers kept.
423fn follow<'scope>(
424    threads: &'scope Threads<'scope, '_>,
425    group: &mut Group,
426    notice: &'scope Notice,
427    ends: &'scope Ends,
428    options: &'scope RunOptions,
429) -> io::Result<(Outcome, Status, Kept, Kept, bool)> {
430    let pipes = (group.take_stdin(), group.take_stdout(), group.take_stderr());
431    let exit = group.waiter();
432    let waiter = match Builder::new().spawn_scoped(threads, move || {
433        let waited = exit.wait();
434        notice.set(|flags| flags.exited = true);
435        waited
436    }) {
437        Ok(waiter) => waiter,
438        Err(error) => {
439            let _ = group.signal(Signal::Kill);
440            let _ = group.reap();
441            return Err(error);
442        }
443    };
444    let mut started = Started {
445        waiter,
446        stdout: None,
447        stderr: None,
448        stdin: None,
449    };
450    let mut failure = start_pipes(threads, &mut started, pipes, notice, ends, options).err();
451    let stopped = if failure.is_some() {
452        stop(group, notice, &Escalation::default(), options);
453        None
454    } else {
455        control(group, notice, options)
456    };
457    let survivors =
458        options.report_survivors && failure.is_none() && stopped.is_none() && group.others_alive();
459    let status = group.reap();
460    // The child is gone. The queues drop lines from the middle of the drain,
461    // so the reader still has time to read the rest of the pipe and `lost`
462    // can be the stream's last line.
463    let reaped = Instant::now();
464    let after = |grace: Duration| reaped.checked_add(grace).unwrap_or(reaped);
465    ends.set(after(DRAIN_GRACE));
466    options.drain_until(after(DRAIN_GRACE / 2));
467    let exited = joined(started.waiter.join());
468    let stdout = started.stdout.map(|reader| joined(reader.join()));
469    let stderr = started.stderr.map(|reader| joined(reader.join()));
470    if let Some(writer) = started.stdin {
471        let _ = writer.join();
472    }
473    if let Some(failure) = failure.take() {
474        return Err(failure);
475    }
476    exited?;
477    let status = sys::status_of(status?);
478    let exit = stopped.unwrap_or(Outcome::Ended(status));
479    let unread = || Kept {
480        captured: Captured::default(),
481        first: None,
482    };
483    Ok((
484        exit,
485        status,
486        stdout.transpose()?.unwrap_or_else(unread),
487        stderr.transpose()?.unwrap_or_else(unread),
488        survivors,
489    ))
490}
491
492/// Starts the readers of the child's output pipes and the writer of its
493/// input, and records each in `started`.
494fn start_pipes<'scope>(
495    threads: &'scope Threads<'scope, '_>,
496    started: &mut Started<'scope>,
497    (stdin, stdout, stderr): (
498        Option<std::process::ChildStdin>,
499        Option<std::process::ChildStdout>,
500        Option<std::process::ChildStderr>,
501    ),
502    notice: &'scope Notice,
503    ends: &'scope Ends,
504    options: &'scope RunOptions,
505) -> io::Result<()> {
506    let over = || notice.set(|flags| flags.over_limit = true);
507    if let Some(stdout) = stdout {
508        let keeper = Keeper::new(&options.stdout);
509        let copy = options.stdout_copy.as_ref();
510        started.stdout = Some(Builder::new().spawn_scoped(threads, move || {
511            pipes::read(stdout, ends, keeper, copy, over)
512        })?);
513    }
514    if let Some(stderr) = stderr {
515        let keeper = Keeper::new(&options.stderr);
516        let copy = options.stderr_copy.as_ref();
517        started.stderr = Some(Builder::new().spawn_scoped(threads, move || {
518            pipes::read(stderr, ends, keeper, copy, over)
519        })?);
520    }
521    if let (Some(stdin), Input::Bytes(bytes)) = (stdin, &options.stdin) {
522        started.stdin =
523            Some(Builder::new().spawn_scoped(threads, move || pipes::write(stdin, bytes, ends))?);
524    }
525    Ok(())
526}
527
528/// Waits until the child exits or the run must stop it, stops it then, and
529/// returns the exit that the stop gives, or `None` when the child ended on
530/// its own. The child has exited when it returns, and is unreaped.
531fn control(group: &Group, notice: &Notice, options: &RunOptions) -> Option<Outcome> {
532    let flags = notice.wait(options.deadline, |flags| {
533        flags.exited || flags.cancelled || flags.over_limit
534    });
535    let exit = if flags.exited {
536        return None;
537    } else if flags.cancelled {
538        Outcome::Stopped(StopReason::Cancelled)
539    } else if flags.over_limit {
540        Outcome::Stopped(StopReason::OverLimit)
541    } else if group.has_exited().unwrap_or(false) {
542        // The deadline passed after the child exited and before the waiter
543        // said so, so the child's own exit stands.
544        notice.wait(None, |flags| flags.exited);
545        return None;
546    } else {
547        Outcome::TimedOut
548    };
549    stop(group, notice, &options.escalation, options);
550    Some(exit)
551}
552
553/// Stops the child with `escalation`, and returns once the child has exited.
554/// First it tells each line queue of `run` that the run is stopping.
555///
556/// A signal that the operating system refuses is skipped, because the next
557/// step, and in the end the kill, still applies. A grace too long for an
558/// `Instant` waits without a limit.
559///
560/// RUST-10: the stop waits for the child's exit after the kill without a
561/// limit. That handles every child that the tool may signal, and it misses
562/// a child that the kill cannot reach, such as a setuid program that
563/// refuses the tool's signals with `EPERM`, which holds the run until it
564/// exits. A run that gives up on such a child and reports it replaces this
565/// when a caller needs one.
566fn stop(group: &Group, notice: &Notice, escalation: &Escalation, options: &RunOptions) {
567    options.stopping();
568    if sys::GRACEFUL {
569        for (signal, grace) in escalation.steps() {
570            let _ = group.signal(signal);
571            if notice
572                .wait(Instant::now().checked_add(grace), |flags| flags.exited)
573                .exited
574            {
575                return;
576            }
577        }
578    }
579    let _ = group.signal(Signal::Kill);
580    notice.wait(None, |flags| flags.exited);
581}
582
583/// Returns a thread's result, or an error when the thread panicked, which
584/// only a broken invariant in the crate can cause.
585fn joined<T>(result: std::thread::Result<io::Result<T>>) -> io::Result<T> {
586    result.unwrap_or_else(|_| Err(io::Error::other("a thread of the run stopped")))
587}