Skip to main content

runnerd_core/api/
archives.rs

1//! What clients show of the action archives runnerd keeps for its runners (ADR 0147): how many it holds, their size,
2//! when it last refreshed them and what failed, each worded once here. Plain derivations of the API's types; the
3//! store itself is `archives`, behind the `host` feature.
4
5use serde::{Deserialize, Serialize};
6
7use super::{Tone, ago};
8use crate::config::ByteSize;
9
10/// The action archives runnerd keeps, as its store last published them; in [`super::Status`] and
11/// [`super::Caches`].
12#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
13pub struct ActionArchives {
14    /// How many verified archives it holds.
15    pub entries: u64,
16    /// Their bytes.
17    pub bytes: u64,
18    /// When a refresh of every repository's pins last ended, in seconds since the epoch; `None` before the first.
19    #[serde(default, skip_serializing_if = "Option::is_none")]
20    pub refreshed_at: Option<u64>,
21    /// What failed and has not succeeded since, oldest first.
22    #[serde(default, skip_serializing_if = "Vec::is_empty")]
23    pub failures: Vec<ArchiveFailure>,
24    /// Runners a restart adopted with the archives mounted, while no check of this daemon has found those good yet.
25    #[serde(default, skip_serializing_if = "is_zero")]
26    pub unchecked: u64,
27}
28
29#[expect(
30    clippy::trivially_copy_pass_by_ref,
31    reason = "serde's `skip_serializing_if` passes a reference"
32)]
33fn is_zero(count: &u64) -> bool {
34    *count == 0
35}
36
37/// Something the store could not do, which jobs make up for by downloading their actions themselves.
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
39pub struct ArchiveFailure {
40    /// What failed: a served repository (`owner/name`) for [`ArchiveFailureKind::Pins`] and
41    /// [`ArchiveFailureKind::Held`], a repository for [`ArchiveFailureKind::Package`], a runner for
42    /// [`ArchiveFailureKind::Exposed`], the store's directory for [`ArchiveFailureKind::Store`] and
43    /// [`ArchiveFailureKind::Full`], else an action (`owner/name@sha`, `owner/name/path@sha`).
44    pub subject: String,
45    /// What went wrong.
46    pub kind: ArchiveFailureKind,
47    /// When it first failed, in seconds since the epoch.
48    pub since: u64,
49}
50
51/// What went wrong with an action archive.
52#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
53#[serde(rename_all = "kebab-case")]
54pub enum ArchiveFailureKind {
55    /// A served repository's pins could not be read; its last ones are kept.
56    Pins,
57    /// An archive could not be downloaded.
58    Download,
59    /// A downloaded archive failed its check, so it was not kept.
60    Rejected,
61    /// A kept archive no longer matched what was verified; it was moved to quarantine and is downloaded again.
62    Quarantined,
63    /// The store could not be opened, checked whole, or written: runners get no archives while it cannot be
64    /// checked.
65    Store,
66    /// Not all a served repository's pins are known, so every archive it last reached is kept.
67    Held,
68    /// The store is at its size cap: what is missing waits for room.
69    Full,
70    /// The archive holds no action file at the path a pin names: not an action the runner loads.
71    NotAction,
72    /// The archive's action file there is not YAML runnerd reads, so what it pins is not followed.
73    Unreadable,
74    /// A job resolved the repository as an immutable action package, which the runner would replace with an archive
75    /// of the same commit: its archives are removed and never kept.
76    Package,
77    /// A runner a restart adopted with the archives mounted, before the first check moved a file it may have read.
78    Exposed,
79    /// A kind from a newer daemon.
80    #[serde(other)]
81    Unknown,
82}
83
84impl ArchiveFailure {
85    /// What failed, in a line: `actions/checkout@08eba0b: its archive failed its check and was not kept`.
86    pub fn line(&self) -> String {
87        let subject = short_subject(&self.subject);
88        let what = match self.kind {
89            ArchiveFailureKind::Pins => {
90                "its pinned actions could not be read; the last ones read are kept"
91            }
92            ArchiveFailureKind::Download => "its archive could not be downloaded",
93            ArchiveFailureKind::Rejected => "its archive failed its check and was not kept",
94            ArchiveFailureKind::Quarantined => {
95                "its kept archive changed on disk; it was moved to quarantine and is downloaded again"
96            }
97            ArchiveFailureKind::Store => {
98                "cannot be opened, checked or written, so runners may download their actions themselves"
99            }
100            ArchiveFailureKind::Held => {
101                "not all its pinned actions are known, so every archive it last reached is kept"
102            }
103            ArchiveFailureKind::Full => "is at its size cap; missing archives wait for room",
104            ArchiveFailureKind::NotAction => {
105                "its archive holds no action there, so it is not kept as one"
106            }
107            ArchiveFailureKind::Unreadable => {
108                "its action file is not YAML runnerd reads, so what it pins is not kept"
109            }
110            ArchiveFailureKind::Package => {
111                "a job resolved it as an immutable action package; its archives are removed and never kept"
112            }
113            ArchiveFailureKind::Exposed => {
114                "kept running across a restart with the archives mounted, and the first check then moved or could \
115                 not read one: its job may have read it"
116            }
117            ArchiveFailureKind::Unknown => "it failed",
118        };
119        format!("{subject}: {what}")
120    }
121}
122
123/// `owner/name@sha` with the commit cut to 7 digits, as git writes one short; anything else as it is.
124fn short_subject(subject: &str) -> String {
125    match subject.split_once('@') {
126        Some((name, sha)) if sha.len() > 7 => format!("{name}@{}", &sha[..7]),
127        _ => subject.to_owned(),
128    }
129}
130
131impl ActionArchives {
132    /// What the store holds: `8 action archives, 12M, refreshed 3m ago`, or `no action archives yet`.
133    pub fn line(&self, now: u64) -> String {
134        let held = match self.entries {
135            0 => "no action archives yet".to_owned(),
136            1 => format!("1 action archive, {}", ByteSize(self.bytes)),
137            entries => format!("{entries} action archives, {}", ByteSize(self.bytes)),
138        };
139        let line = match self.refreshed_at {
140            Some(at) => format!("{held}, refreshed {}", ago(at, now)),
141            None => held,
142        };
143        match self.unchecked {
144            0 => line,
145            1 => format!("{line}; 1 adopted runner reads them before a check"),
146            unchecked => format!("{line}; {unchecked} adopted runners read them before a check"),
147        }
148    }
149
150    /// What its failures mean together, in the attention list's words: `runnerd's action archives are not all kept,
151    /// so jobs download those from GitHub: actions/checkout@08eba0b: … and 1 more`, or, when a runner may have read an
152    /// archive a check then moved, `a runner may have read an action archive that changed: runnerd-…: …`. `None`
153    /// while nothing failed.
154    pub fn attention_title(&self) -> Option<String> {
155        let exposed = self
156            .failures
157            .iter()
158            .find(|failure| failure.kind == ArchiveFailureKind::Exposed);
159        let first = exposed.or_else(|| self.failures.first())?;
160        let more = match self.failures.len() {
161            1 => String::new(),
162            n => format!(" and {} more", n - 1),
163        };
164        Some(if exposed.is_some() {
165            format!(
166                "a runner may have read an action archive that changed: {}{more}",
167                first.line()
168            )
169        } else {
170            format!(
171                "runnerd's action archives are not all kept, so jobs download those from GitHub: {}{more}",
172                first.line()
173            )
174        })
175    }
176
177    /// The tone its failures take: a warning, as jobs still download what is missing.
178    pub fn tone(&self) -> Tone {
179        if self.failures.is_empty() {
180            Tone::Neutral
181        } else {
182            Tone::Warn
183        }
184    }
185
186    /// When its oldest failure began; `None` while nothing failed.
187    pub fn failing_since(&self) -> Option<u64> {
188        self.failures.iter().map(|failure| failure.since).min()
189    }
190}