running_process/
types.rs

1use std::path::PathBuf;
2
3use thiserror::Error;
4
5/// Output stream selector used by process read and capture APIs.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum StreamKind {
8    /// Standard output.
9    Stdout,
10    /// Standard error.
11    Stderr,
12}
13
14impl StreamKind {
15    /// Return the stable lowercase stream name.
16    pub fn as_str(self) -> &'static str {
17        match self {
18            Self::Stdout => "stdout",
19            Self::Stderr => "stderr",
20        }
21    }
22}
23
24/// One captured line or chunk tagged with its source stream.
25#[derive(Debug, Clone, PartialEq, Eq)]
26pub struct StreamEvent {
27    /// Stream that produced `line`.
28    pub stream: StreamKind,
29    /// Raw bytes read from the stream.
30    pub line: Vec<u8>,
31}
32
33/// Result of a bounded process read operation.
34#[derive(Debug, Clone, PartialEq, Eq)]
35pub enum ReadStatus<T> {
36    /// A line or chunk was read.
37    Line(T),
38    /// The read deadline elapsed before data arrived.
39    Timeout,
40    /// The stream reached end-of-file.
41    Eof,
42}
43
44/// Error returned by process lifecycle and I/O operations.
45#[derive(Debug, Error)]
46pub enum ProcessError {
47    /// Start was requested for a process that has already been started.
48    #[error("process already started")]
49    AlreadyStarted,
50    /// The operation requires a running child process.
51    #[error("process is not running")]
52    NotRunning,
53    /// The process was not configured with piped stdin.
54    #[error("process stdin is not available")]
55    StdinUnavailable,
56    /// Child process creation failed.
57    #[error("failed to spawn process: {0}")]
58    Spawn(std::io::Error),
59    /// Reading or writing child process streams failed.
60    #[error("failed to read process output: {0}")]
61    Io(std::io::Error),
62    /// The requested wait or read operation timed out.
63    #[error("process timed out")]
64    Timeout,
65}
66
67/// Captured output and exit status returned by one-shot process helpers.
68#[derive(Debug, Clone, PartialEq, Eq)]
69pub struct RunOutput {
70    /// Raw stdout bytes captured from the child.
71    pub stdout: Vec<u8>,
72    /// Raw stderr bytes captured from the child.
73    pub stderr: Vec<u8>,
74    /// Process exit code, with Unix signal exits represented as negative signal numbers.
75    pub exit_code: i32,
76}
77
78/// Command representation used by [`ProcessConfig`].
79#[derive(Debug, Clone)]
80pub enum CommandSpec {
81    /// Execute a command line through the platform shell.
82    Shell(String),
83    /// Execute a program and argument vector directly.
84    Argv(Vec<String>),
85}
86
87/// Stdin behavior for a spawned process.
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89pub enum StdinMode {
90    /// Inherit stdin from the current process.
91    Inherit,
92    /// Create a pipe so callers can write to child stdin.
93    Piped,
94    /// Connect child stdin to the platform null device.
95    Null,
96}
97
98/// Stderr handling for a spawned process.
99#[derive(Debug, Clone, Copy, PartialEq, Eq)]
100pub enum StderrMode {
101    /// Merge stderr into stdout handling.
102    Stdout,
103    /// Capture stderr through its own pipe.
104    Pipe,
105}
106
107/// Configuration for [`crate::NativeProcess`].
108#[derive(Debug, Clone)]
109pub struct ProcessConfig {
110    /// Command line or argv to execute.
111    pub command: CommandSpec,
112    /// Working directory for the child process.
113    pub cwd: Option<PathBuf>,
114    /// Environment overrides passed to the child process.
115    pub env: Option<Vec<(String, String)>>,
116    /// Whether stdout/stderr should be retained in capture history.
117    pub capture: bool,
118    /// How stderr should be routed.
119    pub stderr_mode: StderrMode,
120    /// Windows process creation flags.
121    pub creationflags: Option<u32>,
122    /// Whether to create a new process group where supported.
123    pub create_process_group: bool,
124    /// How stdin should be routed.
125    pub stdin_mode: StdinMode,
126    /// Nice value to apply on Unix-like platforms.
127    pub nice: Option<i32>,
128}
running_process/types.rs

running_process/
types.rs
