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`]; 503 [`ErrorResponse`] while no run has finished |
20//! | `GET /v1/attention` | [`Attention`]; 404 from a daemon before 0.2 |
21//! | `POST /v1/shutdown` | [`ShutdownRequest`] in, 202 [`ShutdownAnswer`] |
22//! | `GET /v1/dashboard` | [`Dashboard`] |
23//! | `POST /v1/dashboard/sign-out` | none, 204 |
24//! | `POST /v1/dashboard/pairings?`[`PairingQuery`] | [`Pairings`]; 409 when the dashboard is off or has no `[web] origins` |
25//! | `GET /v1/jobs?`[`JobQuery`] | [`JobPage`] |
26//! | `GET /v1/jobs/{id}` | [`Job`] |
27//! | `GET /v1/jobs/{id}/samples` | [`SampleSeries`] |
28//! | `GET /v1/jobs/{id}/logs?`[`LogQuery`] | `text/plain`, one line per log line |
29//! | `GET /v1/host/samples?`[`HostSampleQuery`] | [`HostSamples`] |
30//! | `GET /v1/stats?`[`StatsQuery`] | [`Stats`] |
31//! | `GET /v1/activity?`[`ActivityQuery`] | [`Activity`] |
32//! | `GET /v1/sizing?`[`SizingQuery`] | [`Sizing`] |
33//! | `GET /v1/insights?`[`InsightsQuery`] | [`Insights`] |
34//! | `GET /v1/digest` | [`Digest`] |
35//! | `GET /v1/savings` | [`Savings`] |
36//! | `POST /v1/notify/test?`[`NotifyTestQuery`] | [`NotifyTest`]; 404 without `[notify]` targets or with no such one |
37//! | `GET /v1/caches` | [`Caches`] |
38//! | `GET /v1/caches/history?`[`CacheHistoryQuery`] | [`CacheHistory`] |
39//! | `GET /v1/events?`[`EventQuery`] | `text/event-stream` of [`EventEnvelope`] |
40//! | `GET /v1/records` | [`Records`] |
41//! | `DELETE /v1/records/{job}` | [`RemovedRecords`]; 409 while a shell is open in it |
42//! | `DELETE /v1/records?`[`RemoveRecordsQuery`] | [`RemovedRecords`]; records with an open shell stay |
43//! | `POST /v1/records/{job}/shell?`[`ShellQuery`] | `Upgrade:` [`SHELL_PROTOCOL`], 101, then the shell's terminal; 409 when the budget is full |
44//!
45//! Errors carry an [`ErrorResponse`].
46
47use serde::{Deserialize, Serialize};
48
49mod actions;
50mod admission;
51mod archives;
52mod attention;
53mod budget;
54mod control;
55mod disk;
56mod events;
57mod figure;
58mod insights;
59mod jobs;
60mod labels;
61mod queue;
62mod records;
63mod results;
64mod savings;
65mod sizing;
66mod slots;
67mod stats;
68mod storage;
69mod tone;
70mod units;
71
72pub use actions::{
73    ActionAnswer, ActionOutcome, ActionPreview, ActionQuery, ActionRefusal, ActionResult,
74    ActionTarget, CONFIRM_SECS, JOB_ACTIONS_CHECK, JobAction, JobActions, PreviewFacts,
75    RerunRefused, RunSeen, SIBLINGS_MAX, Superseded, UnknownCause, actions_in_flight,
76    actions_no_run, actions_not_configured, actions_off,
77};
78pub use admission::{Admission, AdmissionPolicy, Basis, CpuAdmission, JobPeak, cores, cpus};
79pub use archives::{ActionArchives, ArchiveFailure, ArchiveFailureKind};
80pub use attention::{
81    ATTENTION_MAX, Attention, AttentionItem, AttentionKind, Fix, Subject, attention_items,
82};
83pub use budget::{
84    BudgetParts, ClosedKind, ClosedPart, FreePart, HeldKind, HeldPart, HostFigure, Reading,
85    SlotForm, SlotPart, SlotReading,
86};
87pub use control::{
88    Busy, Check, CheckCount, CheckStatus, ConfigCheck, ConfigFile, Doctor, DoctorQuery,
89    DoctorState, DoctorSummary, PauseQuery, Paused, ReplaceQuery, RunningJob,
90};
91pub use disk::{
92    Commits, DiskWrites, DiskWritten, DriveShare, DriveShares, DriveWrites, JobWrites, Measure,
93    ShareOwner, WriteSection, WriteTop,
94};
95pub use events::{Event, EventEnvelope, EventQuery, RunnerFailure};
96pub use figure::LabelledFigure;
97pub use insights::{
98    AutoNote, CauseWait, Delivery, Digest, HostHazard, HostSpan, INSIGHT_DAYS, INSIGHT_DAYS_MAX,
99    Insight, InsightFigure, InsightKind, Insights, InsightsHeading, InsightsQuery, LongWait,
100    Notification, NotifyEvent, NotifyTest, NotifyTestQuery, Priority, ProfileQueue,
101    RepositoryWaits, RunLink, Severity, WaitFigure, WaitSpread, WeekWaits,
102};
103#[cfg(feature = "host")]
104pub(crate) use jobs::SAMPLE_GAP_INTERVALS;
105#[cfg(feature = "host")]
106pub(crate) use jobs::TITLE_SOURCE_MAX;
107pub use jobs::{
108    Activity, ActivityQuery, Bucket, BuildCacheCounts, BuildCacheStats, CacheHistory,
109    CacheHistoryQuery, CacheKind, CacheSize, CacheVolume, Caches, ChartLine, ChartLineKind,
110    ChartLines, FailureCause, Holder, HostMemory, HostSample, HostSampleQuery, HostSamples, Job,
111    JobMetrics, JobPage, JobQuery, JobRunner, JobState, JobSummary, JobTitle, Limit, LimitSource,
112    Limits, LogQuery, LogSummary, Milestone, Outcome, OutcomeKind, Phase, PhaseKind, Pressure,
113    RunComparison, RunnerProbe, Sample, SampleSeries, SampleUsage, Started, Stats, StatsQuery,
114    StatsRow, Step, Swap, Timeline, Total, host_margin, job_title,
115};
116pub use jobs::{
117    BarEnd, Baseline, BaselineRead, COMPARE_STEP_BYTES, COMPARE_STEPS_MAX, ChangeKind,
118    CompareQuery, ComparedSteps, FigureDelta, FigureKind, Gap, GapKind, JOB_LABELS_MAX,
119    JOB_SEARCH_MAX, JOB_TEXT_MAX, JOBS_PAGE_BYTES, JOBS_PAGE_DEFAULT, JOBS_PAGE_MAX, JobComparison,
120    JobList, JobOrder, JobRange, JobSort, Lane, RecordFilter, RecordMark, RunnerSpan, SlotKey,
121    SlotTimeline, SlottedBar, SlottedRunner, SortOrder, Span, StepDelta, StepMatch, StepUsage,
122    TIMELINE_BARS_MAX, TIMELINE_DEFAULT, TIMELINE_WINDOW_MAX, TimelineBar, TimelineQuery,
123    TimelineRows, Unavailable, row_bytes,
124};
125pub use jobs::{
126    Color, FailureSummary, LINE_BYTES_MAX, LINES_DEFAULT, LINES_MAX, LineKind, LineRange, LineRead,
127    LogEvidence, LogGroup, LogLinesQuery, LogMark, LogNeedle, LogOutline, LogSearch,
128    LogSearchQuery, MarkKind, OutlineChange, OutlineParts, Outliner, RUNS_MAX, Run,
129    SEARCH_QUERY_MAX, SavedOutline, Search, StepLines, StepLog, StoredLine, StoredLog, StyledLine,
130};
131pub use labels::{Column, Feature, JOBS_HEADING, NOT_SUPPORTED, Section, View};
132pub use queue::{HostWait, WaitCause};
133pub use records::{
134    Record, RecordLimits, RecordNote, RecordRemoval, Records, RemoveRecordsQuery, RemovedRecords,
135    SHELL_PROTOCOL, ShellQuery,
136};
137pub use results::{force_pause_consequence, reseed_outcome, reseed_requested, reseeded};
138pub use savings::{
139    Period, PricedRun, PricedRunner, Pricing, PricingHistory, SELF_HOSTED_RATE, SavedWindow,
140    Savings, Sku, Usd, Visibility, billed_minutes, reads_since,
141};
142pub use sizing::{
143    Advice, AutoPlan, GRANULE, JobSizing, MemoryBound, MemoryHold, Need, PAGE_CACHE_ROOM, Peaks,
144    ProfilePlan, ProfileSizing, Resize, RevertCause, SAMPLE_INTERVAL, SLOT_DISK, Sizing,
145    SizingChange, SizingHold, SizingQuery, SizingRefused, SizingRevert, Spread, Starts, need,
146    period, sampled_note,
147};
148pub use slots::{Figure, Health, HealthKind, SlotState};
149pub use stats::StatsSummary;
150pub use storage::{
151    ACTIONS_CACHE, BUILD_CACHE_TOOLS, BuildCacheActivity, CacheLimit, RECORDS_NEAR_FULL,
152    RecordState, actions_cache_place, records_check, records_near_full,
153};
154pub use tone::{Tone, Toned};
155pub(crate) use units::days_from_civil;
156pub use units::{ago, cores_used, cpu_time, duration, in_cores};
157
158/// Who sent a request, as the transport authenticated it. Handlers get it from one place, so a new transport only
159/// has to produce one.
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161#[serde(rename_all = "kebab-case", tag = "kind")]
162pub enum Principal {
163    /// The user the daemon runs as, on the local Unix socket.
164    LocalOwner {
165        /// The Unix user ID the socket's peer runs as.
166        uid: u32,
167    },
168}
169
170/// `GET /v1/status`: what the daemon serves and runs right now.
171#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
172pub struct Status {
173    /// The daemon's version, from its `Cargo.toml`.
174    pub version: String,
175    /// Set once the daemon stops polling to shut down. [`Status::stopping_line`] says how.
176    pub shutting_down: bool,
177    /// How it stops, once it does; absent from a daemon before it said.
178    #[serde(default, skip_serializing_if = "Option::is_none")]
179    pub stopping: Option<Stopping>,
180    /// Until when GitHub's rate limit is used up, in seconds since the Unix epoch: no runner starts before.
181    /// [`Status::github_line`] says it. Absent while it is not.
182    #[serde(default, skip_serializing_if = "Option::is_none")]
183    pub github_limited_until: Option<u64>,
184    /// The memory budget and what runners use of it.
185    pub budget: Budget,
186    /// Every configured profile with its slots.
187    pub profiles: Vec<ProfileStatus>,
188    /// Every configured repository.
189    pub repositories: Vec<RepositoryStatus>,
190    /// Queued jobs the repositories' runners can take and none holds yet, at the last poll, oldest first. No event
191    /// carries the list: `job.queued` announces a job, `job.started` and `job.finished` its leaving the queue.
192    /// A repository whose last listing failed, as while GitHub rate-limits runnerd, or that is no longer polled
193    /// because runnerd is shutting down, shows no jobs here, while the history keeps its jobs queued.
194    pub queued: Vec<QueuedJob>,
195    /// Whether the daemon cancels and re-runs jobs (ADR 0134); a daemon before 0.2 sends none, read as
196    /// [`JobActions::Unsupported`].
197    #[serde(default)]
198    pub job_actions: JobActions,
199    /// The action archives runnerd keeps for its runners (ADR 0147); absent while `[caches.actions]` is off, before
200    /// the store opened, and from an older daemon.
201    #[serde(default, skip_serializing_if = "Option::is_none")]
202    pub action_archives: Option<ActionArchives>,
203}
204
205/// The memory budget runners and the mirror share, in bytes.
206#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
207pub struct Budget {
208    /// The systemd slice runner containers run in.
209    pub slice: String,
210    /// The slice's `MemoryMax`; `None` when it is unlimited.
211    pub memory_max: Option<u64>,
212    /// Memory the running containers reserve: the runners' caps, or under measured admission the larger of each
213    /// runner's predicted peak and its last sampled memory, nothing for one whose container is gone, and the caps of
214    /// the seed containers, shells and the mirror.
215    pub memory_in_use: u64,
216    /// What pooling takes off `memory_in_use` (ADR 0099, 0130); absent while it takes nothing.
217    #[serde(default, skip_serializing_if = "Option::is_none")]
218    pub pooled: Option<Pooled>,
219    /// The growth count both budgets go by, and its brake (ADR 0130); `pooled` and `host.credit` say what it takes off
220    /// `memory_in_use`. Absent under caps admission, with `[host] pooled_count` off, and from an older daemon.
221    #[serde(default, skip_serializing_if = "Option::is_none")]
222    pub counted: Option<Counted>,
223    /// What a new runner must fit in beside them.
224    pub admission: AdmissionPolicy,
225    /// Under measured admission, whether the slice is at the high-water mark, so no runner starts.
226    pub held: bool,
227    /// The mirror's part of `memory_in_use`: its cap while it is enabled or still running, else 0.
228    pub mirror_memory: u64,
229    /// The seed containers' part of `memory_in_use`, one per profile that reseeds, by profile name.
230    pub seed_memory: Vec<SeedMemory>,
231    /// The shells' part of `memory_in_use`, one per shell open in a record, by job.
232    pub shell_memory: Vec<ShellMemory>,
233    /// What the host's memory leaves runners beside its other programs, from a recent reading of it; absent
234    /// without one.
235    #[serde(default, skip_serializing_if = "Option::is_none")]
236    pub host: Option<HostBudget>,
237    /// The CPU budget, under `[host] cpu_overcommit`. Absent without one.
238    #[serde(default, skip_serializing_if = "Option::is_none")]
239    pub cpu: Option<CpuBudget>,
240    /// The CPUs the slice may use, in millicores: its `AllowedCPUs` or the host's, less under a lower `CPUQuota`,
241    /// whether or not a CPU budget admits runners. The runners' CPU limits are quotas that may add up past it.
242    /// Absent when it could not be read.
243    #[serde(default, skip_serializing_if = "Option::is_none")]
244    pub slice_cpus: Option<u64>,
245}
246
247/// The count the budgets go by while pooling takes something off `Budget::memory_in_use` (ADR 0099).
248#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
249pub struct Pooled {
250    /// What it takes off, in bytes.
251    pub credit: u64,
252    /// `Budget::memory_in_use` less `credit`: what new runners fit beside under `MemoryMax`. The host's limit reads
253    /// `memory_in_use`.
254    pub counted: u64,
255    /// How many runners the credit counts on.
256    pub runners: u64,
257}
258
259/// How far back the growth count's brake compares what runs uses: 10 minutes (ADR 0130,
260/// `admission::growth::GROWTH_WINDOW`).
261pub const GROWTH_WINDOW: std::time::Duration = std::time::Duration::from_mins(10);
262
263/// The growth count (ADR 0130): what the runners use, and the room kept for what they may still grow by.
264#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
265pub struct Counted {
266    /// What the runners use, by their recent samples, in bytes.
267    pub used: u64,
268    /// The room it keeps for their growth, in bytes; absent while it rests (`brake`).
269    #[serde(default, skip_serializing_if = "Option::is_none")]
270    pub kept: Option<u64>,
271    /// How many of the largest growths the room covers at least.
272    pub jobs: u64,
273    /// Why it rests, while it does: the budgets then go by 0099's and 0108's credits.
274    #[serde(default, skip_serializing_if = "Option::is_none")]
275    pub brake: Option<CountBrake>,
276}
277
278/// Why the growth count rests (ADR 0130).
279#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
280#[serde(rename_all = "kebab-case", tag = "kind")]
281pub enum CountBrake {
282    /// What ran grew past the room kept within `GROWTH_WINDOW`.
283    Grew {
284        /// How much the runners present at both looks grew, together, in bytes.
285        grew: u64,
286        /// The room the earlier look kept, in bytes.
287        kept: u64,
288        /// Until when, in seconds since the Unix epoch.
289        until: u64,
290    },
291    /// The daemon started, or a reload changed what the count reads, too recently to judge growth.
292    Restarted {
293        /// Until when, in seconds since the Unix epoch.
294        until: u64,
295    },
296    /// The host is under the guard's line, or a reading is missing, now or at a look within 5 minutes.
297    Guard {
298        /// Until when, in seconds since the Unix epoch; absent for a moment the brake has not looked at yet.
299        #[serde(default, skip_serializing_if = "Option::is_none")]
300        until: Option<u64>,
301    },
302    /// A brake a newer daemon names; this client shows only that the count rests.
303    #[serde(other)]
304    Unknown,
305}
306
307/// What the host's memory leaves the runners (ADR 0055). New runners fit in the lower of `MemoryMax` and
308/// `limit`; running ones are never stopped for it.
309#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
310pub struct HostBudget {
311    /// The reading it comes from.
312    pub memory: HostMemory,
313    /// What the slice may hold now: what its runners hold without page cache plus the host's `MemAvailable`, less
314    /// a margin kept free for the host's page cache; with a ceiling, plus what the host can still grow by
315    /// (`HostMemory::growable`, ADR 0084).
316    pub limit: u64,
317    /// What that leaves new runners beside what the running ones reserve, in bytes.
318    pub spare: u64,
319    /// Whether the host's tasks stall for memory (`full` pressure), so no runner starts until they stop.
320    pub stalled: bool,
321    /// What the host's limit takes off `Budget::memory_in_use` for runners that may not all grow at once (ADR 0108);
322    /// absent while it takes nothing, and from a daemon before 0.0.30.
323    #[serde(default, skip_serializing_if = "Option::is_none")]
324    pub credit: Option<HostCredit>,
325}
326
327/// What the host's limit takes off the plain count (ADR 0108): `Budget::memory_in_use` less `bytes` is what it counts,
328/// `used` of that is what the runners use, and the rest is room kept for what runs to grow into.
329#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
330pub struct HostCredit {
331    /// What it takes off, in bytes.
332    pub bytes: u64,
333    /// What the runners use, by their recent samples, in bytes.
334    pub used: u64,
335}
336
337impl HostBudget {
338    /// Whether the host itself lacks `needs` bytes for a new runner: its tasks stall, `HostMemory::room` is less, or
339    /// that room is under one more margin, so `MemAvailable` is under twice the plain margin, the line `host::stalls`
340    /// reads. There a small job fits only by what the host is about to run out of, and what closing programs frees is
341    /// what starts it. Otherwise a job the host limit holds waits for what runs, whose reservations reach the limit
342    /// (ADR 0103).
343    pub fn short_of(&self, needs: u64) -> bool {
344        let room = self.memory.room();
345        self.stalled || needs > room || room < host_margin(self.memory.grown())
346    }
347
348    /// What the host's limit counts of what runs, `reserved` being `Budget::memory_in_use`: that less the credit
349    /// (ADR 0108).
350    pub fn counts(&self, reserved: u64) -> u64 {
351        reserved.saturating_sub(self.credit.map_or(0, |credit| credit.bytes))
352    }
353
354    /// What that count is made of while a credit stands, as the host's line, a job's wait and the log say it: `it uses
355    /// 14G and keeps 9G for growth`. `None` without a credit, when it counts every reservation.
356    pub fn growth_clause(&self, reserved: u64) -> Option<String> {
357        let credit = self.credit?;
358        let counts = self.counts(reserved);
359        Some(format!(
360            "it uses {} and keeps {} for growth",
361            crate::config::ByteSize(credit.used.min(counts)),
362            crate::config::ByteSize(counts.saturating_sub(credit.used))
363        ))
364    }
365}
366
367/// Why a job waits for the host's limit, needing `needs` bytes with `free` left of it, by the latest reading: for what
368/// runs, or for a host that lacks the room, whose programs it names. While the host's limit takes a credit, what runs
369/// is what it uses and the room it keeps for growth, not its reservations (ADR 0108); `reserved` is
370/// `Budget::memory_in_use`.
371fn host_reason(needs: u64, free: u64, host: Option<&HostBudget>, reserved: u64) -> String {
372    let size = |bytes: u64| crate::config::ByteSize(bytes).to_string();
373    if let Some(host) = host.filter(|host| !host.short_of(needs)) {
374        if let Some(growth) = host.growth_clause(reserved) {
375            return format!(
376                "The host has {}, but what runs may still grow into it: {growth}; needs {}, {} is free",
377                host.memory.available_line(),
378                size(needs),
379                size(free)
380            );
381        }
382        return format!(
383            "The host has {}, but what runs may still grow into it: needs {}; {} of the {} it leaves the slice is free",
384            host.memory.available_line(),
385            size(needs),
386            size(free),
387            size(host.limit)
388        );
389    }
390    let reason = if host.is_some_and(|host| host.stalled) {
391        "The host is short of memory: its programs stall waiting for it, so nothing starts"
392            .to_owned()
393    } else {
394        format!(
395            "The host is short of memory: needs {}; the host has {} to spare",
396            size(needs),
397            size(free)
398        )
399    };
400    match host {
401        Some(host) => format!("{reason}; {}", host.memory.outside_line()),
402        None => reason,
403    }
404}
405
406/// Hundredths of a percent as a percentage: `1.5%`, `12%`.
407pub fn percent(hundredths: u32) -> String {
408    let whole = hundredths / 100;
409    match hundredths % 100 / 10 {
410        0 => format!("{whole}%"),
411        tenth => format!("{whole}.{tenth}%"),
412    }
413}
414
415/// The CPU budget runners share, in millicores.
416#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
417pub struct CpuBudget {
418    /// The CPUs the slice may use: its `AllowedCPUs` or the host's, less under a lower `CPUQuota`.
419    pub cpus: u64,
420    /// Those times `cpu_overcommit`: what the runners' reservations must fit.
421    pub budget: u64,
422    /// What the runners reserve: each its predicted average CPU under measured admission, else its `cpus`.
423    pub in_use: u64,
424    /// Whether a queued job waits for CPU that memory and a slot have room for.
425    pub held: bool,
426}
427
428impl CpuBudget {
429    /// The budget's line as clients show it beside memory, such as `CPU 4.5 of 32 CPUs reserved` or, while a job
430    /// waits for it, `CPU 30 of 32 CPUs reserved; a job waits for CPU`.
431    pub fn line(&self) -> String {
432        let mut line = format!(
433            "CPU {} of {} CPUs reserved",
434            cores(self.in_use),
435            cores(self.budget)
436        );
437        if self.held {
438            line.push_str("; a job waits for CPU");
439        }
440        line
441    }
442}
443
444impl Budget {
445    /// How runners are admitted, as clients add it to the budget's line: nothing under caps, else `by predicted
446    /// peaks`, and why nothing starts while the slice is at the high-water mark.
447    pub fn admission_note(&self) -> Option<&'static str> {
448        match (self.admission, self.held) {
449            (AdmissionPolicy::Caps, _) => None,
450            (AdmissionPolicy::Measured, false) => Some("by predicted peaks"),
451            (AdmissionPolicy::Measured, true) => Some(
452                "by predicted peaks; the slice is past 90% of its MemoryMax, so no runner starts",
453            ),
454        }
455    }
456}
457
458/// A shell container's memory cap: its record's profile's limit when the shell opened.
459#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
460pub struct ShellMemory {
461    /// The job whose record the shell runs.
462    pub job: u64,
463    /// Its cap in bytes.
464    pub memory: u64,
465}
466
467/// A seed container's memory cap: its profile's limit when the reseed started, or, for a requested reseed whose
468/// profile drained, the room it holds until it starts.
469#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
470pub struct SeedMemory {
471    /// The profile it reseeds.
472    pub profile: String,
473    /// Its cap in bytes.
474    pub memory: u64,
475}
476
477/// A runner profile and what runs in its slots.
478#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
479pub struct ProfileStatus {
480    /// The name under `[profiles]` in `runnerd.toml`.
481    pub name: String,
482    /// The image its runners run, such as `runnerd-runner:base`.
483    pub image: String,
484    /// CPUs per slot.
485    pub cpus: u32,
486    /// Bytes per slot.
487    pub memory: u64,
488    /// Set while slot 1's layers become the profile's snapshot.
489    pub reseeding: bool,
490    /// Index 0 is slot 1.
491    pub slots: Vec<SlotStatus>,
492}
493
494/// One slot of a profile: room for one job.
495#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
496pub struct SlotStatus {
497    /// 1-based.
498    pub slot: usize,
499    /// `None` when the slot is free.
500    pub runner: Option<RunnerStatus>,
501}
502
503/// A runner registered for one job, in its container.
504#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
505pub struct RunnerStatus {
506    /// `owner/name` the runner is registered on.
507    pub repository: String,
508    /// The runner's name, also its container's.
509    pub name: String,
510    /// The runner's ID on GitHub.
511    pub runner_id: u64,
512    /// The Docker container ID.
513    pub container: String,
514    /// Whether it runs a job, as GitHub or its log reports it: its log names the job before GitHub lists it busy.
515    pub busy: bool,
516    /// Seconds since the Unix epoch.
517    pub started_at: u64,
518    /// What it takes of the budget: its cap under caps; under measured admission the larger of its predicted peak
519    /// and its last sampled memory.
520    pub reserved: u64,
521    /// A warm runner: idle, and no queued job of its repository waits for it; it takes the next one GitHub hands
522    /// out.
523    pub warm: bool,
524}
525
526/// A configured repository and its queue.
527#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
528pub struct RepositoryStatus {
529    /// `owner/name` on GitHub.
530    pub name: String,
531    /// Its pools in config order, one per `[[repositories]]` entry: a job runs in the one whose labels match it
532    /// (ADR 0058).
533    pub pools: Vec<PoolStatus>,
534    /// Paused repositories get no new runners; their running jobs finish.
535    pub paused: bool,
536    /// Its jobs in `Status::queued`: queued ones none of its runners took yet, those no pool serves too.
537    pub queued_jobs: usize,
538    /// Why its queued jobs cannot be listed, while the listings fail (ADR 0132); absent while they answer, before the
539    /// first, while GitHub's rate limit stops them, and from a daemon before 0.2.
540    #[serde(default, skip_serializing_if = "Option::is_none")]
541    pub listing: Option<ListingFailure>,
542    /// Whether `Status::queued` holds its queued jobs as GitHub listed them at the last tick; `Unknown` from a daemon
543    /// that predates it, which did not say, so a client never reads it as listed (ADR 0150).
544    #[serde(default)]
545    pub queue: QueueShown,
546    /// Why runnerd re-runs none of its runner faults, once GitHub refused one of its automatic re-runs in a way asking
547    /// again cannot change (ADR 0153); absent otherwise, and from a daemon that predates it.
548    #[serde(default, skip_serializing_if = "Option::is_none")]
549    pub rerun_refused: Option<RerunRefused>,
550}
551
552/// Whether a status shows a repository's queued jobs, or none because they could not be listed (ADR 0150).
553#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
554#[serde(rename_all = "kebab-case")]
555pub enum QueueShown {
556    /// Its last listing answered, so its jobs in `Status::queued` are those GitHub had queued then, possibly none.
557    Listed,
558    /// No listing has answered since the daemon started, the last one failed or the rate limit stopped it, or the
559    /// daemon stops: `Status::queued` leaves its jobs out, whether any are queued or not.
560    Unlisted,
561    /// A daemon that predates this, or a state from a newer daemon than this client knows: nothing is said.
562    #[default]
563    #[serde(other)]
564    Unknown,
565}
566
567/// Why runnerd cannot list a repository's queued jobs (ADR 0132): what class of failure GitHub's answer was, never its
568/// text. The engine keeps it until a listing answers or a reload removes the repository; a restart forgets it.
569#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
570pub struct ListingFailure {
571    /// When the listings began to fail, in seconds since the Unix epoch.
572    pub since: u64,
573    /// Why the last one failed.
574    pub problem: ListingProblem,
575}
576
577/// What a failed listing ran into.
578#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
579#[serde(rename_all = "kebab-case", tag = "kind")]
580pub enum ListingProblem {
581    /// runnerd could read no GitHub token.
582    NoToken,
583    /// GitHub refused the token: 401.
584    Unauthorized,
585    /// GitHub answered 403, 404 or 410: the token may not read the repository's Actions, cannot see it, or it is gone.
586    Refused {
587        /// The HTTP status.
588        status: u16,
589    },
590    /// GitHub answered another error status, such as a 5xx.
591    Failed {
592        /// The HTTP status.
593        status: u16,
594    },
595    /// No answer came: the network, DNS or TLS failed.
596    Unreachable,
597    /// The answer was not what GitHub sends.
598    Unexpected,
599    /// A problem from a newer daemon than this client knows.
600    #[serde(other)]
601    Unknown,
602}
603
604impl ListingProblem {
605    /// Whether it is the token's, and so every repository's: none read, or GitHub refused it.
606    pub fn is_token(&self) -> bool {
607        matches!(self, ListingProblem::NoToken | ListingProblem::Unauthorized)
608    }
609}
610
611impl ListingFailure {
612    /// What fails, as every client says it: `Cannot list halyard/ledger's queued jobs: GitHub answers 404; the token
613    /// cannot see the repository, or it is gone`.
614    pub fn line(&self, repository: &str) -> String {
615        format!(
616            "Cannot list {repository}'s queued jobs: {}",
617            self.problem.why()
618        )
619    }
620}
621
622impl ListingProblem {
623    /// Why the listing fails, as the daemon's log and every client say it: `GitHub answers 502`. Never GitHub's text.
624    pub fn why(&self) -> String {
625        match self {
626            ListingProblem::NoToken => "runnerd has no GitHub token".to_owned(),
627            ListingProblem::Unauthorized => "GitHub refuses runnerd's token (401)".to_owned(),
628            ListingProblem::Refused { status: 403 } => {
629                "GitHub answers 403; the token may not read the repository's Actions".to_owned()
630            }
631            ListingProblem::Refused { status } => format!(
632                "GitHub answers {status}; the token cannot see the repository, or it is gone"
633            ),
634            ListingProblem::Failed { status } => format!("GitHub answers {status}"),
635            ListingProblem::Unreachable => "GitHub does not answer".to_owned(),
636            ListingProblem::Unexpected => "GitHub's answer is not what runnerd reads".to_owned(),
637            ListingProblem::Unknown => "for a reason this client does not know".to_owned(),
638        }
639    }
640}
641
642/// One of a repository's pools: its runners in one profile.
643#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
644pub struct PoolStatus {
645    /// The profile its jobs run in.
646    pub profile: String,
647    /// The labels its runners register with.
648    pub labels: Vec<String>,
649    /// Its jobs in `Status::queued`: those its labels match.
650    pub queued_jobs: usize,
651}
652
653/// A queued job runners of this daemon can take, as GitHub listed it at the last poll.
654#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
655pub struct QueuedJob {
656    /// GitHub's job ID.
657    pub id: u64,
658    /// The repository whose runners can take it, `owner/name`.
659    pub repository: String,
660    /// The profile of its repository's pool whose labels match it; `None` when no pool's do.
661    #[serde(default, skip_serializing_if = "Option::is_none")]
662    pub profile: Option<String>,
663    /// The workflow run it belongs to.
664    pub run_id: u64,
665    /// 1 for the first attempt of the run, higher for re-runs.
666    pub run_attempt: u32,
667    /// The workflow's name.
668    pub workflow: Option<String>,
669    /// The job's name in the workflow.
670    pub name: String,
671    /// The branch the run is for.
672    pub branch: Option<String>,
673    /// The job's page on GitHub.
674    pub url: Option<String>,
675    /// When GitHub queued it, in seconds since the Unix epoch; 0 if GitHub did not say.
676    pub queued_at: u64,
677    /// Why no runner has it yet, as the last plan saw it. `None` before the daemon has planned with it, and while
678    /// it shuts down.
679    #[serde(default, skip_serializing_if = "Option::is_none")]
680    pub waiting: Option<Waiting>,
681}
682
683/// The slot of an idle runner of `job`'s repository, in its pool's profile when known, such as `jvm 2`.
684fn starting_for(job: &QueuedJob, status: &Status) -> Option<String> {
685    status
686        .profiles
687        .iter()
688        .filter(|profile| job.profile.as_ref().is_none_or(|own| *own == profile.name))
689        .find_map(|profile| {
690            profile
691                .slots
692                .iter()
693                .find(|slot| {
694                    slot.runner
695                        .as_ref()
696                        .is_some_and(|runner| runner.repository == job.repository && !runner.busy)
697                })
698                .map(|slot| format!("{}\u{a0}{}", profile.name, slot.slot))
699        })
700}
701
702impl QueuedJob {
703    /// Where it runs, as every client names it: its repository, and its pool's profile when the repository has
704    /// several pools in `status`, such as `halyard/ledger · light`.
705    pub fn place(&self, status: &Status) -> String {
706        let pools = status
707            .repositories
708            .iter()
709            .find(|repository| repository.name == self.repository)
710            .map_or(0, |repository| repository.pools.len());
711        match self.profile.as_deref().filter(|_| pools > 1) {
712            Some(profile) => format!("{}\u{a0}· {profile}", self.repository),
713            None => self.repository.clone(),
714        }
715    }
716}
717
718impl RepositoryStatus {
719    /// The profile of its first pool, which every client colours it by.
720    pub fn first_profile(&self) -> &str {
721        self.pools.first().map_or("", |pool| pool.profile.as_str())
722    }
723
724    /// Its pools' profiles, as every client lists them on one line: `jvm` or `jvm + light`.
725    pub fn profiles(&self) -> String {
726        self.pools
727            .iter()
728            .map(|pool| pool.profile.as_str())
729            .collect::<Vec<_>>()
730            .join(" + ")
731    }
732
733    /// The profile of its pool whose labels match a job asking for `labels`, as the daemon picks it.
734    pub fn pool_for(&self, labels: &[String]) -> Option<String> {
735        self.pools
736            .iter()
737            .find(|pool| crate::config::labels_match(labels, &pool.labels))
738            .map(|pool| pool.profile.clone())
739    }
740}
741
742/// What failed, that holds a repository's runners back for a while.
743#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
744#[serde(rename_all = "kebab-case")]
745pub enum HoldCause {
746    /// Its runners ended without connecting, so without taking a job (ADR 0104).
747    NoJob,
748    /// Its runners connected and ended without a job, one after the other.
749    IdleExits,
750    /// GitHub did not register its runner.
751    Register,
752    /// Docker did not start its runner's container.
753    Start,
754}
755
756/// Why a queued job has no runner of its own yet. Jobs are served oldest first; each takes the first of these that
757/// holds for it.
758#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
759#[serde(rename_all = "kebab-case", tag = "kind")]
760pub enum Waiting {
761    /// Its repository is paused.
762    Paused,
763    /// Runners of its repository failed, so none starts before `until` (seconds since the Unix epoch).
764    Backoff {
765        /// When runners may start again.
766        until: u64,
767        /// What failed.
768        cause: HoldCause,
769    },
770    /// A runner started for it and waits for GitHub to hand it the job: a runner takes any job its labels match,
771    /// so not necessarily this one.
772    RunnerStarting,
773    /// Slot 1 of its profile is becoming the profile's snapshot, so none of the profile's slots starts.
774    Reseeding {
775        /// The profile.
776        profile: String,
777    },
778    /// Its profile's image is being pulled, so none of the profile's slots starts.
779    PullingImage {
780        /// The profile.
781        profile: String,
782    },
783    /// Every slot of its profile holds a runner.
784    NoSlot {
785        /// The profile.
786        profile: String,
787    },
788    /// What its runner would reserve does not fit the memory budget left. Under measured admission, `free` is 0
789    /// while the slice is at the high-water mark (`Budget::held`).
790    Memory {
791        /// What its runner would reserve, in bytes.
792        needs: u64,
793        /// What the budget has left, in bytes.
794        free: u64,
795    },
796    /// What its runner would reserve does not fit what the host's memory has to spare beside its other programs
797    /// (`HostBudget::spare`), though it fits the slice's budget. `free` is 0 while the host's tasks stall for memory
798    /// (`HostBudget::stalled`).
799    HostMemory {
800        /// What its runner would reserve, in bytes.
801        needs: u64,
802        /// What the host has to spare, in bytes.
803        free: u64,
804    },
805    /// What its runner would reserve does not fit the CPU budget left, in millicores.
806    Cpu {
807        /// What its runner would reserve.
808        needs: u64,
809        /// What the CPU budget has left.
810        free: u64,
811    },
812    /// An older job has waited long enough for CPU that no younger one takes CPU before it.
813    BehindCpu {
814        /// The older job's ID.
815        job: u64,
816    },
817    /// An older job has waited long enough for memory that no younger one starts before it (ADR 0096).
818    BehindMemory {
819        /// The older job's ID.
820        job: u64,
821    },
822    /// An older job is about to have a runner start for it, which takes the slot, memory or CPU this one would
823    /// otherwise start with: what holds it is that start, not what runs now.
824    BehindStart {
825        /// The older job's ID.
826        job: u64,
827    },
828    /// No pool of its repository has every label it asks for, so no runner of this daemon can take it (ADR 0058).
829    NoPool {
830        /// The labels it asks for.
831        labels: Vec<String>,
832    },
833    /// A host crash may have torn what runners wrote without syncing, and the daemon has not emptied it yet, so no
834    /// runner starts (ADR 0141, 0142).
835    Torn {
836        /// The volumes a container keeps it from removing, as of its last try: the owner's to remove once nothing
837        /// mounts them. Empty while it has not tried, or Docker failed.
838        volumes: Vec<String>,
839    },
840    /// A reason from a newer daemon than this client knows, so a reason added later does not keep the client from
841    /// reading the status.
842    #[serde(other)]
843    Unknown,
844}
845
846/// What a [`Waiting`] reason waits on, which clients draw it by.
847#[derive(Debug, Clone, Copy, PartialEq, Eq)]
848pub enum WaitKind {
849    /// Something the owner can act on: a pause, runners that failed to take a job, or labels no pool serves.
850    Act,
851    /// Something that clears by itself shortly: a runner starting, a reseed, an image pull, an older job's start.
852    Soon,
853    /// Room: a slot, memory or CPU that a running job holds.
854    Full,
855    /// A reason this client does not know (`Waiting::Unknown`), drawn neutral.
856    Other,
857}
858
859impl Waiting {
860    /// Whether runnerd cannot start the job with the config it runs with: its repository is paused, or no pool serves
861    /// its labels. Not that nothing ever will: a resume or a config change can, and another machine's runner may take
862    /// it. A backoff ends by itself, and a reason this client does not know says nothing (ADR 0132).
863    pub fn cannot_start(&self) -> bool {
864        matches!(self, Waiting::Paused | Waiting::NoPool { .. })
865    }
866
867    /// What it waits on.
868    pub fn kind(&self) -> WaitKind {
869        match self {
870            Waiting::Paused | Waiting::Backoff { .. } | Waiting::NoPool { .. } => WaitKind::Act,
871            Waiting::Torn { volumes } if !volumes.is_empty() => WaitKind::Act,
872            Waiting::Unknown => WaitKind::Other,
873            Waiting::Torn { .. }
874            | Waiting::RunnerStarting
875            | Waiting::Reseeding { .. }
876            | Waiting::PullingImage { .. }
877            | Waiting::BehindStart { .. } => WaitKind::Soon,
878            Waiting::NoSlot { .. }
879            | Waiting::Memory { .. }
880            | Waiting::HostMemory { .. }
881            | Waiting::Cpu { .. }
882            | Waiting::BehindCpu { .. }
883            | Waiting::BehindMemory { .. } => WaitKind::Full,
884        }
885    }
886
887    /// Why `job` waits, in the owner's words with the numbers that hold it, as every client says it: such as
888    /// `All 2 node slots are busy` or `Needs 9G of memory; 2.5G of the budget is free`. `status` is the one `job`
889    /// is queued in, which names the slot of a starting runner and the older job one waits behind.
890    pub fn reason(&self, job: &QueuedJob, status: &Status, now: u64) -> String {
891        let size = |bytes: u64| crate::config::ByteSize(bytes).to_string();
892        let older_name = |id: u64| {
893            status
894                .queued
895                .iter()
896                .find(|candidate| candidate.id == id)
897                .map_or_else(|| "an older job".to_owned(), |older| older.name.clone())
898        };
899        match self {
900            Waiting::Paused => format!("{} is paused", job.repository),
901            Waiting::Unknown => "Waits for a reason this client does not know yet".to_owned(),
902            Waiting::NoPool { labels } if labels.is_empty() => {
903                "It asks for no labels, so no profile serves it".to_owned()
904            }
905            Waiting::NoPool { labels } => format!(
906                "No profile serves the {} {}",
907                if labels.len() == 1 { "label" } else { "labels" },
908                labels.join(", ")
909            ),
910            Waiting::Backoff { until, cause } => format!(
911                "{}; retrying in {}",
912                match cause {
913                    HoldCause::NoJob => "Runners failed to take a job",
914                    HoldCause::IdleExits => "Runners ended without a job after waiting for one",
915                    HoldCause::Register => "Runners cannot register with GitHub",
916                    HoldCause::Start => "Runners cannot start",
917                },
918                duration(until.saturating_sub(now))
919            ),
920            Waiting::RunnerStarting => match starting_for(job, status) {
921                Some(slot) => format!("A runner is starting for it in {slot}"),
922                None => "A runner is starting for it".to_owned(),
923            },
924            Waiting::Reseeding { profile } => format!("{profile} is rebuilding its snapshot"),
925            Waiting::Torn { volumes } if volumes.is_empty() => {
926                "Emptying the caches a host crash may have torn".to_owned()
927            }
928            Waiting::Torn { volumes } => format!(
929                "A host crash may have torn caches a container holds; once nothing mounts them: docker volume rm {}",
930                volumes.join(" ")
931            ),
932            Waiting::PullingImage { profile } => format!("Pulling {profile}'s image"),
933            Waiting::NoSlot { profile } => {
934                let slots = status
935                    .profiles
936                    .iter()
937                    .find(|candidate| &candidate.name == profile)
938                    .map_or(0, |profile| profile.slots.len());
939                if slots == 1 {
940                    format!("The {profile} slot is busy")
941                } else {
942                    format!("All {slots} {profile} slots are busy")
943                }
944            }
945            Waiting::Memory { .. } if status.budget.held => {
946                "The slice is past 90% of its MemoryMax, so nothing starts".to_owned()
947            }
948            Waiting::Memory { needs, free } => format!(
949                "Needs {} of memory; {} of the budget is free",
950                size(*needs),
951                size(*free)
952            ),
953            Waiting::HostMemory { needs, free } => host_reason(
954                *needs,
955                *free,
956                status.budget.host.as_ref(),
957                status.budget.memory_in_use,
958            ),
959            Waiting::Cpu { needs, free } => {
960                format!(
961                    "Needs {}; {} are free",
962                    cpus(*needs),
963                    admission::free_cores(*free)
964                )
965            }
966            Waiting::BehindCpu { job: older } => {
967                format!("Behind {}, which waits for CPU", older_name(*older))
968            }
969            Waiting::BehindMemory { job: older } => {
970                format!("Behind {}, which waits for memory", older_name(*older))
971            }
972            Waiting::BehindStart { job: older } => {
973                format!(
974                    "Next after {}, whose runner starts first",
975                    older_name(*older)
976                )
977            }
978        }
979    }
980}
981
982/// `GET /v1/dashboard`: the dashboard's `[web]` settings, as the daemon read them when it started.
983#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
984pub struct Dashboard {
985    /// `[web] open`: the one of `[web] origins` that `runnerctl web` opens the dashboard on; the loopback address
986    /// when none.
987    #[serde(default, skip_serializing_if = "Option::is_none")]
988    pub open: Option<String>,
989}
990
991/// `POST /v1/dashboard/pairings`: which of `[web] origins` to make a link for.
992#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
993pub struct PairingQuery {
994    /// One of `[web] origins`; each of them when none.
995    #[serde(default, skip_serializing_if = "Option::is_none")]
996    pub origin: Option<String>,
997}
998
999/// `POST /v1/dashboard/pairings`: fresh one-time links that sign a device in to the dashboard.
1000#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
1001pub struct Pairings {
1002    /// One per origin asked for.
1003    pub links: Vec<Pairing>,
1004}
1005
1006/// A link that signs one device in to the dashboard on `origin`, and nowhere else, within `lifetime`.
1007#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
1008pub struct Pairing {
1009    /// One of `[web] origins`.
1010    pub origin: String,
1011    /// The link with its one-time code: a credential, which `Debug` leaves out.
1012    pub url: String,
1013    /// Seconds it works for from when it was made.
1014    pub lifetime: u64,
1015}
1016
1017impl std::fmt::Debug for Pairing {
1018    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1019        formatter
1020            .debug_struct("Pairing")
1021            .field("origin", &self.origin)
1022            .field("lifetime", &self.lifetime)
1023            .finish_non_exhaustive()
1024    }
1025}
1026
1027/// `POST /v1/shutdown`.
1028#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
1029pub struct ShutdownRequest {
1030    /// Kill running jobs and delete their runners instead of waiting for them.
1031    #[serde(default)]
1032    pub force: bool,
1033}
1034
1035/// What `POST /v1/shutdown` answers: how the daemon stops now, which a stop asked for earlier may have made more
1036/// urgent than the request.
1037#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
1038pub struct ShutdownAnswer {
1039    /// How it stops.
1040    pub stopping: Stopping,
1041}
1042
1043/// How a stopping daemon treats running jobs (ADR 0091).
1044#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
1045#[serde(rename_all = "kebab-case")]
1046pub enum Stopping {
1047    /// `runnerd stop`: it waits for running jobs, then removes every runner.
1048    WaitsForJobs,
1049    /// A signal: it removes idle runners and leaves running jobs to the next start.
1050    LeavesJobs,
1051    /// `runnerd stop --force` or a second signal: it kills running jobs.
1052    KillsJobs,
1053    /// A kind of stop from a newer daemon than this client knows, so one added later does not keep the client from
1054    /// reading the status.
1055    #[serde(other)]
1056    Unknown,
1057}
1058
1059impl Stopping {
1060    /// What it does, as every client says it: `shutting down: waits for running jobs`.
1061    pub fn line(self) -> &'static str {
1062        match self {
1063            Stopping::WaitsForJobs => "shutting down: waits for running jobs",
1064            Stopping::LeavesJobs => "shutting down: leaves running jobs to the next start",
1065            Stopping::KillsJobs => "shutting down: kills running jobs",
1066            Stopping::Unknown => "shutting down",
1067        }
1068    }
1069}
1070
1071impl Status {
1072    /// What a stopping daemon does, as every client says it ([`Stopping::line`]); `shutting down` from a daemon
1073    /// that does not say how; `None` while it runs.
1074    pub fn stopping_line(&self) -> Option<&'static str> {
1075        match (self.stopping, self.shutting_down) {
1076            (Some(stopping), _) => Some(stopping.line()),
1077            (None, true) => Some("shutting down"),
1078            (None, false) => None,
1079        }
1080    }
1081
1082    /// Why no runner starts while GitHub's rate limit is used up, as every client says it; `None` while it is not.
1083    pub fn github_line(&self) -> Option<&'static str> {
1084        self.github_limited_until
1085            .map(|_| "GitHub's rate limit is used up: no runner starts until it resets")
1086    }
1087}
1088
1089/// The body of every error response.
1090#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1091pub struct ErrorResponse {
1092    /// What went wrong, for people to read.
1093    pub message: String,
1094}