Skip to main content

runnerd_core/api/
storage.rs

1//! What the disk runnerd keeps means as every client shows it: what each cache volume holds and what its limit does,
2//! what the build cache did for a job and over a week, where GitHub Actions' cache is served, how full the records are and what became of a job's record,
3//! and how much of a job's log is stored. Plain derivations of the API's types; clients only lay them out.
4
5use super::{
6    BuildCacheCounts, BuildCacheStats, CacheKind, CacheVolume, LogSummary, RecordLimits,
7    RecordNote, RecordRemoval, Records, Tone, period,
8};
9use crate::config::ByteSize;
10
11/// The share of `[records] max_total` past which the records are near it, in percent: new ones then remove the
12/// oldest to fit.
13pub const RECORDS_NEAR_FULL: u64 = 80;
14
15/// Whether records taking `bytes` are near `max_total` (`RECORDS_NEAR_FULL`).
16pub fn records_near_full(bytes: u64, max_total: u64) -> bool {
17    u128::from(bytes) * 100 >= u128::from(max_total) * u128::from(RECORDS_NEAR_FULL)
18}
19
20impl CacheKind {
21    /// What it holds, as every client names it: `jvm snapshot`, `jvm slot 2 layer`, `pnpm store, shared`, `Maven
22    /// repository, shared`, `Docker Hub mirror` or `build cache, shared`.
23    pub fn description(&self) -> String {
24        match self {
25            CacheKind::Snapshot { profile } => format!("{profile} snapshot"),
26            CacheKind::Slot { profile, slot } => format!("{profile} slot {slot} layer"),
27            CacheKind::Pnpm => "pnpm store, shared".to_owned(),
28            CacheKind::Maven => "Maven repository, shared".to_owned(),
29            CacheKind::Mirror => "Docker Hub mirror".to_owned(),
30            CacheKind::Build => "build cache, shared".to_owned(),
31        }
32    }
33
34    /// The profile it belongs to; `None` for a shared one.
35    pub fn profile(&self) -> Option<&str> {
36        match self {
37            CacheKind::Snapshot { profile } | CacheKind::Slot { profile, .. } => Some(profile),
38            CacheKind::Pnpm | CacheKind::Maven | CacheKind::Mirror | CacheKind::Build => None,
39        }
40    }
41}
42
43/// A cache volume against its limit, from `CacheVolume::limit_status`.
44#[derive(Debug, Clone, PartialEq, Eq)]
45pub struct CacheLimit {
46    /// In bytes.
47    pub limit: u64,
48    /// Whether the volume is past it, so runnerd acts on it.
49    pub over: bool,
50    /// What runnerd does at it: `emptied above 5G`, `trimmed to 20G`, or for a snapshot `started over at its next
51    /// reseed above 30G`.
52    pub label: String,
53}
54
55impl CacheLimit {
56    /// What its size means: past the limit is worth a look.
57    pub fn tone(&self) -> Tone {
58        if self.over { Tone::Warn } else { Tone::Neutral }
59    }
60}
61
62impl CacheVolume {
63    /// Its size against its limit, when it has one.
64    pub fn limit_status(&self) -> Option<CacheLimit> {
65        let limit = self.limit?;
66        let size = ByteSize(limit);
67        let label = match self.kind {
68            CacheKind::Build => format!("trimmed to {size}"),
69            CacheKind::Snapshot { .. } => format!("started over at its next reseed above {size}"),
70            CacheKind::Slot { .. } | CacheKind::Pnpm | CacheKind::Maven | CacheKind::Mirror => {
71                format!("emptied above {size}")
72            }
73        };
74        Some(CacheLimit {
75            limit,
76            over: self.bytes > limit,
77            label,
78        })
79    }
80}
81
82/// What the build cache did for one job, from `BuildCacheCounts::activity`.
83#[derive(Debug, Clone, Copy, PartialEq, Eq)]
84pub struct BuildCacheActivity {
85    /// The counts.
86    pub counts: BuildCacheCounts,
87}
88
89impl BuildCacheCounts {
90    /// What it did, for a job that used it at all: looked an entry up, stored one, or was refused one. `None` for
91    /// a job that never used it.
92    pub fn activity(&self) -> Option<BuildCacheActivity> {
93        (self.lookups() > 0 || self.written_bytes > 0 || self.refused > 0)
94            .then_some(BuildCacheActivity { counts: *self })
95    }
96}
97
98impl BuildCacheActivity {
99    /// Its lookups: `3 of 4 lookups hit (75%)`, or `no lookups`.
100    pub fn lookups_line(&self) -> String {
101        let counts = &self.counts;
102        match counts.hit_percent() {
103            Some(percent) => format!(
104                "{} of {} lookups hit ({percent}%)",
105                counts.hits,
106                counts.lookups()
107            ),
108            None => "no lookups".to_owned(),
109        }
110    }
111
112    /// What it served: `1.5G served`.
113    pub fn served_line(&self) -> String {
114        format!("{} served", ByteSize(self.counts.read_bytes))
115    }
116
117    /// What it stored: `2G stored`, or `read only` for a job that may not write.
118    pub fn stored_line(&self) -> String {
119        if self.counts.writer {
120            format!("{} stored", ByteSize(self.counts.written_bytes))
121        } else {
122            "read only".to_owned()
123        }
124    }
125
126    /// The uploads it refused, when it refused any: `3 uploads refused`.
127    pub fn refused_line(&self) -> Option<String> {
128        (self.counts.refused > 0).then(|| format!("{} uploads refused", self.counts.refused))
129    }
130
131    /// A line for a client with little room: the hit rate and what it served, or what a job that only wrote stored,
132    /// and always the uploads it refused: `75% hit, 1.5G served, 3 uploads refused`, `read only`.
133    pub fn short_line(&self) -> String {
134        let mut parts = match self.counts.hit_percent() {
135            Some(percent) => vec![format!("{percent}% hit"), self.served_line()],
136            None => vec![self.stored_line()],
137        };
138        parts.extend(self.refused_line());
139        parts.join(", ")
140    }
141
142    /// All of it in a line: `3 of 4 lookups hit (75%), 1.5G served, 2G stored, 3 uploads refused`.
143    pub fn line(&self) -> String {
144        let mut parts = vec![self.lookups_line(), self.served_line(), self.stored_line()];
145        parts.extend(self.refused_line());
146        parts.join(", ")
147    }
148}
149
150/// The tools whose caches the build cache serves, as clients name them over its counts (ADR 0052, 0083). The image
151/// points each at it but Nx, which fails its run when the cache does not answer.
152pub const BUILD_CACHE_TOOLS: &str =
153    "Gradle, sccache, Bazel and Turborepo, and Nx where a workflow opts in";
154
155/// What doctor and the Caches page name GitHub Actions' cache.
156pub const ACTIONS_CACHE: &str = "GitHub Actions' cache";
157
158/// Where jobs' GitHub Actions cache is (ADR 0082), with `[caches.build] actions_cache` at `served`.
159pub fn actions_cache_place(served: bool) -> &'static str {
160    if served {
161        "served from the build cache on this host, in place of GitHub's"
162    } else {
163        "GitHub's, as [caches.build] actions_cache = false sets"
164    }
165}
166
167impl BuildCacheStats {
168    /// Where jobs' GitHub Actions cache is, and while it is here, where its hits are counted and how to turn it off:
169    /// `GitHub Actions' cache: served from the build cache on this host, in place of GitHub's, and counted with it;
170    /// [caches.build] actions_cache = false turns it off`.
171    pub fn actions_cache_line(&self) -> String {
172        let place = actions_cache_place(self.actions_cache);
173        if self.actions_cache {
174            format!(
175                "{ACTIONS_CACHE}: {place}, and counted with it; [caches.build] actions_cache = false turns it \
176                 off"
177            )
178        } else {
179            format!("{ACTIONS_CACHE}: {place}")
180        }
181    }
182
183    /// Its entries and the last 7 days' jobs: `120 entries; 75% of 400 lookups hit in 7 days, 3G served, 1G
184    /// stored, 2 uploads refused`, `120 entries; no lookups in 7 days, 1G stored`, or `120 entries; no lookups in 7
185    /// days`.
186    pub fn week_line(&self) -> String {
187        let week = &self.week;
188        let mut parts = match week.hit_percent() {
189            Some(percent) => vec![
190                format!("{percent}% of {} lookups hit in 7 days", week.lookups()),
191                format!("{} served", ByteSize(week.read_bytes)),
192            ],
193            None => vec!["no lookups in 7 days".to_owned()],
194        };
195        if week.activity().is_some() {
196            parts.push(format!("{} stored", ByteSize(week.written_bytes)));
197        }
198        if week.refused > 0 {
199            parts.push(format!("{} uploads refused", week.refused));
200        }
201        format!("{} entries; {}", self.entries, parts.join(", "))
202    }
203}
204
205impl RecordLimits {
206    /// Whether records taking `bytes` are near `max_total` (`records_near_full`).
207    pub fn near_full(&self, bytes: u64) -> bool {
208        records_near_full(bytes, self.max_total)
209    }
210}
211
212impl Records {
213    /// How many there are and how much they take of their limits, and when near `max_total`, `Records::pressure`:
214    /// `3 of 20 records, 1.2G of 10G, each kept 7 days; near max_total, so new ones remove the oldest`.
215    pub fn summary(&self) -> String {
216        match self.pressure() {
217            Some(pressure) => format!("{}; {pressure}", self.usage()),
218            None => self.usage(),
219        }
220    }
221
222    /// How many there are and how much they take of their limits: `3 of 20 records, 1.2G of 10G, each kept 7 days`.
223    pub fn usage(&self) -> String {
224        let limits = &self.limits;
225        // `[records] max_age` is in days more often than not.
226        let age = match limits.max_age / 86_400 {
227            1 if limits.max_age == 86_400 => "1 day".to_owned(),
228            days if days > 1 && limits.max_age.is_multiple_of(86_400) => format!("{days} days"),
229            _ => period(limits.max_age),
230        };
231        format!(
232            "{} of {} records, {} of {}, each kept {age}",
233            self.records.len(),
234            limits.max_count,
235            ByteSize(self.bytes()),
236            ByteSize(limits.max_total),
237        )
238    }
239
240    /// What being near `max_total` means, when they are: `near max_total, so new ones remove the oldest`.
241    pub fn pressure(&self) -> Option<&'static str> {
242        self.limits
243            .near_full(self.bytes())
244            .then_some("near max_total, so new ones remove the oldest")
245    }
246
247    /// What the summary means: near `max_total` is worth a look.
248    pub fn summary_tone(&self) -> Tone {
249        if self.limits.near_full(self.bytes()) {
250            Tone::Warn
251        } else {
252            Tone::Neutral
253        }
254    }
255
256    /// Why there are none: `none kept: a profile with record_failures = true keeps each failed job's runner as a
257    /// record, to open a shell where it failed`.
258    pub fn empty_reason() -> &'static str {
259        "none kept: a profile with record_failures = true keeps each failed job's runner as a record, to open a \
260         shell where it failed"
261    }
262
263    /// Whether a shell is open in `job`'s record.
264    pub fn shell_open(&self, job: u64) -> bool {
265        self.shells.contains(&job)
266    }
267}
268
269/// What became of a failed job's record, from `RecordNote::state`.
270#[derive(Debug, Clone, Copy, PartialEq, Eq)]
271pub enum RecordState<'note> {
272    /// None was made.
273    Skipped {
274        /// Why, such as too little free disk.
275        why: &'note str,
276    },
277    /// It was made, then removed.
278    Removed {
279        /// When.
280        at: u64,
281        /// Why, when known.
282        by: Option<RecordRemoval>,
283    },
284    /// It is kept: a shell can open in it.
285    Kept {
286        /// Its size when made, when known.
287        bytes: Option<u64>,
288    },
289}
290
291impl RecordNote {
292    /// What became of the record: not made, made and removed, or kept, in that order of precedence.
293    pub fn state(&self) -> RecordState<'_> {
294        match (&self.skipped, self.removed_at) {
295            (Some(why), _) => RecordState::Skipped { why },
296            (None, Some(at)) => RecordState::Removed {
297                at,
298                by: self.removed_by,
299            },
300            (None, None) => RecordState::Kept { bytes: self.bytes },
301        }
302    }
303
304    /// The command that opens a shell in `job`'s record: `runnerctl shell 42`.
305    pub fn shell_command(job: u64) -> String {
306        format!("runnerctl shell {job}")
307    }
308}
309
310impl RecordState<'_> {
311    /// Its words, before when it was removed for a removed one: `not kept: too little free disk`, `removed past
312    /// max_age`, or `record kept, 2G`.
313    pub fn line(&self) -> String {
314        match self {
315            RecordState::Skipped { why } => format!("not kept: {why}"),
316            RecordState::Removed { by, .. } => {
317                by.map_or_else(|| "removed".to_owned(), |by| by.to_string())
318            }
319            RecordState::Kept { bytes: Some(bytes) } => {
320                format!("record kept, {}", ByteSize(*bytes))
321            }
322            RecordState::Kept { bytes: None } => "record kept".to_owned(),
323        }
324    }
325}
326
327impl LogSummary {
328    /// How much of the log is stored: `120 lines, 4M`, and `, cut at history.log_max` once later lines were
329    /// dropped.
330    pub fn description(&self) -> String {
331        let line = format!("{} lines, {}", self.lines, ByteSize(self.bytes));
332        if self.truncated {
333            format!("{line}, cut at history.log_max")
334        } else {
335            line
336        }
337    }
338}
339
340#[cfg(test)]
341mod tests;