Struct StartRequest 

#[non_exhaustive]
pub struct StartRequest {
    pub exec_id: String,
    pub command: Vec<String>,
    pub shell: Shell,
    pub cwd: Option<String>,
    pub env: HashMap<String, String>,
    pub user: Option<NameOrId>,
    pub group: Option<NameOrId>,
    pub timeout_sec: Option<f64>,
    pub stdin: bool,
    pub reap_group_on_exit: bool,
    pub poweroff_on_exit: bool,
    pub inherit_image_env: bool,
}

A start request. command is either an argv array or, with shell set, a single script string.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

exec_id: String

Caller-minted idempotency key. Harbor retries, and a retry must not produce a second child.

command: Vec<String>

argv when shell is false, or the script when it is set.

shell: Shell

false, true (/bin/sh -c), or a shell name such as "bash". A name the guest cannot resolve answers 400 unknown_shell before anything is spawned.

cwd: Option<String>

Omitted means inherit the daemon’s working directory. See the module docs.

env: HashMap<String, String>

user: Option<NameOrId>

The user to demote to: a numeric uid, or a name resolved against the guest’s /etc/passwd. Optional; omitted means the image’s AGENTD_DEFAULT_USER, resolved to the passwd row its name or uid matches, with that row’s primary gid, or the daemon’s own user when the image sets none. A name the guest does not have, or a default with no row, answers 400 unknown_user before anything is spawned.

A user with a passwd row, however it was given, gets HOME, USER and LOGNAME from the row, beneath the launch environment and env. A user given by name also gets the row’s primary gid when group is omitted; a numeric uid keeps the daemon’s group, as it always did.

group: Option<NameOrId>

The group to demote to: a numeric gid, or a name resolved against /etc/group. A name the guest does not have answers 400 unknown_group.

timeout_sec: Option<f64>

Wall-clock budget. Validated before the child spawns — the predecessor raised on a bad value inside the waiter thread, by which point the child was already running and became an orphan.

stdin: bool

Whether to give the child a writable stdin pipe. Defaults to false, which keeps Stdio::null().

Opt-in rather than always-on, and not only for tidiness: a child holding an open stdin pipe nobody will ever write to is a child that blocks forever the first time it reads. /bin/sh reading a script from stdin, git deciding it can prompt, any tool that probes for input — all of them behave differently against a pipe than against /dev/null. Every existing caller gets today’s behavior by not setting this.

reap_group_on_exit: bool

Whether to signal the exec’s whole process group once its own child exits.

Off by default, and the default is the contract this daemon has always had: a backgrounded grandchild that inherited the output pipe keeps running and keeps writing, and the linger deadline is what bounds how long the daemon waits on it. That is the “backgrounded server keeps logging” guarantee, and callers rely on it. Set to true, the daemon runs the same SIGTERM-then- SIGKILL escalation POST /v1/exec/{id}/kill uses against the group as soon as the child’s exit is observed, so nothing the command left behind outlives it and the linger sees EOF rather than writers_may_be_alive. A timed-out exec is already escalated and is not escalated twice.

poweroff_on_exit: bool

Power off the guest after this exec’s original process group has no live members. Off by default. Requires advertised daemon support and its CAP_SYS_BOOT privilege. Other work in the VM ends too; the start acknowledgment and exit record may be lost. Processes that leave the group are outside this condition. This does not keep an idle guest awake, and a terminated state does not establish when billing stops.

inherit_image_env: bool

Whether the child’s environment starts from the image’s ENV.

Off by default, which keeps the property the daemon has always had: nothing from its own environment reaches a child. Set, the environment the daemon inherited as the container CMD, minus every AGENTD_* variable, is the lowest layer, under the passwd identity, the launch environment and env. The agent token is never in that snapshot: it arrives in the run hook, after the snapshot is taken.

A daemon that predates this field ignores it, as serde ignores any unknown key; a caller that depends on it can read image_env_keys on GET /v1/health, which such a daemon does not report.

Implementations

impl StartRequest

pub fn new(exec_id: impl Into<String>, command: Vec<String>) -> Self

A request to run command as an argv under the idempotency key exec_id, with every other field at the default a body that omits it gets.

exec_id has no default here: minting one needs a clock and a random source, which this crate doesn’t have, and a shared fixed key would answer a second exec from the first one’s record.

This and the with_* setters are the only way to build a request outside this crate, because StartRequest is #[non_exhaustive]. The builder is where every optional field gets its one default, the same one serde gives a body that omits it, so a client can’t pick its own timeout_sec, reap_group_on_exit or inherit_image_env by writing the struct out, and a field added here reaches every caller as its default instead of as a build error in each client. (The struct’s own doc comment is the published schema’s description, so this lives here.)

let request: StartRequest = StartRequest::new("e1", vec!["true".into()]);

The same request as a struct expression doesn’t build outside this crate (E0639):

let request: StartRequest = StartRequest { ..StartRequest::new("e1", vec!["true".into()]) };

pub fn with_shell(self, shell: impl Into<Shell>) -> Self

Run command as a script under this shell, or as an argv for false.

pub fn with_cwd(self, cwd: Option<String>) -> Self

The child’s working directory; None inherits the daemon’s.

pub fn with_env(self, env: HashMap<String, String>) -> Self

The top layer of the child’s environment.

pub fn with_user(self, user: Option<NameOrId>) -> Self

The user to demote to; None runs as the image’s AGENTD_DEFAULT_USER, or as the daemon’s own user when the image sets none.

pub fn with_group(self, group: Option<NameOrId>) -> Self

The group to demote to; None follows StartRequest::user’s rule.

pub fn with_timeout_sec(self, timeout_sec: Option<f64>) -> Self

The daemon’s wall-clock budget for the child; None sets none.

pub fn with_stdin(self, stdin: bool) -> Self

Give the child a writable stdin pipe.

pub fn with_reap_group_on_exit(self, reap: bool) -> Self

Signal the exec’s process group once its own child exits.

pub fn with_poweroff_on_exit(self, poweroff: bool) -> Self

Power off the guest when this exec’s original process group has exited.

pub fn with_inherit_image_env(self, inherit: bool) -> Self

Start the child’s environment from the image’s ENV.

Trait Implementations

impl Debug for StartRequest

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StartRequest

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for StartRequest

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl Serialize for StartRequest

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.