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}