Struct CommandRunner

Source

pub struct CommandRunner { /* private fields */ }

Expand description

Runs external commands and captures their output.

CommandRunner runs one Command synchronously on the caller thread and returns captured process output. The runner always preserves raw output bytes up to the configured per-stream limits. Use CommandOutput::stdout_text and CommandOutput::stderr_text for strict UTF-8 text, or CommandOutput::stdout_lossy_text and CommandOutput::stderr_lossy_text when invalid UTF-8 should be replaced.

Implementations§

Source §

impl CommandRunner

Source

pub fn new() -> Self

Creates a command runner with default settings.

§Returns

A runner with no timeout, inherited working directory, success exit code 0, unlimited in-memory output capture, and no output tee files.

Source

pub const fn timeout(self, timeout: Duration) -> Self

Sets the command timeout.

§Parameters

timeout - Maximum duration allowed for each command.

§Returns

The updated command runner.

Source

pub const fn without_timeout(self) -> Self

Disables timeout handling.

§Returns

The updated command runner.

Source

pub fn working_directory(self, working_directory: P) -> Self
where P: Into<PathBuf>,

Sets the default working directory.

§Parameters

working_directory - Directory used when a command has no per-command working directory override.

§Returns

The updated command runner.

Source

pub fn success_exit_code(self, exit_code: i32) -> Self

Sets the only exit code treated as successful.

§Parameters

exit_code - Exit code considered successful.

§Returns

The updated command runner.

Source

pub fn success_exit_codes(self, exit_codes: &[i32]) -> Self

Sets all exit codes treated as successful.

§Parameters

exit_codes - Exit codes considered successful.

§Returns

The updated command runner.

Source

pub const fn disable_logging(self, disable_logging: bool) -> Self

Enables or disables command execution logs.

§Parameters

disable_logging - true to suppress runner logs.

§Returns

The updated command runner.

Source

pub fn sensitive_field(self, field: &str, level: SensitivityLevel) -> Self

Adds one sensitive field name for command diagnostics.

The field is appended to the default qubit-sanitize policy used for command text in runner logs and CommandError::command. Command’s standalone Debug output has no runner context and uses the default policy only. Matching uses NameMatchMode::ExactOrSuffix, so contextual names such as TENANT_OPTION match tenant_option.

§Parameters

field - Field or option name that should be treated as sensitive.
level - Sensitivity level controlling how values are masked.

§Returns

The updated command runner.

Source

pub fn sensitive_fields(self, fields: &[&str], level: SensitivityLevel) -> Self

Adds multiple sensitive field names for command diagnostics.

This is the batch form of Self::sensitive_field. The fields extend the default qubit-sanitize policy used by runner logs and CommandError::command; standalone Command Debug output still uses only the built-in default policy because it has no runner context.

§Parameters

fields - Field or option names that should be treated as sensitive.
level - Sensitivity level applied to every provided field.

§Returns

The updated command runner.

Source

pub const fn max_stdout_bytes(self, max_bytes: usize) -> Self

Sets the maximum stdout bytes retained in memory.

The reader still drains the complete stdout stream. Bytes beyond this limit are not retained in CommandOutput, but they are still written to a configured stdout tee file.

§Parameters

max_bytes - Maximum number of stdout bytes to retain.

§Returns

The updated command runner.

Source

pub const fn max_stderr_bytes(self, max_bytes: usize) -> Self

Sets the maximum stderr bytes retained in memory.

The reader still drains the complete stderr stream. Bytes beyond this limit are not retained in CommandOutput, but they are still written to a configured stderr tee file.

§Parameters

max_bytes - Maximum number of stderr bytes to retain.

§Returns

The updated command runner.

Source

pub const fn max_output_bytes(self, max_bytes: usize) -> Self

Sets the same in-memory capture limit for stdout and stderr.

§Parameters

max_bytes - Maximum number of bytes retained for each stream.

§Returns

The updated command runner.

Source

pub fn tee_stdout_to_file(self, path: P) -> Self
where P: Into<PathBuf>,

Streams stdout to a file while still capturing it in memory.

The file is created or truncated before the command is spawned. Combine this with Self::max_stdout_bytes to avoid unbounded memory use for large stdout streams.

§Parameters

path - Destination file path for stdout bytes.

§Returns

The updated command runner.

Source

pub fn tee_stderr_to_file(self, path: P) -> Self
where P: Into<PathBuf>,

Streams stderr to a file while still capturing it in memory.

The file is created or truncated before the command is spawned. Combine this with Self::max_stderr_bytes to avoid unbounded memory use for large stderr streams.

§Parameters

path - Destination file path for stderr bytes.

§Returns

The updated command runner.

Source

pub const fn configured_timeout(&self) -> Option<Duration>

Returns the configured timeout.

§Returns

Some(duration) when timeout handling is enabled, otherwise None.

Source

pub fn configured_working_directory(&self) -> Option<&Path>

Returns the default working directory.

§Returns

Some(path) when a default working directory is configured, otherwise None to inherit the current process working directory.

Source

pub fn configured_success_exit_codes(&self) -> &[i32]

Returns the configured successful exit codes.

§Returns

Borrowed list of exit codes treated as successful.

Source

pub const fn is_logging_disabled(&self) -> bool

Returns whether logging is disabled.

§Returns

true when runner logs are disabled.

Source

pub const fn configured_max_stdout_bytes(&self) -> Option<usize>

Returns the configured stdout capture limit.

§Returns

Some(max_bytes) when stdout capture is limited, otherwise None.

Source

pub const fn configured_max_stderr_bytes(&self) -> Option<usize>

Returns the configured stderr capture limit.

§Returns

Some(max_bytes) when stderr capture is limited, otherwise None.

Source

pub fn configured_stdout_file(&self) -> Option<&Path>

Returns the stdout tee file path.

§Returns

Some(path) when stdout is streamed to a file, otherwise None.

Source

pub fn configured_stderr_file(&self) -> Option<&Path>

Returns the stderr tee file path.

§Returns

Some(path) when stderr is streamed to a file, otherwise None.

Source

pub fn run(&self, command: Command) -> Result<CommandOutput, CommandError>

Runs a command and captures stdout and stderr.

This method blocks the caller thread until the command exits and its I/O helpers finish, or until the configured timeout is reached. When a timeout is configured, Unix children run as leaders of new process groups and Windows children run in Job Objects. This lets timeout killing target the process tree instead of only the direct child process, including cases where the direct child exits but descendants keep inherited stdout or stderr pipes open. Without a configured timeout, commands use the platform’s normal process-spawning behavior.

Captured output is retained as raw bytes up to the configured per-stream limits. Reader threads still drain complete streams so the child is not blocked on full pipes. Use CommandOutput::stdout_text and CommandOutput::stderr_text for strict UTF-8 text, or CommandOutput::stdout_lossy_text and CommandOutput::stderr_lossy_text when invalid UTF-8 should be replaced.

§Parameters

command - Structured command to run.

§Returns

Captured output when the process exits with a configured success code.

§Errors

Returns CommandError if the process cannot be spawned, cannot be waited on, times out, cannot be killed after timing out, emits output that cannot be read or written to a tee file, cannot receive configured stdin, or exits with a code not configured as successful.