docs/generated/contracts.mdgenerated from code
Reference · 6 min read
api-runs
Contracts: api-runs.
Read as
Source: crates/lvcs-api/src/runs.rs.
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}