Skip to main content

runnerd_core/
api.rs

1//! The daemon's JSON API, version 1: the request and response types every client deserializes, and the
2//! principal a transport authenticates. Plain data only: no I/O, no Docker or GitHub types, no secrets but a
3//! [`Pairing`]'s one-time link, which its `Debug` leaves out.
4//!
5//! Routes, all under the authenticated principal:
6//!
7//! | Route | Body |
8//! |---|---|
9//! | `GET /v1/status` | [`Status`] |
10//! | `POST /v1/repositories/{owner}/{name}/pause?`[`PauseQuery`] | [`Paused`]; 409 [`Busy`] while it runs a job |
11//! | `POST /v1/repositories/{owner}/{name}/resume` | none, 204 |
12//! | `POST /v1/repositories/pause?`[`PauseQuery`] | [`Paused`]; 409 [`Busy`] while any runs a job, pausing none |
13//! | `POST /v1/repositories/resume` | none, 204: every repository resumed |
14//! | `POST /v1/profiles/{name}/reseed` | none, 202; 409 while it reseeds; `cache.reseeded` when done |
15//! | `POST /v1/caches/{name}/clean` | none, 204; 409 [`Busy`] while a runner uses it |
16//! | `GET /v1/config` | [`ConfigFile`] |
17//! | `POST /v1/config/check` | TOML in, [`ConfigCheck`] |
18//! | `PUT /v1/config` | TOML in, [`ConfigCheck`]; 422 [`ConfigCheck`] when invalid |
19//! | `GET /v1/doctor` | [`Doctor`] |
20//! | `POST /v1/shutdown` | [`ShutdownRequest`] in, 202 |
21//! | `GET /v1/dashboard` | [`Dashboard`] |
22//! | `POST /v1/dashboard/sign-out` | none, 204 |
23//! | `POST /v1/dashboard/pairings?`[`PairingQuery`] | [`Pairings`]; 409 when the dashboard is off or has no `[web] origins` |
24//! | `GET /v1/jobs?`[`JobQuery`] | [`JobPage`] |
25//! | `GET /v1/jobs/{id}` | [`Job`] |
26//! | `GET /v1/jobs/{id}/samples` | [`SampleSeries`] |
27//! | `GET /v1/jobs/{id}/logs?`[`LogQuery`] | `text/plain`, one line per log line |
28//! | `GET /v1/host/samples?`[`HostSampleQuery`] | [`HostSamples`] |
29//! | `GET /v1/stats?`[`StatsQuery`] | [`Stats`] |
30//! | `GET /v1/activity?`[`ActivityQuery`] | [`Activity`] |
31//! | `GET /v1/sizing?`[`SizingQuery`] | [`Sizing`] |
32//! | `GET /v1/insights?`[`InsightsQuery`] | [`Insights`] |
33//! | `GET /v1/digest` | [`Digest`] |
34//! | `GET /v1/savings` | [`Savings`] |
35//! | `POST /v1/notify/test?`[`NotifyTestQuery`] | [`NotifyTest`]; 404 without `[notify]` targets or with no such one |
36//! | `GET /v1/caches` | [`Caches`] |
37//! | `GET /v1/caches/history?`[`CacheHistoryQuery`] | [`CacheHistory`] |
38//! | `GET /v1/events?`[`EventQuery`] | `text/event-stream` of [`EventEnvelope`] |
39//! | `GET /v1/records` | [`Records`] |
40//! | `DELETE /v1/records/{job}` | [`RemovedRecords`]; 409 while a shell is open in it |
41//! | `DELETE /v1/records?`[`RemoveRecordsQuery`] | [`RemovedRecords`]; records with an open shell stay |
42//! | `POST /v1/records/{job}/shell?`[`ShellQuery`] | `Upgrade:` [`SHELL_PROTOCOL`], 101, then the shell's terminal; 409 when the budget is full |
43//!
44//! Errors carry an [`ErrorResponse`].
45
46use serde::{Deserialize, Serialize};
47
48mod admission;
49mod budget;
50mod control;
51mod events;
52mod insights;
53mod jobs;
54mod records;
55mod results;
56mod savings;
57mod sizing;
58mod slots;
59mod stats;
60mod storage;
61mod tone;
62mod units;
63
64pub use admission::{Admission, AdmissionPolicy, Basis, CpuAdmission, JobPeak, cores, cpus};
65pub use budget::{
66    BudgetParts, ClosedKind, ClosedPart, FreePart, HeldKind, HeldPart, Reading, SlotPart,
67};
68pub use control::{
69    Busy, Check, CheckStatus, ConfigCheck, ConfigFile, Doctor, PauseQuery, Paused, ReplaceQuery,
70    RunningJob,
71};
72pub use events::{Event, EventEnvelope, EventQuery, RunnerFailure};
73pub use insights::{
74    AutoNote, Delivery, Digest, INSIGHT_DAYS, INSIGHT_DAYS_MAX, Insight, InsightKind, Insights,
75    InsightsQuery, LongWait, Notification, NotifyEvent, NotifyTest, NotifyTestQuery, Priority,
76    RepositoryWaits, RunLink, Severity, WaitSpread, WeekWaits,
77};
78pub use jobs::{
79    Activity, ActivityQuery, Bucket, BuildCacheCounts, BuildCacheStats, CacheHistory,
80    CacheHistoryQuery, CacheKind, CacheSize, CacheVolume, Caches, ChartLine, ChartLineKind,
81    ChartLines, Holder, HostMemory, HostSample, HostSampleQuery, HostSamples, Job, JobMetrics,
82    JobPage, JobQuery, JobRunner, JobState, JobSummary, JobTitle, Limit, LimitSource, Limits,
83    LogQuery, LogSummary, Milestone, Outcome, OutcomeKind, Phase, PhaseKind, Pressure,
84    RunComparison, Sample, SampleSeries, SampleUsage, Started, Stats, StatsQuery, StatsRow, Step,
85    Timeline, job_title,
86};
87pub use records::{
88    Record, RecordLimits, RecordNote, RecordRemoval, Records, RemoveRecordsQuery, RemovedRecords,
89    SHELL_PROTOCOL, ShellQuery,
90};
91pub use results::{force_pause_consequence, reseed_requested, reseeded};
92pub use savings::{
93    Period, PricedRun, PricedRunner, Pricing, PricingHistory, SELF_HOSTED_RATE, SavedWindow,
94    Savings, Sku, Usd, Visibility, billed_minutes, reads_since,
95};
96pub use sizing::{
97    Advice, AutoPlan, GRANULE, JobSizing, Need, PAGE_CACHE_ROOM, Peaks, ProfilePlan, ProfileSizing,
98    Resize, RevertCause, SAMPLE_INTERVAL, Sizing, SizingChange, SizingHold, SizingQuery,
99    SizingRefused, SizingRevert, Spread, Starts, need, period, sampled_note,
100};
101pub use slots::{Health, SlotState};
102pub use stats::StatsSummary;
103pub use storage::{
104    ACTIONS_CACHE, BUILD_CACHE_TOOLS, BuildCacheActivity, CacheLimit, RECORDS_NEAR_FULL,
105    RecordState, actions_cache_place, records_near_full,
106};
107pub use tone::{Tone, Toned};
108#[cfg(feature = "host")]
109pub(crate) use units::days_from_civil;
110pub use units::{ago, cores_used, cpu_time, duration, in_cores};
111
112/// Who sent a request, as the transport authenticated it. Handlers get it from one place, so a new transport only
113/// has to produce one.
114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
115#[serde(rename_all = "kebab-case", tag = "kind")]
116pub enum Principal {
117    /// The user the daemon runs as, on the local Unix socket.
118    LocalOwner {
119        /// The Unix user ID the socket's peer runs as.
120        uid: u32,
121    },
122}
123
124/// `GET /v1/status`: what the daemon serves and runs right now.
125#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
126pub struct Status {
127    /// The daemon's version, from its `Cargo.toml`.
128    pub version: String,
129    /// Set once the daemon stops polling to shut down.
130    pub shutting_down: bool,
131    /// The memory budget and what runners use of it.
132    pub budget: Budget,
133    /// Every configured profile with its slots.
134    pub profiles: Vec<ProfileStatus>,
135    /// Every configured repository.
136    pub repositories: Vec<RepositoryStatus>,
137    /// Queued jobs the repositories' runners can take and none holds yet, at the last poll, oldest first. No event
138    /// carries the list: `job.queued` announces a job, `job.started` and `job.finished` its leaving the queue.
139    /// A repository whose last listing failed, as while GitHub rate-limits runnerd, or that is no longer polled
140    /// because runnerd is shutting down, shows no jobs here, while the history keeps its jobs queued.
141    pub queued: Vec<QueuedJob>,
142}
143
144/// The memory budget runners and the mirror share, in bytes.
145#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
146pub struct Budget {
147    /// The systemd slice runner containers run in.
148    pub slice: String,
149    /// The slice's `MemoryMax`; `None` when it is unlimited.
150    pub memory_max: Option<u64>,
151    /// Memory the running containers reserve: the runners' caps, or under measured admission the larger of each
152    /// runner's predicted peak and its last sampled memory, and the caps of the seed containers, shells and the
153    /// mirror.
154    pub memory_in_use: u64,
155    /// What a new runner must fit in beside them.
156    pub admission: AdmissionPolicy,
157    /// Under measured admission, whether the slice is at the high-water mark, so no runner starts.
158    pub held: bool,
159    /// The mirror's part of `memory_in_use`: its cap while it is enabled or still running, else 0.
160    pub mirror_memory: u64,
161    /// The seed containers' part of `memory_in_use`, one per profile that reseeds, by profile name.
162    pub seed_memory: Vec<SeedMemory>,
163    /// The shells' part of `memory_in_use`, one per shell open in a record, by job.
164    pub shell_memory: Vec<ShellMemory>,
165    /// What the host's memory leaves runners beside its other programs, from a recent reading of it; absent
166    /// without one.
167    #[serde(default, skip_serializing_if = "Option::is_none")]
168    pub host: Option<HostBudget>,
169    /// The CPU budget, under `[host] cpu_overcommit`. Absent without one.
170    #[serde(default, skip_serializing_if = "Option::is_none")]
171    pub cpu: Option<CpuBudget>,
172    /// The CPUs the slice may use, in millicores: its `AllowedCPUs` or the host's, less under a lower `CPUQuota`,
173    /// whether or not a CPU budget admits runners. The runners' CPU limits are quotas that may add up past it.
174    /// Absent when it could not be read.
175    #[serde(default, skip_serializing_if = "Option::is_none")]
176    pub slice_cpus: Option<u64>,
177}
178
179/// What the host's memory leaves the runners (ADR 0055). New runners fit in the lower of `MemoryMax` and
180/// `limit`; running ones are never stopped for it.
181#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
182pub struct HostBudget {
183    /// The reading it comes from.
184    pub memory: HostMemory,
185    /// What the slice may hold now: what its runners hold without page cache plus the host's `MemAvailable`, less
186    /// a margin kept free for the host's page cache; with a ceiling, plus what the host can still grow by
187    /// (`HostMemory::growable`, ADR 0084).
188    pub limit: u64,
189    /// What that leaves new runners beside what the running ones reserve, in bytes.
190    pub spare: u64,
191    /// Whether the host's tasks stall for memory (`full` pressure), so no runner starts until they stop.
192    pub stalled: bool,
193}
194
195/// Hundredths of a percent as a percentage: `1.5%`, `12%`.
196pub fn percent(hundredths: u32) -> String {
197    let whole = hundredths / 100;
198    match hundredths % 100 / 10 {
199        0 => format!("{whole}%"),
200        tenth => format!("{whole}.{tenth}%"),
201    }
202}
203
204/// The CPU budget runners share, in millicores.
205#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
206pub struct CpuBudget {
207    /// The CPUs the slice may use: its `AllowedCPUs` or the host's, less under a lower `CPUQuota`.
208    pub cpus: u64,
209    /// Those times `cpu_overcommit`: what the runners' reservations must fit.
210    pub budget: u64,
211    /// What the runners reserve: each its predicted average CPU under measured admission, else its `cpus`.
212    pub in_use: u64,
213    /// Whether a queued job waits for CPU that memory and a slot have room for.
214    pub held: bool,
215}
216
217impl CpuBudget {
218    /// The budget's line as clients show it beside memory, such as `CPU 4.5 of 32 CPUs reserved` or, while a job
219    /// waits for it, `CPU 30 of 32 CPUs reserved; a job waits for CPU`.
220    pub fn line(&self) -> String {
221        let mut line = format!(
222            "CPU {} of {} CPUs reserved",
223            cores(self.in_use),
224            cores(self.budget)
225        );
226        if self.held {
227            line.push_str("; a job waits for CPU");
228        }
229        line
230    }
231}
232
233impl Budget {
234    /// How runners are admitted, as clients add it to the budget's line: nothing under caps, else `by predicted
235    /// peaks`, and why nothing starts while the slice is at the high-water mark.
236    pub fn admission_note(&self) -> Option<&'static str> {
237        match (self.admission, self.held) {
238            (AdmissionPolicy::Caps, _) => None,
239            (AdmissionPolicy::Measured, false) => Some("by predicted peaks"),
240            (AdmissionPolicy::Measured, true) => Some(
241                "by predicted peaks; the slice is past 90% of its MemoryMax, so no runner starts",
242            ),
243        }
244    }
245}
246
247/// A shell container's memory cap: its record's profile's limit when the shell opened.
248#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
249pub struct ShellMemory {
250    /// The job whose record the shell runs.
251    pub job: u64,
252    /// Its cap in bytes.
253    pub memory: u64,
254}
255
256/// A seed container's memory cap: its profile's limit when the reseed started, or, for a requested reseed whose
257/// profile drained, the room it holds until it starts.
258#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
259pub struct SeedMemory {
260    /// The profile it reseeds.
261    pub profile: String,
262    /// Its cap in bytes.
263    pub memory: u64,
264}
265
266/// A runner profile and what runs in its slots.
267#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
268pub struct ProfileStatus {
269    /// The name under `[profiles]` in `runnerd.toml`.
270    pub name: String,
271    /// The image its runners run, such as `runnerd-runner:base`.
272    pub image: String,
273    /// CPUs per slot.
274    pub cpus: u32,
275    /// Bytes per slot.
276    pub memory: u64,
277    /// Set while slot 1's layers become the profile's snapshot.
278    pub reseeding: bool,
279    /// Index 0 is slot 1.
280    pub slots: Vec<SlotStatus>,
281}
282
283/// One slot of a profile: room for one job.
284#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
285pub struct SlotStatus {
286    /// 1-based.
287    pub slot: usize,
288    /// `None` when the slot is free.
289    pub runner: Option<RunnerStatus>,
290}
291
292/// A runner registered for one job, in its container.
293#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
294pub struct RunnerStatus {
295    /// `owner/name` the runner is registered on.
296    pub repository: String,
297    /// The runner's name, also its container's.
298    pub name: String,
299    /// The runner's ID on GitHub.
300    pub runner_id: u64,
301    /// The Docker container ID.
302    pub container: String,
303    /// Whether it runs a job, as GitHub or its log reports it: its log names the job before GitHub lists it busy.
304    pub busy: bool,
305    /// Seconds since the Unix epoch.
306    pub started_at: u64,
307    /// What it takes of the budget: its cap under caps; under measured admission the larger of its predicted peak
308    /// and its last sampled memory.
309    pub reserved: u64,
310    /// A warm runner: idle, and no queued job of its repository waits for it; it takes the next one GitHub hands
311    /// out.
312    pub warm: bool,
313}
314
315/// A configured repository and its queue.
316#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
317pub struct RepositoryStatus {
318    /// `owner/name` on GitHub.
319    pub name: String,
320    /// Its pools in config order, one per `[[repositories]]` entry: a job runs in the one whose labels match it
321    /// (ADR 0058).
322    pub pools: Vec<PoolStatus>,
323    /// Paused repositories get no new runners; their running jobs finish.
324    pub paused: bool,
325    /// Its jobs in `Status::queued`: queued ones none of its runners took yet, those no pool serves too.
326    pub queued_jobs: usize,
327}
328
329/// One of a repository's pools: its runners in one profile.
330#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
331pub struct PoolStatus {
332    /// The profile its jobs run in.
333    pub profile: String,
334    /// The labels its runners register with.
335    pub labels: Vec<String>,
336    /// Its jobs in `Status::queued`: those its labels match.
337    pub queued_jobs: usize,
338}
339
340/// A queued job runners of this daemon can take, as GitHub listed it at the last poll.
341#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
342pub struct QueuedJob {
343    /// GitHub's job ID.
344    pub id: u64,
345    /// The repository whose runners can take it, `owner/name`.
346    pub repository: String,
347    /// The profile of its repository's pool whose labels match it; `None` when no pool's do.
348    #[serde(default, skip_serializing_if = "Option::is_none")]
349    pub profile: Option<String>,
350    /// The workflow run it belongs to.
351    pub run_id: u64,
352    /// 1 for the first attempt of the run, higher for re-runs.
353    pub run_attempt: u32,
354    /// The workflow's name.
355    pub workflow: Option<String>,
356    /// The job's name in the workflow.
357    pub name: String,
358    /// The branch the run is for.
359    pub branch: Option<String>,
360    /// The job's page on GitHub.
361    pub url: Option<String>,
362    /// When GitHub queued it, in seconds since the Unix epoch; 0 if GitHub did not say.
363    pub queued_at: u64,
364    /// Why no runner has it yet, as the last plan saw it. `None` before the daemon has planned with it, and while
365    /// it shuts down.
366    #[serde(default, skip_serializing_if = "Option::is_none")]
367    pub waiting: Option<Waiting>,
368}
369
370/// The slot of an idle runner of `job`'s repository, in its pool's profile when known, such as `jvm 2`.
371fn starting_for(job: &QueuedJob, status: &Status) -> Option<String> {
372    status
373        .profiles
374        .iter()
375        .filter(|profile| job.profile.as_ref().is_none_or(|own| *own == profile.name))
376        .find_map(|profile| {
377            profile
378                .slots
379                .iter()
380                .find(|slot| {
381                    slot.runner
382                        .as_ref()
383                        .is_some_and(|runner| runner.repository == job.repository && !runner.busy)
384                })
385                .map(|slot| format!("{}\u{a0}{}", profile.name, slot.slot))
386        })
387}
388
389impl QueuedJob {
390    /// Where it runs, as every client names it: its repository, and its pool's profile when the repository has
391    /// several pools in `status`, such as `halyard/ledger · light`.
392    pub fn place(&self, status: &Status) -> String {
393        let pools = status
394            .repositories
395            .iter()
396            .find(|repository| repository.name == self.repository)
397            .map_or(0, |repository| repository.pools.len());
398        match self.profile.as_deref().filter(|_| pools > 1) {
399            Some(profile) => format!("{}\u{a0}· {profile}", self.repository),
400            None => self.repository.clone(),
401        }
402    }
403}
404
405impl RepositoryStatus {
406    /// The profile of its first pool, which every client colours it by.
407    pub fn first_profile(&self) -> &str {
408        self.pools.first().map_or("", |pool| pool.profile.as_str())
409    }
410
411    /// Its pools' profiles, as every client lists them on one line: `jvm` or `jvm + light`.
412    pub fn profiles(&self) -> String {
413        self.pools
414            .iter()
415            .map(|pool| pool.profile.as_str())
416            .collect::<Vec<_>>()
417            .join(" + ")
418    }
419
420    /// The profile of its pool whose labels match a job asking for `labels`, as the daemon picks it.
421    pub fn pool_for(&self, labels: &[String]) -> Option<String> {
422        self.pools
423            .iter()
424            .find(|pool| crate::config::labels_match(labels, &pool.labels))
425            .map(|pool| pool.profile.clone())
426    }
427}
428
429/// What failed, that holds a repository's runners back for a while.
430#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
431#[serde(rename_all = "kebab-case")]
432pub enum HoldCause {
433    /// Its runners ended without taking a job.
434    NoJob,
435    /// Its runners ended without a job after waiting for one, twice in a row.
436    IdleExits,
437    /// GitHub did not register its runner.
438    Register,
439    /// Docker did not start its runner's container.
440    Start,
441}
442
443/// Why a queued job has no runner of its own yet. Jobs are served oldest first; each takes the first of these that
444/// holds for it.
445#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
446#[serde(rename_all = "kebab-case", tag = "kind")]
447pub enum Waiting {
448    /// Its repository is paused.
449    Paused,
450    /// Runners of its repository failed, so none starts before `until` (seconds since the Unix epoch).
451    Backoff {
452        /// When runners may start again.
453        until: u64,
454        /// What failed.
455        cause: HoldCause,
456    },
457    /// A runner started for it and waits for GitHub to hand it the job: a runner takes any job its labels match,
458    /// so not necessarily this one.
459    RunnerStarting,
460    /// Slot 1 of its profile is becoming the profile's snapshot, so none of the profile's slots starts.
461    Reseeding {
462        /// The profile.
463        profile: String,
464    },
465    /// Its profile's image is being pulled, so none of the profile's slots starts.
466    PullingImage {
467        /// The profile.
468        profile: String,
469    },
470    /// Every slot of its profile holds a runner.
471    NoSlot {
472        /// The profile.
473        profile: String,
474    },
475    /// What its runner would reserve does not fit the memory budget left. Under measured admission, `free` is 0
476    /// while the slice is at the high-water mark (`Budget::held`).
477    Memory {
478        /// What its runner would reserve, in bytes.
479        needs: u64,
480        /// What the budget has left, in bytes.
481        free: u64,
482    },
483    /// What its runner would reserve does not fit what the host's memory has to spare beside its other programs
484    /// (`HostBudget::spare`), though it fits the slice's budget. `free` is 0 while the host's tasks stall for memory
485    /// (`HostBudget::stalled`).
486    HostMemory {
487        /// What its runner would reserve, in bytes.
488        needs: u64,
489        /// What the host has to spare, in bytes.
490        free: u64,
491    },
492    /// What its runner would reserve does not fit the CPU budget left, in millicores.
493    Cpu {
494        /// What its runner would reserve.
495        needs: u64,
496        /// What the CPU budget has left.
497        free: u64,
498    },
499    /// An older job has waited long enough for CPU that no younger one takes CPU before it.
500    BehindCpu {
501        /// The older job's ID.
502        job: u64,
503    },
504    /// An older job is about to have a runner start for it, which takes the slot, memory or CPU this one would
505    /// otherwise start with: what holds it is that start, not what runs now.
506    BehindStart {
507        /// The older job's ID.
508        job: u64,
509    },
510    /// No pool of its repository has every label it asks for, so no runner of this daemon can take it (ADR 0058).
511    NoPool {
512        /// The labels it asks for.
513        labels: Vec<String>,
514    },
515    /// A reason from a newer daemon than this client knows, so a reason added later does not keep the client from
516    /// reading the status.
517    #[serde(other)]
518    Unknown,
519}
520
521/// What a [`Waiting`] reason waits on, which clients draw it by.
522#[derive(Debug, Clone, Copy, PartialEq, Eq)]
523pub enum WaitKind {
524    /// Something the owner can act on: a pause, runners that failed to take a job, or labels no pool serves.
525    Act,
526    /// Something that clears by itself shortly: a runner starting, a reseed, an image pull, an older job's start.
527    Soon,
528    /// Room: a slot, memory or CPU that a running job holds.
529    Full,
530    /// A reason this client does not know (`Waiting::Unknown`), drawn neutral.
531    Other,
532}
533
534impl Waiting {
535    /// What it waits on.
536    pub fn kind(&self) -> WaitKind {
537        match self {
538            Waiting::Paused | Waiting::Backoff { .. } | Waiting::NoPool { .. } => WaitKind::Act,
539            Waiting::Unknown => WaitKind::Other,
540            Waiting::RunnerStarting
541            | Waiting::Reseeding { .. }
542            | Waiting::PullingImage { .. }
543            | Waiting::BehindStart { .. } => WaitKind::Soon,
544            Waiting::NoSlot { .. }
545            | Waiting::Memory { .. }
546            | Waiting::HostMemory { .. }
547            | Waiting::Cpu { .. }
548            | Waiting::BehindCpu { .. } => WaitKind::Full,
549        }
550    }
551
552    /// Why `job` waits, in the owner's words with the numbers that hold it, as every client says it: such as
553    /// `All 2 node slots are busy` or `Needs 9G of memory; 2.5G of the budget is free`. `status` is the one `job`
554    /// is queued in, which names the slot of a starting runner and the older job one waits behind.
555    pub fn reason(&self, job: &QueuedJob, status: &Status, now: u64) -> String {
556        let size = |bytes: u64| crate::config::ByteSize(bytes).to_string();
557        let older_name = |id: u64| {
558            status
559                .queued
560                .iter()
561                .find(|candidate| candidate.id == id)
562                .map_or_else(|| "an older job".to_owned(), |older| older.name.clone())
563        };
564        match self {
565            Waiting::Paused => format!("{} is paused", job.repository),
566            Waiting::Unknown => "Waits for a reason this client does not know yet".to_owned(),
567            Waiting::NoPool { labels } if labels.is_empty() => {
568                "It asks for no labels, so no profile serves it".to_owned()
569            }
570            Waiting::NoPool { labels } => format!(
571                "No profile serves the {} {}",
572                if labels.len() == 1 { "label" } else { "labels" },
573                labels.join(", ")
574            ),
575            Waiting::Backoff { until, cause } => format!(
576                "{}; retrying in {}",
577                match cause {
578                    HoldCause::NoJob => "Runners failed to take a job",
579                    HoldCause::IdleExits => "Runners ended without a job after waiting for one",
580                    HoldCause::Register => "Runners cannot register with GitHub",
581                    HoldCause::Start => "Runners cannot start",
582                },
583                duration(until.saturating_sub(now))
584            ),
585            Waiting::RunnerStarting => match starting_for(job, status) {
586                Some(slot) => format!("A runner is starting for it in {slot}"),
587                None => "A runner is starting for it".to_owned(),
588            },
589            Waiting::Reseeding { profile } => format!("{profile} is rebuilding its snapshot"),
590            Waiting::PullingImage { profile } => format!("Pulling {profile}'s image"),
591            Waiting::NoSlot { profile } => {
592                let slots = status
593                    .profiles
594                    .iter()
595                    .find(|candidate| &candidate.name == profile)
596                    .map_or(0, |profile| profile.slots.len());
597                if slots == 1 {
598                    format!("The {profile} slot is busy")
599                } else {
600                    format!("All {slots} {profile} slots are busy")
601                }
602            }
603            Waiting::Memory { .. } if status.budget.held => {
604                "The slice is past 90% of its MemoryMax, so nothing starts".to_owned()
605            }
606            Waiting::Memory { needs, free } => format!(
607                "Needs {} of memory; {} of the budget is free",
608                size(*needs),
609                size(*free)
610            ),
611            Waiting::HostMemory { needs, free } => {
612                let host = status.budget.host.as_ref();
613                let reason = if host.is_some_and(|host| host.stalled) {
614                    "The host is short of memory: its programs stall waiting for it, so nothing starts"
615                        .to_owned()
616                } else {
617                    format!(
618                        "The host is short of memory: needs {}; the host has {} to spare",
619                        size(*needs),
620                        size(*free)
621                    )
622                };
623                match host {
624                    Some(host) => format!("{reason}; {}", host.memory.outside_line()),
625                    None => reason,
626                }
627            }
628            Waiting::Cpu { needs, free } => {
629                format!(
630                    "Needs {}; {} are free",
631                    cpus(*needs),
632                    admission::free_cores(*free)
633                )
634            }
635            Waiting::BehindCpu { job: older } => {
636                format!("Behind {}, which waits for CPU", older_name(*older))
637            }
638            Waiting::BehindStart { job: older } => {
639                format!(
640                    "Next after {}, whose runner starts first",
641                    older_name(*older)
642                )
643            }
644        }
645    }
646}
647
648/// `GET /v1/dashboard`: the dashboard's `[web]` settings, as the daemon read them when it started.
649#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
650pub struct Dashboard {
651    /// `[web] open`: the one of `[web] origins` that `runnerctl web` opens the dashboard on; the loopback address
652    /// when none.
653    #[serde(default, skip_serializing_if = "Option::is_none")]
654    pub open: Option<String>,
655}
656
657/// `POST /v1/dashboard/pairings`: which of `[web] origins` to make a link for.
658#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
659pub struct PairingQuery {
660    /// One of `[web] origins`; each of them when none.
661    #[serde(default, skip_serializing_if = "Option::is_none")]
662    pub origin: Option<String>,
663}
664
665/// `POST /v1/dashboard/pairings`: fresh one-time links that sign a device in to the dashboard.
666#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
667pub struct Pairings {
668    /// One per origin asked for.
669    pub links: Vec<Pairing>,
670}
671
672/// A link that signs one device in to the dashboard on `origin`, and nowhere else, within `lifetime`.
673#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
674pub struct Pairing {
675    /// One of `[web] origins`.
676    pub origin: String,
677    /// The link with its one-time code: a credential, which `Debug` leaves out.
678    pub url: String,
679    /// Seconds it works for from when it was made.
680    pub lifetime: u64,
681}
682
683impl std::fmt::Debug for Pairing {
684    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
685        formatter
686            .debug_struct("Pairing")
687            .field("origin", &self.origin)
688            .field("lifetime", &self.lifetime)
689            .finish_non_exhaustive()
690    }
691}
692
693/// `POST /v1/shutdown`.
694#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
695pub struct ShutdownRequest {
696    /// Kill running jobs and delete their runners instead of waiting for them.
697    #[serde(default)]
698    pub force: bool,
699}
700
701/// The body of every error response.
702#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
703pub struct ErrorResponse {
704    /// What went wrong, for people to read.
705    pub message: String,
706}