Skip to main content

runnerd_core/api/
slots.rs

1//! What a slot is doing and whether CI keeps up, as every client names and counts it. Plain derivations of
2//! [`Status`] and [`Activity`]: a client never infers a slot's state from whether it found the job's details.
3
4use super::{Activity, ProfileStatus, RunnerStatus, SlotStatus, Status, Tone, duration};
5
6/// What a slot is doing, from `Status::slot_state`.
7#[derive(Debug, Clone, PartialEq, Eq)]
8pub enum SlotState {
9    /// No runner, and nothing to do.
10    Idle,
11    /// No runner: slot 1's layers become the profile's snapshot.
12    Reseeding,
13    /// A runner started for a queued job and waits for GitHub to hand it one.
14    Starting {
15        /// `owner/name` the runner is registered on.
16        repository: String,
17    },
18    /// A warm runner: no queued job waits for it; it takes the next one GitHub hands out.
19    Warm {
20        /// `owner/name` the runner is registered on.
21        repository: String,
22    },
23    /// Its runner runs a job.
24    Running {
25        /// `owner/name` the runner is registered on.
26        repository: String,
27    },
28}
29
30impl SlotState {
31    /// What a slot holding `runner` is doing: running its job, warm for its repository, or starting.
32    pub fn of_runner(runner: &RunnerStatus) -> SlotState {
33        let repository = runner.repository.clone();
34        if runner.busy {
35            SlotState::Running { repository }
36        } else if runner.warm {
37            SlotState::Warm { repository }
38        } else {
39            SlotState::Starting { repository }
40        }
41    }
42
43    /// One word for it, as a table column says it: `idle`, `reseeding`, `starting`, `warm` or `running`.
44    pub fn word(&self) -> &'static str {
45        match self {
46            SlotState::Idle => "idle",
47            SlotState::Reseeding => "reseeding",
48            SlotState::Starting { .. } => "starting",
49            SlotState::Warm { .. } => "warm",
50            SlotState::Running { .. } => "running",
51        }
52    }
53
54    /// What it does, as a sentence's tail: `idle`, `reseeding the snapshot`, `a runner for o/app waiting for its
55    /// job`, `a warm runner for o/app, waiting for a job` or `running a job of o/app`.
56    pub fn line(&self) -> String {
57        match self {
58            SlotState::Idle => "idle".to_owned(),
59            SlotState::Reseeding => "reseeding the snapshot".to_owned(),
60            SlotState::Starting { repository } => {
61                format!("a runner for {repository} waiting for its job")
62            }
63            SlotState::Warm { repository } => {
64                format!("a warm runner for {repository}, waiting for a job")
65            }
66            SlotState::Running { repository } => format!("running a job of {repository}"),
67        }
68    }
69
70    /// Whether a runner runs a job in it.
71    pub fn is_running(&self) -> bool {
72        matches!(self, SlotState::Running { .. })
73    }
74
75    /// What it means at a glance: a running slot is a plain fact, every other one background.
76    pub fn tone(&self) -> Tone {
77        match self {
78            SlotState::Running { .. } => Tone::Neutral,
79            _ => Tone::Quiet,
80        }
81    }
82}
83
84impl Status {
85    /// What `slot` of `profile` is doing: its runner's state as the daemon reports it, or for a free slot, whether its
86    /// profile reseeds into it.
87    pub fn slot_state(profile: &ProfileStatus, slot: &SlotStatus) -> SlotState {
88        match &slot.runner {
89            Some(runner) => SlotState::of_runner(runner),
90            None if profile.reseeding && slot.slot == 1 => SlotState::Reseeding,
91            None => SlotState::Idle,
92        }
93    }
94
95    /// Whether CI keeps up now: slots running, starting and warm, and the queue with its oldest job's wait at `now`.
96    pub fn health(&self, now: u64) -> Health {
97        let mut health = Health {
98            slots: 0,
99            running: 0,
100            starting: 0,
101            warm: 0,
102            waiting: self.queued.len(),
103            oldest_wait: self
104                .queued
105                .iter()
106                .filter(|job| job.queued_at > 0)
107                .map(|job| now.saturating_sub(job.queued_at))
108                .max(),
109        };
110        for profile in &self.profiles {
111            for slot in &profile.slots {
112                health.slots += 1;
113                match Status::slot_state(profile, slot) {
114                    SlotState::Running { .. } => health.running += 1,
115                    SlotState::Starting { .. } => health.starting += 1,
116                    SlotState::Warm { .. } => health.warm += 1,
117                    SlotState::Idle | SlotState::Reseeding => {}
118                }
119            }
120        }
121        health
122    }
123}
124
125/// Whether CI keeps up now, from `Status::health`.
126#[derive(Debug, Clone, Copy, PartialEq, Eq)]
127pub struct Health {
128    /// Every configured slot.
129    pub slots: usize,
130    /// Slots whose runner runs a job.
131    pub running: usize,
132    /// Slots whose runner waits for the queued job it started for.
133    pub starting: usize,
134    /// Slots whose warm runner waits for jobs not queued yet.
135    pub warm: usize,
136    /// Queued jobs no runner holds yet.
137    pub waiting: usize,
138    /// How long the oldest of them has waited, in seconds; `None` when none says when it was queued.
139    pub oldest_wait: Option<u64>,
140}
141
142impl Health {
143    /// What the queue means: any job waiting is worth a look.
144    pub fn waiting_tone(&self) -> Tone {
145        if self.waiting > 0 {
146            Tone::Warn
147        } else {
148            Tone::Neutral
149        }
150    }
151}
152
153/// One of the overview's four health figures, worded once for every client: the web dashboard lays them out as
154/// tiles, the TUI on one line.
155#[derive(Debug, Clone, PartialEq, Eq)]
156pub struct Figure {
157    /// Which of the four it is, for a client that links or places one: never its label's text.
158    pub kind: HealthKind,
159    /// What it counts: `Running`, `Waiting`, `Wait p95, 24 h` or `Failed, 24 h`.
160    pub label: &'static str,
161    /// The figure itself.
162    pub value: String,
163    /// What it is out of, such as `of 6 slots`.
164    pub of: Option<String>,
165    /// What qualifies it, most telling first.
166    pub notes: Vec<String>,
167    /// What it means.
168    pub tone: Tone,
169}
170
171/// Which health figure a [`Figure`] is.
172#[derive(Debug, Clone, Copy, PartialEq, Eq)]
173pub enum HealthKind {
174    /// Slots running a job.
175    Running,
176    /// Jobs waiting for a runner, which the queue lists.
177    Waiting,
178    /// The last day's p95 wait.
179    Wait,
180    /// The last day's failed jobs, which the history lists by outcome.
181    Failed,
182}
183
184impl Health {
185    /// The four figures that say whether CI keeps up: slots running, jobs waiting and the oldest's wait, and from
186    /// the last day's `activity`, the wait of the jobs that started and the failures. The last two are left out
187    /// until the day is read.
188    pub fn figures(&self, activity: Option<&Activity>) -> Vec<Figure> {
189        let mut running = Vec::new();
190        if self.starting > 0 {
191            let s = if self.starting == 1 { "" } else { "s" };
192            running.push(format!("{} runner{s} starting", self.starting));
193        }
194        if self.warm > 0 {
195            running.push(format!("{} warm, waiting for jobs", self.warm));
196        }
197        let waiting = match self.oldest_wait {
198            Some(oldest) => vec![format!("oldest {}", duration(oldest))],
199            None => Vec::new(),
200        };
201        let mut figures = vec![
202            Figure {
203                kind: HealthKind::Running,
204                label: "Running",
205                value: self.running.to_string(),
206                of: Some(format!("of {} slots", self.slots)),
207                notes: running,
208                tone: Tone::Neutral,
209            },
210            Figure {
211                kind: HealthKind::Waiting,
212                label: "Waiting",
213                value: self.waiting.to_string(),
214                of: None,
215                notes: waiting,
216                tone: self.waiting_tone(),
217            },
218        ];
219        if let Some(day) = activity {
220            let started = day.started.len();
221            figures.push(Figure {
222                kind: HealthKind::Wait,
223                label: "Wait p95, 24 h",
224                value: day.wait_p95().map_or_else(|| "–".to_owned(), duration),
225                of: None,
226                notes: vec![format!(
227                    "{started} job{} started",
228                    if started == 1 { "" } else { "s" }
229                )],
230                tone: Tone::Neutral,
231            });
232            let runner =
233                (day.runner_failed > 0).then(|| format!("{} by their runner", day.runner_failed));
234            figures.push(Figure {
235                kind: HealthKind::Failed,
236                label: "Failed, 24 h",
237                value: day.failed.to_string(),
238                of: Some(format!("of {} finished", day.finished)),
239                notes: runner.into_iter().collect(),
240                tone: day.failed_tone(),
241            });
242        }
243        figures
244    }
245}
246
247impl Activity {
248    /// What the day's failures mean: bad only when a runner failed, since a job's own failing steps are its
249    /// repository's.
250    pub fn failed_tone(&self) -> Tone {
251        if self.runner_failed > 0 {
252            Tone::Bad
253        } else {
254            Tone::Neutral
255        }
256    }
257}
258
259#[cfg(test)]
260mod tests;