run

Source: crates/lvcs-action/src/run.rs.

/// The executor starts a run of `action`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Start {
    /// The action.
    pub action: Action,
    /// What the shell supplies its expressions.
    pub runtime: Box<Runtime>,
}

/// What a run's expressions read that the shell supplies (decision 245,
/// stage C): `github.sha`, the revision's frontier id; `runner.arch`;
/// and each `hashFiles` call's digest, by its globs, over the files of
/// `/work`.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Runtime {
    /// `github.sha`.
    pub sha: String,
    /// `runner.arch`: `X64` or `ARM64`.
    pub arch: String,
    /// Each `hashFiles` call's digest, by its globs.
    pub hash_files: BTreeMap<Vec<String>, String>,
}

/// Launch `launch` ended.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Ended {
    /// The launch, as `Launch` named it.
    pub launch: u64,
    /// Its exit status: 128 plus the signal for one a signal ended, 125
    /// for a spec the sandbox refused.
    pub exit: i32,
    /// Whether the sandbox killed it at its timeout.
    pub timed_out: bool,
    /// Whether the run was cancelled from outside while it ran: the shell
    /// dropped the run's kill switch, and the sandbox killed the step, or
    /// spawned nothing, at its standard input's hang-up (decision 249,
    /// revised). A cancelled run launches nothing more.
    pub cancelled: bool,
    /// How long it ran, in milliseconds, by the shell's clock.
    pub elapsed_ms: u64,
    /// What its step files held.
    pub files: FilesRead,
}

/// Which phase a launch is in.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Phase {
    /// A node step's `pre`.
    Pre,
    /// A step's main run.
    Main,
    /// A node step's `post`.
    Post,
}

/// What a launch runs, the shell building its argument list.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Program {
    /// An argument list, with no shell.
    Exec {
        /// The argument list.
        argv: Vec<String>,
    },
    /// A script with every hole rendered (a script holds no secret),
    /// which the shell writes to a file and runs with `shell`.
    Script {
        /// Its shell.
        shell: Shell,
        /// Its text.
        text: String,
    },
    /// `node <file>`.
    Node {
        /// The program's path in the sandbox.
        file: String,
    },
}

/// Run one step through `lvcs sandbox` (decision 245).
///
/// `env` is set after the sandbox's fixed variables, each value rendered
/// but for its secret holes, which the shell fills; `path` goes before the
/// sandbox's fixed `PATH`; `cwd` is relative to `/work`; and `timeout_s` is
/// the step's wall clock. The shell makes the step files empty before the
/// launch and reads them after it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Launch {
    /// This launch, which `Ended` names.
    pub launch: u64,
    /// The step's place in the action, from 0.
    pub step: usize,
    /// The phase.
    pub phase: Phase,
    /// What kind of step it is, for the `action.step` span.
    pub kind: StepKindValue,
    /// What it runs.
    pub program: Program,
    /// Its environment.
    pub env: Vec<(String, Template)>,
    /// Its `PATH` entries before the fixed ones.
    pub path: Vec<String>,
    /// Its working directory, relative to `/work`.
    pub cwd: Option<String>,
    /// Its wall clock, in seconds.
    pub timeout_s: u64,
}

/// How the run ended.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Done {
    /// Whether it passed: no step failed the run, and it wasn't cancelled.
    pub passed: bool,
    /// Whether it ran out of time: the step that failed it was killed at
    /// its timeout, or the run was cancelled with steps left.
    pub timed_out: bool,
    /// The step that failed it, from 0, and its phase.
    pub failed: Option<(usize, Phase)>,
}

/// What the run machine asks of the executor.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RunOutput {
    /// Run one step.
    Launch(Launch),
    /// The run ended.
    Done(Done),
}