api-runs

Source: crates/lvcs-api/src/runs.rs.

/// `run.list` (decision 303): the runs this daemon heard of, its own
/// runner's included, newest first: at most `RUN_HISTORY_MAX` per channel,
/// kept for the daemon's run. Optionally only one channel's (a channel
/// name) or one frontier's (`ID_ENCODING`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunListParams {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub channel: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub frontier: Option<String>,
}

/// `run.list` result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunListResult {
    #[serde(default)]
    pub runs: Vec<RunRecord>,
}

/// One runner's run of one action on one frontier, at its latest state.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunRecord {
    /// The run's id, in `ID_ENCODING`: the `HASH` of its channel's name,
    /// a zero byte, its frontier's id bytes, and its runner's key bytes,
    /// the same on every daemon that heard of it. `lvcs run view` takes
    /// it or its unique start (decision 332).
    #[serde(default)]
    pub id: String,
    /// The channel the action moves (decision 297).
    pub channel: String,
    /// The action's name: its channel's, or a GitHub job's matrix cell.
    pub action: String,
    /// The frontier it runs on, in `ID_ENCODING`.
    pub frontier: String,
    /// The runner's participant id, in `ID_ENCODING`.
    pub runner: String,
    /// The runner's name as hints name it (`Named`): its alias when one
    /// is bound, else a short id.
    pub runner_name: String,
    /// A `run_state` value.
    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]
    pub state: RunState,
    /// When the runner took the run, in Unix milliseconds by its clock.
    pub started_ms: i64,
    /// When it ended, for an ended state.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_ms: Option<i64>,
    /// Its steps as they started and ended, in order (decision 312): only
    /// on the daemon that ran it, empty elsewhere, since runners gossip no
    /// step.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub steps: Vec<RunStepRecord>,
}

/// One step of a run (decision 312).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunStepRecord {
    /// Its place in the action, from 1.
    pub step: usize,
    /// Its id, else `step <n>`.
    pub name: String,
    /// A `run_state` value: `running`, `passed`, or `failed`.
    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]
    pub state: RunState,
    /// Its exit status, once it ended.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exit: Option<i32>,
    /// When it started, in Unix milliseconds by the runner's daemon's
    /// clock.
    pub started_ms: i64,
    /// When it ended.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ended_ms: Option<i64>,
    /// The last `STEP_LOG_TAIL_LINES` lines of its masked output, once it
    /// ended.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub log_tail: Vec<String>,
}

/// Server push, JSON-RPC notification method `run` (`watch`): a run's
/// state changed, or, on the daemon that runs it, one of its steps started
/// or ended (decision 312).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunPush {
    /// The `watch` it is pushed for.
    pub sub: u64,
    pub run: RunRecord,
}

/// `run.view` (decision 312): every runner's run of `channel`
/// on `frontier` this daemon heard of, the action's steps under the
/// approved `lvcs.toml`, and, where this daemon ran it, the last
/// `RUN_LOG_TAIL_LINES` lines of its masked `log` (pull, not push: the
/// viewer asked for it). A run on another daemon names its runner, whose
/// own daemon serves its log.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunViewParams {
    pub channel: String,
    /// A frontier id (`ID_ENCODING`).
    pub frontier: String,
}

/// `run.view` result.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunViewResult {
    pub channel: String,
    pub frontier: String,
    /// The channel's gated action's steps, or its change actions' names,
    /// in order: each step's id, else `step <n>`.
    #[serde(default)]
    pub steps: Vec<String>,
    /// Each runner's run, newest first.
    #[serde(default)]
    pub runs: Vec<RunRecord>,
    /// The last lines of this daemon's own run's log, oldest first; empty
    /// when it ran none here.
    #[serde(default)]
    pub log_tail: Vec<String>,
    /// Whether this daemon ran one of them, so `log_tail` is its log's.
    #[serde(default)]
    pub here: bool,
}