Struct SpawnSpec 

pub struct SpawnSpec { /* private fields */ }

A child process about to be launched.

A builder rather than a bare Command so that the arguments and the environment can be inspected before the launch — which is what SpawnSpec::spawn_with_handoff does.

Implementations

impl SpawnSpec

pub fn new(program: impl Into<PathBuf>) -> Self

Starts a specification for program.

pub fn arg(self, arg: impl AsRef<OsStr>) -> Self

Appends one argument.

pub fn args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Appends several arguments.

pub fn env(self, key: impl AsRef<OsStr>, value: impl AsRef<OsStr>) -> Self

Sets one environment variable for the child, on top of the inherited environment.

pub fn working_dir(self, dir: impl Into<PathBuf>) -> Self

Sets the child’s working directory.

pub fn output(self, output: OutputMode) -> Self

Chooses what happens to the child’s output.

pub fn expect_normal_scheduling(self) -> Self

Declares that the child must run at normal scheduling priority, and has the launch say so when it does not.

On macOS the parent reads the child’s base priority back after the spawn and logs a warning when it is at the background ceiling. A throttled runner still runs its job correctly, only 4 to 20 times slower, so this reports rather than refuses.

Nothing here changes the child’s priority. Under launchd the priority comes from the job’s ProcessType, which every descendant inherits and none can leave (crate::service::LAUNCHD_PROCESS_TYPE has the measurements), so the fix belongs in the plist. 0.4.31 cleared PRIO_DARWIN_PROCESS between fork and exec instead; the call succeeded and the runner stayed at 4, and this warning is what showed it.

No effect on other platforms.

pub fn arguments(&self) -> &[OsString]

The arguments as configured. Exposed so a security test can assert what a process listing would show.

pub fn configured_env(&self, name: &str) -> Option<&OsStr>

The variable the child gets for name, as configured on top of the inherited environment: the last Self::env for it wins, as it does in the child. Names compare without case on Windows, as Windows does.

pub fn spawn(&self) -> Result<ChildProcess, ProcessError>

Launches the child.

Errors

ProcessError::Spawn when the program cannot be launched, and ProcessError::Identity when it launches but its start time cannot be read — which would leave an unrecordable process running, so the child is killed rather than leaked.

pub fn spawn_with_handoff( &self, handoff: &RestrictiveHandoff, ) -> Result<ChildProcess, ProcessError>

Launches the child after proving the handoff payload is not in the command line or the environment.

This is the enforcement point for 07-security.md’s control on “A process listing reveals a JIT config”. e3 should reach for this and not for SpawnSpec::spawn, because a rule that is checked is a rule, and a rule that is written down is a hope.

Errors

ProcessError::SecretInCommandLine when the payload appears in an argument or an environment value, plus everything SpawnSpec::spawn returns.

pub fn spawn_runner_with_handoff( &self, handoff: &RestrictiveHandoff, ) -> Result<ChildProcess, ProcessError>

Launches GitHub Runner using its supported process-safe JIT input.

The encoded configuration is deliberately absent from SpawnSpec: callers cannot render it as an argument or accidentally retain it in a reusable specification. It is copied from the restrictive handoff into the child’s initial environment at the final Command::spawn boundary. GitHub Runner’s CommandSettings treats jitconfig as a secret and removes ACTIONS_RUNNER_INPUT_JITCONFIG from the process environment before executing the run command.

The caller still owns deleting handoff immediately after this method returns. A failed launch leaves deletion to RestrictiveHandoff’s fail-closed Drop implementation.

Errors

ProcessError::SecretInCommandLine when the payload was also placed in an argument or explicitly configured environment value, plus every error returned by SpawnSpec::spawn.

Trait Implementations

impl Clone for SpawnSpec

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SpawnSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.