docs/generated/contracts.mdgenerated from code

Reference · 6 min read

api-runs

Contracts: api-runs.

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

ruston main
1/// `run.list` (discussion:owner/303): the runs this daemon heard of, its own2/// runner's included, newest first: at most `RUN_HISTORY_MAX` per channel,3/// kept for the daemon's run. Optionally only one channel's (a channel4/// name) or one frontier's (`ID_ENCODING`).5#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]6pub struct RunListParams {7    #[serde(default, skip_serializing_if = "Option::is_none")]8    pub channel: Option<String>,9    #[serde(default, skip_serializing_if = "Option::is_none")]10    pub frontier: Option<String>,11}1213/// `run.list` result.14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]15pub struct RunListResult {16    #[serde(default)]17    pub runs: Vec<RunRecord>,18    /// Each gated action waiting for an approval before it can run19    /// (discussion:owner/372), of the named channel or frontier when one is named.20    #[serde(default, skip_serializing_if = "Vec::is_empty")]21    pub waiting: Vec<RunWaiting>,22    /// When this daemon started: a run's record lasts the daemon's run, so23    /// `runs` holds what it heard since (discussion:owner/477).24    #[serde(default)]25    pub since_ms: i64,26    /// What the named channel holds now, as its signed attestations and27    /// outcomes say: they outlast the records of the runs behind them.28    #[serde(default, skip_serializing_if = "Vec::is_empty")]29    pub holds: Vec<RunHolds>,30}3132/// One frontier a channel holds, with who passed it.33#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]34pub struct RunHolds {35    pub channel: String,36    pub frontier: String,37    /// The name of each runner whose attestation or passed outcome of the38    /// frontier the channel holds, sorted.39    #[serde(default)]40    pub runners: Vec<String>,41}4243/// A channel-triggered gated action due to run on `frontier` that no44/// runner takes, since the frontier holds protected paths past their45/// approved heads (discussion:owner/372): no run exists until an approval names46/// them, so the wait is the action's, not a run's.47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]48pub struct RunWaiting {49    /// The gated action's channel, which is its name.50    pub channel: String,51    /// The frontier it is due to run on, in `ID_ENCODING`.52    pub frontier: String,53    /// What it waits on: an [`WaitReason::Approval`].54    pub wait: RunWait,55}5657/// What a run, or a gated action no run exists for yet, waits on (rows58/// 368 and 372): why, typed, and what to do about it.59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]60pub struct RunWait {61    pub reason: WaitReason,62    /// The reason in words, its `recover`, and its next step: `wait` for63    /// this runner's reads or executor, or `protected_path`64    /// (`fix_request`) with the `approve` of the paths as next.65    pub error: crate::error::ErrorData,66}6768/// Why a run or an action waits (rows 368 and 372).69#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]70#[serde(tag = "kind", rename_all = "snake_case")]71pub enum WaitReason {72    /// Documents the run reads haven't been read here yet: `unread` of73    /// `documents` (absent for a change job, which counts only those left).74    Reads {75        unread: u32,76        #[serde(default, skip_serializing_if = "Option::is_none")]77        documents: Option<u32>,78    },79    /// Another job or run holds this runner's executor.80    Executor,81    /// The frontier holds protected paths past their approved heads, so82    /// no runner takes it until an `approve` names exactly `paths`83    /// (sorted).84    Approval { paths: Vec<String> },85}8687/// One runner's run of one action on one frontier, at its latest state.88#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]89pub struct RunRecord {90    /// The run's id, in `ID_ENCODING`: the `HASH` of its channel's name,91    /// a zero byte, its frontier's id bytes, its runner's key bytes, and92    /// its `started_ms` as a big-endian `i64`, so each attempt has its own93    /// (row 352), the same on every daemon that heard of it. `lvcs run94    /// view` takes it or its unique start (discussion:owner/332).95    #[serde(default)]96    pub id: String,97    /// Which attempt this is of its runner's runs of its channel on its98    /// frontier, from 1, by start time among those this daemon holds99    /// (row 352).100    #[serde(default)]101    pub attempt: u32,102    /// The channel the action moves (discussion:owner/297).103    pub channel: String,104    /// The action's name: its channel's, or a GitHub job's matrix cell.105    pub action: String,106    /// The frontier it runs on, in `ID_ENCODING`.107    pub frontier: String,108    /// The runner's peer id, in `ID_ENCODING`.109    pub runner: String,110    /// The runner's name as hints name it (`Named`): its alias when one111    /// is bound, else a short id.112    pub runner_name: String,113    /// A `run_state` value.114    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]115    pub state: RunState,116    /// When the runner took the run, in Unix milliseconds by its clock.117    pub started_ms: i64,118    /// When it ended, for an ended state.119    #[serde(default, skip_serializing_if = "Option::is_none")]120    pub ended_ms: Option<i64>,121    /// What the run waits on while it is `waiting`, with the next step, as122    /// the daemon that runs it knows it (row 368): only on that daemon,123    /// absent elsewhere and once it runs. Boxed, so a record stays small124    /// beside the pushes it rides with.125    #[serde(default, skip_serializing_if = "Option::is_none")]126    pub waiting: Option<Box<RunWait>>,127    /// Its steps as they started and ended, in order (discussion:owner/312): only128    /// on the daemon that ran it, empty elsewhere, since runners gossip no129    /// step.130    #[serde(default, skip_serializing_if = "Vec::is_empty")]131    pub steps: Vec<RunStepRecord>,132}133134/// One step of a run (discussion:owner/312).135#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]136pub struct RunStepRecord {137    /// Its place in the action, from 1.138    pub step: usize,139    /// Its id, else `step <n>`.140    pub name: String,141    /// A `run_state` value: `running`, `passed`, or `failed`.142    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]143    pub state: RunState,144    /// Its exit status, once it ended.145    #[serde(default, skip_serializing_if = "Option::is_none")]146    pub exit: Option<i32>,147    /// When it started, in Unix milliseconds by the runner's daemon's148    /// clock.149    pub started_ms: i64,150    /// When it ended.151    #[serde(default, skip_serializing_if = "Option::is_none")]152    pub ended_ms: Option<i64>,153    /// The last `STEP_LOG_TAIL_LINES` lines of its masked output, once it154    /// ended.155    #[serde(default, skip_serializing_if = "Vec::is_empty")]156    pub log_tail: Vec<String>,157}158159/// Server push, JSON-RPC notification method `run` (`watch`): a run's160/// state changed, or, on the daemon that runs it, one of its steps started161/// or ended (discussion:owner/312).162#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]163pub struct RunPush {164    /// The `watch` it is pushed for.165    pub sub: u64,166    pub run: RunRecord,167}168169/// `run.view` (discussion:owner/312): every runner's run of `channel`170/// on `frontier` this daemon heard of, the action's steps under the171/// approved `lvcs.toml`, and, where this daemon ran it, the last172/// `RUN_LOG_TAIL_LINES` lines of its masked `log` (pull, not push: the173/// viewer asked for it). A run on another daemon names its runner, whose174/// own daemon serves its log.175#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]176pub struct RunViewParams {177    pub channel: String,178    /// A frontier id (`ID_ENCODING`).179    pub frontier: String,180}181182/// `run.view` result.183#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]184pub struct RunViewResult {185    pub channel: String,186    pub frontier: String,187    /// The channel's gated action's steps, or its change actions' names,188    /// in order: each step's id, else `step <n>`.189    #[serde(default)]190    pub steps: Vec<String>,191    /// Each runner's run, newest first.192    #[serde(default)]193    pub runs: Vec<RunRecord>,194    /// The last lines of this daemon's own run's log, oldest first; empty195    /// when it ran none here.196    #[serde(default)]197    pub log_tail: Vec<String>,198    /// Whether this daemon ran one of them, so `log_tail` is its log's.199    #[serde(default)]200    pub here: bool,201    /// The channel's action waiting for an approval (discussion:owner/372), at202    /// whatever frontier it is due to run on.203    #[serde(default, skip_serializing_if = "Option::is_none")]204    pub waiting: Option<RunWaiting>,205    /// The node (`ID_ENCODING`) whose daemon ran it, when this daemon206    /// read `log_tail` and the runs' steps from there (discussion:owner/422).207    #[serde(default, skip_serializing_if = "Option::is_none")]208    pub log_node: Option<String>,209    /// Why another runner's log couldn't be read (discussion:owner/422).210    #[serde(default, skip_serializing_if = "Option::is_none")]211    pub log_unavailable: Option<crate::error::ErrorData>,212    /// The action's log document (`LOG_PREFIX` + the channel) this daemon213    /// read `log_tail` and `log_errors` from, when the runner's node214    /// couldn't be reached and the document holds this run's failure215    /// (discussion:owner/500).216    #[serde(default, skip_serializing_if = "Option::is_none")]217    pub log_document: Option<String>,218    /// The failed run's kept error lines, from its log document (219    /// discussion:owner/500); empty otherwise.220    #[serde(default, skip_serializing_if = "Vec::is_empty")]221    pub log_errors: Vec<String>,222    /// Whether the run's log was withheld: the caller's read grants don't223    /// cover every path the action's `paths` and `uses` match, so224    /// `log_tail`, `log_errors`, `log_document`, and each step's225    /// `log_tail` are empty (discussion:owner/502).226    #[serde(default, skip_serializing_if = "std::ops::Not::not")]227    pub log_withheld: bool,228}