Crate rskit_process

Expand description

Subprocess execution with explicit I/O modes, process-group isolation, and timeouts.

This crate provides functionality to execute external processes with:

Timeout support with configurable grace period
SIGTERM → SIGKILL escalation for graceful shutdown
Process group isolation to ensure child processes are properly terminated
Explicit captured, observed, and inherited stdio modes
Environment variable control
Working directory configuration

§I/O modes

ProcessIo::Captured captures stdout and stderr separately through pipes. It is deterministic for non-interactive commands, but it is not a terminal and cannot guarantee exact ordering between stdout and stderr.

ProcessIo::Observed also uses separate pipes and supports live raw-byte or line callbacks with optional capture. Line observers split deterministically on \n, \r, and \r\n; invalid UTF-8 is reported lossily.

ProcessIo::Inherited gives the child the parent stdio handles. This is the right mode for normal terminal commands, but it does not provide structured output capture.

§Example

use rskit_process::{ProcessConfig, ProcessSpec, run_with_cancel};
use std::time::Duration;
use tokio_util::sync::CancellationToken;

let spec = ProcessSpec::new("echo")
    .arg("hello")
    .arg("world");

let config = ProcessConfig::default().with_timeout(Some(Duration::from_secs(30)));

let result = run_with_cancel(&spec, &config, CancellationToken::new()).await?;
println!("stdout: {}", result.stdout);
println!("exit code: {:?}", result.exit_code);

Structs§

AppError: Re-export error types Application-level structured error.
ArgRedaction: Redaction policy for command-line arguments emitted in process spawn logs.
CapturedIo: Pipe-backed deterministic capture mode.
InheritedIo: Inherited terminal stdio mode.
ObservedIo: Pipe-backed live observation mode with optional capture.
OutputObserver: Optional callbacks for line-oriented process output.
OutputPolicy: Output capture policy for pipe-backed modes.
PersistentConfig: Configuration for a persistent process.
PersistentOutput: Persistent process output forwarding policy.
PersistentOutputObserver: Byte observers for persistent process output.
PersistentProcess: Running persistent process.
PersistentRun: Result of starting a persistent process.
PersistentStartup: Captured output retained while waiting for persistent readiness.
ProcessConfig: Configuration for subprocess execution behavior.
ProcessResult: Result of a completed subprocess execution.
ProcessSpec: What to execute as a subprocess.
PtyIo: Pseudoterminal-backed I/O mode.
PtySize: Window size of a pseudoterminal, in character cells plus optional pixels.
SignalPolicy: Signal and process-tree termination policy.

Enums§

EnvPolicy: Command environment policy.
ErrorCode: Re-export error types Machine-readable error code.
InputPolicy: Standard input policy.
PersistentOutputStream: Parent stream used for forwarding persistent output.
PersistentReadiness: Persistent process readiness policy.
PersistentStartErrorKind: Machine-readable persistent process startup failure classification.
ProcessIo: Process I/O strategy.
ShutdownOutcome: Outcome of requesting persistent process shutdown.

Constants§

DEFAULT_MAX_OUTPUT_BYTES: Default maximum retained bytes for each captured output stream.

Functions§

command: Create a subprocess specification.
interrupt_process_group: Request graceful interruption for the process group led by the provided child PID.
isolate_process_group: Configure a command so the spawned child becomes the leader of a new process group.
kill_process_group: Forcefully terminate the process group led by the provided child PID.
persistent_start_error_kind: Return the structured persistent startup error kind attached to an AppError.
run: Execute a subprocess on the current thread using captured or inherited I/O mode.
run_with_cancel: Execute a subprocess with the given configuration and cancellation token.
start_persistent_with_cancel: Start a persistent process and wait for its readiness policy.
terminal_size: Query the window size of the terminal backing fd.
terminate_process_group: Request graceful termination for the process group led by the provided child PID.

Type Aliases§

AppResult: Re-export error types Convenience alias used throughout rskit crates.