rskit-process

Process and subprocess execution with explicit I/O modes, timeout handling, and process-tree termination.

Mode selection

PTY-backed terminal fidelity and live parent-stdin forwarding are intentionally not exposed until those modes are implemented with documented platform guarantees.

Line observers split deterministically on \n, \r, and \r\n. Invalid UTF-8 is passed to line observers lossily; use raw-byte observers for binary output.

Capturing output

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

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let spec = ProcessSpec::new("echo").arg("hello");
let config = ProcessConfig::default().with_max_output_bytes(1024 * 1024);

let result = run_with_cancel(&spec, &config, CancellationToken::new()).await?;
result.check()?;
println!("{}", result.stdout);
# Ok(())
# }

Observing output

use rskit_process::{
    ObservedIo, OutputObserver, OutputPolicy, ProcessConfig, ProcessIo, ProcessSpec,
    run_with_cancel,
};
use tokio_util::sync::CancellationToken;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let spec = ProcessSpec::new("printf").arg("hello\n");
let observer = OutputObserver::new().with_stdout_line(|line| {
    eprintln!("child stdout: {line}");
});
let config = ProcessConfig::default().with_io(ProcessIo::observed(
    ObservedIo::new(observer).with_output(OutputPolicy::observe_only()),
));

let result = run_with_cancel(&spec, &config, CancellationToken::new()).await?;
result.check()?;
# Ok(())
# }

Predefined stdin

use rskit_process::{InputPolicy, ProcessConfig, ProcessSpec, run_with_cancel};
use tokio_util::sync::CancellationToken;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let spec = ProcessSpec::new("cat");
let config = ProcessConfig::default().with_input(InputPolicy::Bytes(b"hello".to_vec()));

let result = run_with_cancel(&spec, &config, CancellationToken::new()).await?;
assert_eq!(result.stdout, "hello");
# Ok(())
# }

Inherited terminal stdio

use rskit_process::{InheritedIo, ProcessConfig, ProcessIo, ProcessSpec, run_with_cancel};
use tokio_util::sync::CancellationToken;

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let spec = ProcessSpec::new("printf").args(["%s\n", "terminal output"]);
let config = ProcessConfig::default().with_io(ProcessIo::inherited(InheritedIo::new()));

let result = run_with_cancel(&spec, &config, CancellationToken::new()).await?;
result.check()?;
assert!(result.stdout.is_empty());
# Ok(())
# }

Timeout and process groups

By default, rskit-process creates an isolated process group where the platform supports it. On timeout or cancellation, it sends a graceful termination signal, waits for SignalPolicy::grace_period, then escalates to kill. Inherited mode is the exception: it does not create a new process group, because terminal-native commands should remain in the parent's foreground terminal context unless a future terminal-control mode provides stronger guarantees.

Separate stdout and stderr pipes are read concurrently, so each stream is ordered internally, but exact ordering across streams is not guaranteed.

Process start logs redact secret-looking argument values, but argv is still visible to operating-system process inspection on many platforms. Prefer stdin, files with restricted permissions, or environment-specific secret mechanisms for sensitive values instead of command-line arguments.

Custom secret-bearing argument names can be added to the spawn-log redaction policy:

use rskit_process::{ArgRedaction, ProcessConfig};

let config = ProcessConfig::default()
    .with_arg_redaction(ArgRedaction::default().with_name("license-key"));