qubit_command/
command_runner.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2026 Haixing Hu.
4 *
5 *    SPDX-License-Identifier: Apache-2.0
6 *
7 *    Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10use std::{
11    path::{
12        Path,
13        PathBuf,
14    },
15    time::Duration,
16};
17
18use qubit_sanitize::{
19    FieldSanitizer,
20    SensitivityLevel,
21};
22
23pub(crate) mod captured_output;
24pub(crate) mod command_io;
25pub(crate) mod error_mapping;
26pub(crate) mod finished_command;
27pub(crate) mod managed_child_process;
28pub(crate) mod output_capture_error;
29pub(crate) mod output_capture_options;
30pub(crate) mod output_collector;
31pub(crate) mod output_reader;
32pub(crate) mod output_tee;
33pub(crate) mod prepared_command;
34pub(crate) mod process_launcher;
35pub(crate) mod process_setup;
36pub(crate) mod running_command;
37pub(crate) mod stdin_pipe;
38pub(crate) mod stdin_writer;
39pub(crate) mod wait_policy;
40
41use command_io::CommandIo;
42use error_mapping::{
43    output_pipe_error,
44    spawn_failed,
45};
46use finished_command::FinishedCommand;
47use output_capture_options::OutputCaptureOptions;
48use output_collector::read_output_stream;
49use prepared_command::PreparedCommand;
50use process_launcher::spawn_child;
51use running_command::RunningCommand;
52use stdin_pipe::write_stdin_bytes;
53
54use crate::{
55    Command,
56    CommandError,
57    CommandOutput,
58    OutputStream,
59};
60
61/// Predefined ten-second timeout value.
62///
63/// `CommandRunner::new` does not apply this timeout automatically. Use this
64/// constant with [`CommandRunner::timeout`] when callers want a short, explicit
65/// command limit.
66pub const DEFAULT_COMMAND_TIMEOUT: Duration = Duration::from_secs(10);
67
68/// Runs external commands and captures their output.
69///
70/// `CommandRunner` runs one [`Command`] synchronously on the caller thread and
71/// returns captured process output. The runner always preserves raw output bytes
72/// up to the configured per-stream limits. Use
73/// [`CommandOutput::stdout_text`] and [`CommandOutput::stderr_text`] for strict
74/// UTF-8 text, or [`CommandOutput::stdout_lossy_text`] and
75/// [`CommandOutput::stderr_lossy_text`] when invalid UTF-8 should be replaced.
76///
77#[derive(Debug, Clone, PartialEq, Eq)]
78pub struct CommandRunner {
79    /// Maximum duration allowed for each command.
80    timeout: Option<Duration>,
81    /// Default working directory used when a command does not override it.
82    working_directory: Option<PathBuf>,
83    /// Exit codes treated as successful.
84    success_exit_codes: Vec<i32>,
85    /// Whether command execution logs are disabled.
86    disable_logging: bool,
87    /// Field sanitizer used for command diagnostics and logs.
88    diagnostic_sanitizer: FieldSanitizer,
89    /// Maximum stdout bytes retained in memory.
90    max_stdout_bytes: Option<usize>,
91    /// Maximum stderr bytes retained in memory.
92    max_stderr_bytes: Option<usize>,
93    /// File that receives a streaming copy of stdout.
94    stdout_file: Option<PathBuf>,
95    /// File that receives a streaming copy of stderr.
96    stderr_file: Option<PathBuf>,
97}
98
99impl Default for CommandRunner {
100    /// Creates a command runner with the default exit-code policy.
101    ///
102    /// # Returns
103    ///
104    /// A runner with no timeout, inherited working directory, success exit code
105    /// `0`, unlimited in-memory output capture, and no output tee files.
106    #[inline]
107    fn default() -> Self {
108        Self {
109            timeout: None,
110            working_directory: None,
111            success_exit_codes: vec![0],
112            disable_logging: false,
113            diagnostic_sanitizer: FieldSanitizer::default(),
114            max_stdout_bytes: None,
115            max_stderr_bytes: None,
116            stdout_file: None,
117            stderr_file: None,
118        }
119    }
120}
121
122impl CommandRunner {
123    /// Creates a command runner with default settings.
124    ///
125    /// # Returns
126    ///
127    /// A runner with no timeout, inherited working directory, success exit code
128    /// `0`, unlimited in-memory output capture, and no output tee files.
129    #[inline]
130    pub fn new() -> Self {
131        Self::default()
132    }
133
134    /// Sets the command timeout.
135    ///
136    /// # Parameters
137    ///
138    /// * `timeout` - Maximum duration allowed for each command.
139    ///
140    /// # Returns
141    ///
142    /// The updated command runner.
143    #[inline]
144    pub const fn timeout(mut self, timeout: Duration) -> Self {
145        self.timeout = Some(timeout);
146        self
147    }
148
149    /// Disables timeout handling.
150    ///
151    /// # Returns
152    ///
153    /// The updated command runner.
154    #[inline]
155    pub const fn without_timeout(mut self) -> Self {
156        self.timeout = None;
157        self
158    }
159
160    /// Sets the default working directory.
161    ///
162    /// # Parameters
163    ///
164    /// * `working_directory` - Directory used when a command has no
165    ///   per-command working directory override.
166    ///
167    /// # Returns
168    ///
169    /// The updated command runner.
170    #[inline]
171    pub fn working_directory<P>(mut self, working_directory: P) -> Self
172    where
173        P: Into<PathBuf>,
174    {
175        self.working_directory = Some(working_directory.into());
176        self
177    }
178
179    /// Sets the only exit code treated as successful.
180    ///
181    /// # Parameters
182    ///
183    /// * `exit_code` - Exit code considered successful.
184    ///
185    /// # Returns
186    ///
187    /// The updated command runner.
188    #[inline]
189    pub fn success_exit_code(mut self, exit_code: i32) -> Self {
190        self.success_exit_codes = vec![exit_code];
191        self
192    }
193
194    /// Sets all exit codes treated as successful.
195    ///
196    /// # Parameters
197    ///
198    /// * `exit_codes` - Exit codes considered successful.
199    ///
200    /// # Returns
201    ///
202    /// The updated command runner.
203    #[inline]
204    pub fn success_exit_codes(mut self, exit_codes: &[i32]) -> Self {
205        self.success_exit_codes = exit_codes.to_vec();
206        self
207    }
208
209    /// Enables or disables command execution logs.
210    ///
211    /// # Parameters
212    ///
213    /// * `disable_logging` - `true` to suppress runner logs.
214    ///
215    /// # Returns
216    ///
217    /// The updated command runner.
218    #[inline]
219    pub const fn disable_logging(mut self, disable_logging: bool) -> Self {
220        self.disable_logging = disable_logging;
221        self
222    }
223
224    /// Adds one sensitive field name for command diagnostics.
225    ///
226    /// The field is appended to the default `qubit-sanitize` policy used for
227    /// command text in runner logs and [`CommandError::command`]. `Command`'s
228    /// standalone [`Debug`](std::fmt::Debug) output has no runner context and
229    /// uses the default policy only. Matching uses
230    /// [`NameMatchMode::ExactOrSuffix`](qubit_sanitize::NameMatchMode::ExactOrSuffix),
231    /// so contextual names such as `TENANT_OPTION` match `tenant_option`.
232    ///
233    /// # Parameters
234    ///
235    /// * `field` - Field or option name that should be treated as sensitive.
236    /// * `level` - Sensitivity level controlling how values are masked.
237    ///
238    /// # Returns
239    ///
240    /// The updated command runner.
241    #[inline]
242    pub fn sensitive_field(mut self, field: &str, level: SensitivityLevel) -> Self {
243        self.diagnostic_sanitizer.insert_sensitive_field(field, level);
244        self
245    }
246
247    /// Adds multiple sensitive field names for command diagnostics.
248    ///
249    /// This is the batch form of [`Self::sensitive_field`]. The fields extend
250    /// the default `qubit-sanitize` policy used by runner logs and
251    /// [`CommandError::command`]; standalone [`Command`](crate::Command)
252    /// [`Debug`](std::fmt::Debug) output still uses only the built-in default
253    /// policy because it has no runner context.
254    ///
255    /// # Parameters
256    ///
257    /// * `fields` - Field or option names that should be treated as sensitive.
258    /// * `level` - Sensitivity level applied to every provided field.
259    ///
260    /// # Returns
261    ///
262    /// The updated command runner.
263    #[inline]
264    pub fn sensitive_fields(mut self, fields: &[&str], level: SensitivityLevel) -> Self {
265        self.diagnostic_sanitizer
266            .extend_sensitive_fields(fields.iter().copied(), level);
267        self
268    }
269
270    /// Sets the maximum stdout bytes retained in memory.
271    ///
272    /// The reader still drains the complete stdout stream. Bytes beyond this
273    /// limit are not retained in [`CommandOutput`], but they are still written to
274    /// a configured stdout tee file.
275    ///
276    /// # Parameters
277    ///
278    /// * `max_bytes` - Maximum number of stdout bytes to retain.
279    ///
280    /// # Returns
281    ///
282    /// The updated command runner.
283    #[inline]
284    pub const fn max_stdout_bytes(mut self, max_bytes: usize) -> Self {
285        self.max_stdout_bytes = Some(max_bytes);
286        self
287    }
288
289    /// Sets the maximum stderr bytes retained in memory.
290    ///
291    /// The reader still drains the complete stderr stream. Bytes beyond this
292    /// limit are not retained in [`CommandOutput`], but they are still written to
293    /// a configured stderr tee file.
294    ///
295    /// # Parameters
296    ///
297    /// * `max_bytes` - Maximum number of stderr bytes to retain.
298    ///
299    /// # Returns
300    ///
301    /// The updated command runner.
302    #[inline]
303    pub const fn max_stderr_bytes(mut self, max_bytes: usize) -> Self {
304        self.max_stderr_bytes = Some(max_bytes);
305        self
306    }
307
308    /// Sets the same in-memory capture limit for stdout and stderr.
309    ///
310    /// # Parameters
311    ///
312    /// * `max_bytes` - Maximum number of bytes retained for each stream.
313    ///
314    /// # Returns
315    ///
316    /// The updated command runner.
317    #[inline]
318    pub const fn max_output_bytes(mut self, max_bytes: usize) -> Self {
319        self.max_stdout_bytes = Some(max_bytes);
320        self.max_stderr_bytes = Some(max_bytes);
321        self
322    }
323
324    /// Streams stdout to a file while still capturing it in memory.
325    ///
326    /// The file is created or truncated before the command is spawned. Combine
327    /// this with [`Self::max_stdout_bytes`] to avoid unbounded memory use for
328    /// large stdout streams.
329    ///
330    /// # Parameters
331    ///
332    /// * `path` - Destination file path for stdout bytes.
333    ///
334    /// # Returns
335    ///
336    /// The updated command runner.
337    #[inline]
338    pub fn tee_stdout_to_file<P>(mut self, path: P) -> Self
339    where
340        P: Into<PathBuf>,
341    {
342        self.stdout_file = Some(path.into());
343        self
344    }
345
346    /// Streams stderr to a file while still capturing it in memory.
347    ///
348    /// The file is created or truncated before the command is spawned. Combine
349    /// this with [`Self::max_stderr_bytes`] to avoid unbounded memory use for
350    /// large stderr streams.
351    ///
352    /// # Parameters
353    ///
354    /// * `path` - Destination file path for stderr bytes.
355    ///
356    /// # Returns
357    ///
358    /// The updated command runner.
359    #[inline]
360    pub fn tee_stderr_to_file<P>(mut self, path: P) -> Self
361    where
362        P: Into<PathBuf>,
363    {
364        self.stderr_file = Some(path.into());
365        self
366    }
367
368    /// Returns the configured timeout.
369    ///
370    /// # Returns
371    ///
372    /// `Some(duration)` when timeout handling is enabled, otherwise `None`.
373    #[inline]
374    pub const fn configured_timeout(&self) -> Option<Duration> {
375        self.timeout
376    }
377
378    /// Returns the default working directory.
379    ///
380    /// # Returns
381    ///
382    /// `Some(path)` when a default working directory is configured, otherwise
383    /// `None` to inherit the current process working directory.
384    #[inline]
385    pub fn configured_working_directory(&self) -> Option<&Path> {
386        self.working_directory.as_deref()
387    }
388
389    /// Returns the configured successful exit codes.
390    ///
391    /// # Returns
392    ///
393    /// Borrowed list of exit codes treated as successful.
394    #[inline]
395    pub fn configured_success_exit_codes(&self) -> &[i32] {
396        &self.success_exit_codes
397    }
398
399    /// Returns whether logging is disabled.
400    ///
401    /// # Returns
402    ///
403    /// `true` when runner logs are disabled.
404    #[inline]
405    pub const fn is_logging_disabled(&self) -> bool {
406        self.disable_logging
407    }
408
409    /// Returns the configured stdout capture limit.
410    ///
411    /// # Returns
412    ///
413    /// `Some(max_bytes)` when stdout capture is limited, otherwise `None`.
414    #[inline]
415    pub const fn configured_max_stdout_bytes(&self) -> Option<usize> {
416        self.max_stdout_bytes
417    }
418
419    /// Returns the configured stderr capture limit.
420    ///
421    /// # Returns
422    ///
423    /// `Some(max_bytes)` when stderr capture is limited, otherwise `None`.
424    #[inline]
425    pub const fn configured_max_stderr_bytes(&self) -> Option<usize> {
426        self.max_stderr_bytes
427    }
428
429    /// Returns the stdout tee file path.
430    ///
431    /// # Returns
432    ///
433    /// `Some(path)` when stdout is streamed to a file, otherwise `None`.
434    #[inline]
435    pub fn configured_stdout_file(&self) -> Option<&Path> {
436        self.stdout_file.as_deref()
437    }
438
439    /// Returns the stderr tee file path.
440    ///
441    /// # Returns
442    ///
443    /// `Some(path)` when stderr is streamed to a file, otherwise `None`.
444    #[inline]
445    pub fn configured_stderr_file(&self) -> Option<&Path> {
446        self.stderr_file.as_deref()
447    }
448
449    /// Runs a command and captures stdout and stderr.
450    ///
451    /// This method blocks the caller thread until the command exits and its I/O
452    /// helpers finish, or until the configured timeout is reached. When a
453    /// timeout is configured, Unix children run as leaders of new process
454    /// groups and Windows children run in Job Objects. This lets timeout
455    /// killing target the process tree instead of only the direct child
456    /// process, including cases where the direct child exits but descendants
457    /// keep inherited stdout or stderr pipes open. Without a configured timeout,
458    /// commands use the platform's normal process-spawning behavior.
459    ///
460    /// Captured output is retained as raw bytes up to the configured per-stream
461    /// limits. Reader threads still drain complete streams so the child is not
462    /// blocked on full pipes. Use [`CommandOutput::stdout_text`] and
463    /// [`CommandOutput::stderr_text`] for strict UTF-8 text, or
464    /// [`CommandOutput::stdout_lossy_text`] and
465    /// [`CommandOutput::stderr_lossy_text`] when invalid UTF-8 should be
466    /// replaced.
467    ///
468    /// # Parameters
469    ///
470    /// * `command` - Structured command to run.
471    ///
472    /// # Returns
473    ///
474    /// Captured output when the process exits with a configured success code.
475    ///
476    /// # Errors
477    ///
478    /// Returns [`CommandError`] if the process cannot be spawned, cannot be
479    /// waited on, times out, cannot be killed after timing out, emits output
480    /// that cannot be read or written to a tee file, cannot receive configured
481    /// stdin, or exits with a code not configured as successful.
482    pub fn run(&self, command: Command) -> Result<CommandOutput, CommandError> {
483        let PreparedCommand {
484            command_text,
485            process_command,
486            stdin_bytes,
487            stdout_file,
488            stderr_file,
489            stdout_file_path,
490            stderr_file_path,
491        } = PreparedCommand::prepare(
492            command,
493            &self.diagnostic_sanitizer,
494            self.working_directory.as_deref(),
495            self.stdout_file.as_deref(),
496            self.stderr_file.as_deref(),
497        )?;
498
499        if !self.disable_logging {
500            log::info!("Running command: {command_text}");
501        }
502
503        let mut child_process = match spawn_child(process_command, self.timeout.is_some()) {
504            Ok(child_process) => child_process,
505            Err(source) => return Err(spawn_failed(&command_text, source)),
506        };
507
508        let stdin_writer = write_stdin_bytes(&command_text, child_process.as_mut(), stdin_bytes)?;
509
510        let stdout = match child_process.stdout().take() {
511            Some(stdout) => stdout,
512            None => return Err(output_pipe_error(&command_text, OutputStream::Stdout)),
513        };
514        let stderr = match child_process.stderr().take() {
515            Some(stderr) => stderr,
516            None => return Err(output_pipe_error(&command_text, OutputStream::Stderr)),
517        };
518        let stdout_reader = read_output_stream(
519            Box::new(stdout),
520            OutputCaptureOptions::new(self.max_stdout_bytes, stdout_file, stdout_file_path),
521        );
522        let stderr_reader = read_output_stream(
523            Box::new(stderr),
524            OutputCaptureOptions::new(self.max_stderr_bytes, stderr_file, stderr_file_path),
525        );
526        let command_io = CommandIo::new(stdout_reader, stderr_reader, stdin_writer);
527        let finished =
528            RunningCommand::new(command_text, child_process, command_io).wait_for_completion(self.timeout)?;
529        let FinishedCommand { command_text, output } = finished;
530
531        if output
532            .exit_code()
533            .is_some_and(|exit_code| self.success_exit_codes.contains(&exit_code))
534        {
535            if !self.disable_logging {
536                log::info!("Finished command `{}` in {:?}.", command_text, output.elapsed());
537            }
538            Ok(output)
539        } else {
540            if !self.disable_logging {
541                log::error!("Command `{}` exited with code {:?}.", command_text, output.exit_code());
542            }
543            Err(CommandError::UnexpectedExit {
544                command: command_text,
545                exit_code: output.exit_code(),
546                expected: self.success_exit_codes.clone(),
547                output: Box::new(output),
548            })
549        }
550    }
551}
qubit_command/command_runner.rs

qubit_command/
command_runner.rs
