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(¬ice);
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, ¬ice, &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}