Skip to main content

runnerd_core/
config.rs

1//! `runnerd.toml`: the repositories to serve, the runner profiles they use, the shared caches and the host
2//! budget they must fit in. Builds without the `host` feature, so clients can read a config; its only I/O is
3//! reading the file and asking `systemctl` for a slice's `MemoryMax`. It never talks to Docker or GitHub.
4
5use std::collections::BTreeMap;
6use std::fmt;
7use std::net::{Ipv4Addr, Ipv6Addr};
8use std::path::{Path, PathBuf};
9use std::process::Command;
10use std::str::FromStr;
11use std::time::Duration;
12
13use serde::{Deserialize, Deserializer, de};
14
15use crate::api;
16
17mod budget;
18
19pub use budget::{BudgetBlock, CheckBudget, Remainder, Verdict};
20
21/// A parsed `runnerd.toml`. `validate` checks it against the host's budget.
22#[derive(Debug, Deserialize)]
23#[serde(deny_unknown_fields)]
24pub struct Config {
25    /// The host's budget and isolation.
26    pub host: Host,
27    /// The caches runners share.
28    pub caches: Caches,
29    /// Runner profiles by name.
30    pub profiles: BTreeMap<String, Profile>,
31    /// The repositories to serve, one pool per entry: a repository named by several entries is served by each of
32    /// their profiles, a job by the one whose labels match it (ADR 0058).
33    pub repositories: Vec<Repository>,
34    /// What is kept of past jobs.
35    #[serde(default)]
36    pub history: History,
37    /// How much the records of failed jobs may keep.
38    #[serde(default)]
39    pub records: Records,
40    /// How sizing advice reads the job history.
41    #[serde(default)]
42    pub sizing: Sizing,
43    /// Who may use the dashboard through another address.
44    #[serde(default)]
45    pub web: Web,
46    /// Where the daemon sends notifications; none by default.
47    #[serde(default)]
48    pub notify: Notify,
49    /// What runnerd may ask of GitHub on the owner's behalf.
50    #[serde(default)]
51    pub github: Github,
52}
53
54/// `[host]`: where runner containers run and how they are isolated.
55#[derive(Debug, Deserialize)]
56#[serde(deny_unknown_fields)]
57pub struct Host {
58    /// The systemd slice every runner container is placed in; its `MemoryMax` is the budget.
59    pub slice: String,
60    /// How runner containers are kept from the host.
61    pub isolation: Isolation,
62    /// Must be set for `isolation = "unsafe-dind"`, so a copied config cannot turn it on silently.
63    #[serde(default)]
64    pub allow_unsafe: bool,
65    /// How often GitHub is asked for queued jobs.
66    #[serde(default = "default_poll_interval", deserialize_with = "duration")]
67    pub poll_interval: Duration,
68    /// What a runner must fit in before it starts. Default `measured` (ADR 0138).
69    #[serde(default)]
70    pub admission: Admission,
71    /// Set, a runner also starts only when its predicted CPU fits the slice's CPUs times this; absent, CPU is not
72    /// admitted.
73    #[serde(default)]
74    pub cpu_overcommit: Option<f64>,
75    /// Set, the most memory the host can grow to, for a VM whose hypervisor adds memory as the guest asks for it:
76    /// admission counts what it can still grow by past `MemTotal` as available, and keeps the margin of this
77    /// (ADR 0084). Absent, or not above `MemTotal`, the host is the memory it has now.
78    #[serde(default)]
79    pub memory_ceiling: Option<ByteSize>,
80    /// Under measured admission, whether `MemoryMax` and the host's limit count what runs uses and keep room for its
81    /// growth (ADR 0099, 0108, 0130) rather than every runner's worst case. Default on; off, both add every runner's
82    /// take, the way back if a host meets what the count did not foresee.
83    #[serde(default = "default_on")]
84    pub pooled_count: bool,
85    /// Whether runners whose image carries `runnerd-skip-syncs` are asked to answer `fsync` and the other sync calls
86    /// without syncing (ADR 0141). Default on: what a runner writes is a cache or goes with its container, and a host
87    /// crash empties those caches. A runner of an image without it keeps its syncs whatever this says. A reload
88    /// applies it from the next runner on.
89    #[serde(default = "default_on")]
90    pub skip_syncs: bool,
91}
92
93/// Whether a profile's image answers its runner's sync calls without syncing, as doctor reads it.
94#[derive(Debug, Clone, Copy, PartialEq, Eq)]
95pub enum ImageSyncs {
96    /// It carries `runnerd-skip-syncs` and mounts its layers `volatile` under it, as its labels say: runnerd asks its
97    /// runners to skip their sync calls, and unmounting their layers syncs nothing (ADR 0142).
98    Skips,
99    /// It carries `runnerd-skip-syncs` and lacks volatile layers, as the 0.1.2 images: runnerd asks its runners to
100    /// skip their sync calls, and their layers sync when unmounted.
101    SkipsCalls,
102    /// It lacks it, as runner images before it do: runnerd never asks its runners, and they sync.
103    Syncs,
104    /// Docker does not have it, or did not answer: each runner's start reads it.
105    Unread,
106}
107
108/// Whether the systemd journal tells runnerd how a past boot ended (`boots::past_boots`).
109#[derive(Debug, Clone, Copy, PartialEq, Eq)]
110pub enum PastBoots {
111    /// It keeps past boots and runnerd's user reads `systemd`'s lines.
112    Read,
113    /// It keeps no boot before this one: it lives in memory, was vacuumed below one boot, or the host booted once.
114    NotKept,
115    /// runnerd's user reads none of `systemd`'s lines.
116    Unreadable,
117}
118
119impl Host {
120    /// Doctor's word on whether runners sync what they write, from what each profile's image carries (`images`, by
121    /// reference) and whether the journal shows how past boots ended (`boots`). For information, unless a crash guard
122    /// that cannot read the journal empties the caches after every boot.
123    pub fn syncs_check(
124        &self,
125        images: &BTreeMap<String, ImageSyncs>,
126        boots: PastBoots,
127    ) -> api::Check {
128        let check = |status, detail: String, fix: Option<&str>| api::Check {
129            name: "runner syncs".to_owned(),
130            status,
131            detail,
132            fix: fix.map(str::to_owned),
133        };
134        if !self.skip_syncs {
135            return check(
136                api::CheckStatus::Info,
137                "kept, as [host] skip_syncs = false sets".to_owned(),
138                None,
139            );
140        }
141        let of = |wanted: ImageSyncs| -> Vec<&str> {
142            images
143                .iter()
144                .filter(|(_, syncs)| **syncs == wanted)
145                .map(|(image, _)| image.as_str())
146                .collect()
147        };
148        // What each kind of image's runners do, worded around the images' references.
149        let words = [
150            (
151                ImageSyncs::Skips,
152                "skipped by the runners of ",
153                ", which carry runnerd-skip-syncs and mount their layers volatile",
154            ),
155            (
156                ImageSyncs::SkipsCalls,
157                "skipped in sync calls only by the runners of ",
158                ": they carry runnerd-skip-syncs, and their layers sync when unmounted",
159            ),
160            (
161                ImageSyncs::Syncs,
162                "kept by the runners of ",
163                ": they lack runnerd-skip-syncs, so runnerd never asks them",
164            ),
165            (
166                ImageSyncs::Unread,
167                "decided at each runner's start for ",
168                ", which Docker does not have yet",
169            ),
170        ];
171        let mut parts: Vec<String> = words
172            .iter()
173            .filter_map(|(kind, before, after)| {
174                let list = of(*kind);
175                (!list.is_empty()).then(|| format!("{before}{}{after}", list.join(", ")))
176            })
177            .collect();
178        if parts.is_empty() {
179            parts.push(
180                "decided at each runner's start, from its image's runnerd.skip-syncs label"
181                    .to_owned(),
182            );
183        }
184        let runners = parts.join("; ");
185        let arms = |kind: &ImageSyncs| *kind != ImageSyncs::Syncs;
186        if !images.is_empty() && !images.values().any(arms) {
187            return check(
188                api::CheckStatus::Info,
189                format!("{runners}. Nothing is emptied after a crash"),
190                None,
191            );
192        }
193        let crash = "a crash or power loss while such a runner ran empties the slots' volumes and the pnpm and Maven \
194                     stores before any runner starts";
195        match boots {
196            PastBoots::Read => check(
197                api::CheckStatus::Info,
198                format!(
199                    "{runners}. After {crash}; an orderly shutdown or reboot keeps them, as the journal shows its \
200                     final sync"
201                ),
202                None,
203            ),
204            PastBoots::NotKept => check(
205                api::CheckStatus::Warn,
206                format!(
207                    "{runners}. This host's journal keeps no past boot, so runnerd cannot tell an orderly shutdown \
208                     from a crash: every boot after such a runner ran empties the slots' volumes and the pnpm and \
209                     Maven stores before any runner starts"
210                ),
211                Some(
212                    "keep the journal across boots: set Storage=persistent in /etc/systemd/journald.conf, then \
213                     sudo systemctl restart systemd-journald; or set [host] skip_syncs = false",
214                ),
215            ),
216            PastBoots::Unreadable => check(
217                api::CheckStatus::Warn,
218                format!(
219                    "{runners}. runnerd's user cannot read the system journal, so runnerd cannot tell an orderly \
220                     shutdown from a crash: every boot after such a runner ran empties the slots' volumes and the \
221                     pnpm and Maven stores before any runner starts"
222                ),
223                Some(
224                    "let runnerd's user read the journal: sudo usermod -aG systemd-journal \"$USER\", then log in \
225                     again; or set [host] skip_syncs = false",
226                ),
227            ),
228        }
229    }
230
231    /// Refuses a `cpu_overcommit` that is not above 0 and at most `MAX_CPU_OVERCOMMIT`.
232    fn check_cpu_overcommit(&self) -> Result<(), ConfigError> {
233        match self.cpu_overcommit {
234            Some(value) if !(value > 0.0 && value <= MAX_CPU_OVERCOMMIT) => {
235                Err(ConfigError::CpuOvercommit { value })
236            }
237            _ => Ok(()),
238        }
239    }
240}
241
242/// The largest `cpu_overcommit` the config check takes.
243pub const MAX_CPU_OVERCOMMIT: f64 = 16.0;
244
245/// `admission` under `[host]`: what a new runner must fit in the slice's `MemoryMax` beside the running ones.
246#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
247#[serde(rename_all = "kebab-case")]
248pub enum Admission {
249    /// Every runner's memory cap: `slots × memory` over all profiles, with the mirror, must fit `MemoryMax`. The
250    /// opt-out from measured admission.
251    Caps,
252    /// The default: every runner's predicted peak, from the job history; `slots` only bounds how many run at once,
253    /// and one runner of each profile with the mirror must fit `MemoryMax`. Nothing starts while the slice is at 90%
254    /// of it.
255    #[default]
256    Measured,
257}
258
259impl Admission {
260    /// The policy as the API names it.
261    pub fn policy(self) -> api::AdmissionPolicy {
262        match self {
263            Admission::Caps => api::AdmissionPolicy::Caps,
264            Admission::Measured => api::AdmissionPolicy::Measured,
265        }
266    }
267}
268
269fn default_on() -> bool {
270    true
271}
272
273fn default_poll_interval() -> Duration {
274    Duration::from_secs(15)
275}
276
277/// How runner containers are kept from the host: `isolation` under `[host]`.
278#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
279#[serde(rename_all = "kebab-case")]
280pub enum Isolation {
281    /// Sysbox: Docker inside an unprivileged container.
282    Sysbox,
283    /// Privileged Docker-in-Docker: a job can take over the host.
284    UnsafeDind,
285}
286
287/// `[caches]`: what runners share and keep between jobs.
288#[derive(Debug, Clone, Deserialize)]
289#[serde(deny_unknown_fields)]
290pub struct Caches {
291    /// The Docker Hub mirror.
292    pub mirror: Mirror,
293    /// The shared pnpm store.
294    pub pnpm: CacheLimit,
295    /// The shared Maven repository.
296    pub maven: CacheLimit,
297    /// When a profile has no job running and its slot 1 changed its layers by at least this much, slot 1's
298    /// layers become the profile's new snapshot.
299    #[serde(default = "default_reseed_at")]
300    pub reseed_at: ByteSize,
301    /// A reseed that would make a profile's snapshot larger than this starts it over from slot 1's changes alone,
302    /// or from the image when those are larger too.
303    #[serde(default = "default_snapshot_max")]
304    pub snapshot_max: ByteSize,
305    /// The build cache every runner shares.
306    #[serde(default)]
307    pub build: BuildCache,
308}
309
310/// `[caches.build]`: the build cache every runner shares (ADR 0052): Gradle's, and the other tools' the runner image
311/// points at it. Every field has a default.
312#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
313#[serde(deny_unknown_fields, default)]
314pub struct BuildCache {
315    /// Whether runners get it. Default true.
316    pub enabled: bool,
317    /// Above this size, the entries used least recently go when no job runs. Default 10G.
318    pub max_size: ByteSize,
319    /// The branches whose pushes, scheduled and manually started runs may write to it besides each repository's
320    /// default branch, which always may. Every other job only reads. Default empty.
321    pub branches: Vec<String>,
322    /// Where its entries are kept; default `$XDG_CACHE_HOME/runnerd/build-cache`.
323    pub directory: Option<PathBuf>,
324    /// Whether it also serves GitHub Actions' cache, for `actions/cache`, the `setup-*` actions' caches and
325    /// BuildKit's `type=gha`, in place of GitHub's (ADR 0082). Default true.
326    pub actions_cache: bool,
327}
328
329impl BuildCache {
330    /// Doctor's word on where jobs' GitHub Actions cache is: for information, it fails nothing.
331    pub fn actions_cache_check(&self) -> api::Check {
332        api::Check {
333            name: api::ACTIONS_CACHE.to_owned(),
334            status: api::CheckStatus::Info,
335            detail: if self.enabled {
336                api::actions_cache_place(self.actions_cache)
337            } else {
338                "GitHub's, as the build cache is off"
339            }
340            .to_owned(),
341            fix: None,
342        }
343    }
344
345    fn validate(&self) -> Result<(), ConfigError> {
346        if self.enabled && self.max_size.0 == 0 {
347            return Err(ConfigError::ZeroLimit {
348                field: "caches.build.max_size".to_owned(),
349            });
350        }
351        Ok(())
352    }
353}
354
355impl Default for BuildCache {
356    fn default() -> BuildCache {
357        BuildCache {
358            enabled: true,
359            max_size: ByteSize(10 << 30),
360            branches: Vec::new(),
361            directory: None,
362            actions_cache: true,
363        }
364    }
365}
366
367fn default_reseed_at() -> ByteSize {
368    ByteSize(2 << 30)
369}
370
371/// Above the 8.7G a profile running Flutter and Android builds needs: its Flutter SDK, NDK and Gradle caches.
372fn default_snapshot_max() -> ByteSize {
373    ByteSize(10 << 30)
374}
375
376fn default_mirror_max_size() -> ByteSize {
377    ByteSize(10 << 30)
378}
379
380/// The Docker Hub pull-through mirror shared by all runners.
381#[derive(Debug, Clone, Deserialize)]
382#[serde(deny_unknown_fields)]
383pub struct Mirror {
384    /// Whether runners pull through the mirror.
385    pub enabled: bool,
386    /// The mirror container's memory limit.
387    pub memory: ByteSize,
388    /// The mirror container's CPUs.
389    pub cpus: u32,
390    /// How long content not pulled again is kept.
391    #[serde(deserialize_with = "duration")]
392    pub ttl: Duration,
393    /// Its storage is emptied above this size when no job runs.
394    #[serde(default = "default_mirror_max_size")]
395    pub max_size: ByteSize,
396}
397
398/// A size limit on a shared cache.
399#[derive(Debug, Clone, Deserialize)]
400#[serde(deny_unknown_fields)]
401pub struct CacheLimit {
402    /// The cache is emptied above this size when no job runs.
403    pub max_size: ByteSize,
404}
405
406/// Where runnerd's release workflow publishes the runner images, one tag per stage and version, such as
407/// `ghcr.io/ayagmar/runnerd-runner:jvm-0.1.4`.
408pub const PUBLISHED_RUNNER: &str = "ghcr.io/ayagmar/runnerd-runner";
409
410/// A runner image with its limits; every job of the profile gets one container with these limits.
411#[derive(Debug, Clone, Deserialize)]
412#[serde(try_from = "ProfileToml")]
413pub struct Profile {
414    /// The image its runners run: `image_stage` or `image`, exactly one of them.
415    pub image: Image,
416    /// CPUs per slot.
417    pub cpus: u32,
418    /// Memory per slot; the container's hard limit.
419    pub memory: ByteSize,
420    /// The most jobs of this profile running at once.
421    pub slots: u32,
422    /// Whether a failed job's runner is kept as a record, to open a shell in (`runnerctl shell`).
423    pub record_failures: bool,
424    /// The least `memory` auto sizing lowers it to; `None` for no bound.
425    pub min_memory: Option<ByteSize>,
426    /// The most `memory` auto sizing raises it to; `None` for what the slice's `MemoryMax` holds.
427    pub max_memory: Option<ByteSize>,
428    /// The most `slots` auto sizing raises them to; `None` for as many as the slice's `MemoryMax` holds.
429    pub max_slots: Option<u32>,
430    /// The GitHub-hosted runner its jobs are priced at (ADR 0072); `None` for the daemon's architecture's 2-core
431    /// standard runner.
432    pub priced_as: Option<api::Sku>,
433}
434
435/// The image a profile's runners run.
436#[derive(Debug, Clone, PartialEq, Eq)]
437pub enum Image {
438    /// `image_stage`: a stage of `image/Dockerfile` built on this host as `runnerd-runner:<stage>`.
439    Stage(String),
440    /// `image`: a reference runnerd pulls when Docker lacks it, such as
441    /// `ghcr.io/ayagmar/runnerd-runner:jvm-0.1.4`.
442    Pulled(String),
443}
444
445impl Image {
446    /// The reference Docker runs.
447    pub fn reference(&self) -> String {
448        match self {
449            Image::Stage(stage) => format!("runnerd-runner:{stage}"),
450            Image::Pulled(reference) => reference.clone(),
451        }
452    }
453}
454
455/// `[profiles.<name>]` as written, before `Profile` checks it names one image.
456#[derive(Deserialize)]
457#[serde(deny_unknown_fields)]
458struct ProfileToml {
459    image_stage: Option<String>,
460    image: Option<String>,
461    cpus: u32,
462    memory: ByteSize,
463    slots: u32,
464    #[serde(default)]
465    record_failures: bool,
466    min_memory: Option<ByteSize>,
467    max_memory: Option<ByteSize>,
468    max_slots: Option<u32>,
469    priced_as: Option<api::Sku>,
470}
471
472impl TryFrom<ProfileToml> for Profile {
473    type Error = String;
474
475    fn try_from(profile: ProfileToml) -> Result<Profile, String> {
476        let image = match (profile.image_stage, profile.image) {
477            (Some(stage), None) if !stage.is_empty() => Image::Stage(stage),
478            (None, Some(reference)) if !reference.is_empty() => Image::Pulled(reference),
479            (Some(_), Some(_)) => {
480                return Err(
481                    "set image_stage (a stage built from image/Dockerfile) or image (a reference to pull), \
482                     not both"
483                        .to_owned(),
484                );
485            }
486            _ => {
487                return Err(
488                    "set image_stage (a stage built from image/Dockerfile) or image (a reference to pull)"
489                        .to_owned(),
490                );
491            }
492        };
493        Ok(Profile {
494            image,
495            cpus: profile.cpus,
496            memory: profile.memory,
497            slots: profile.slots,
498            record_failures: profile.record_failures,
499            min_memory: profile.min_memory,
500            max_memory: profile.max_memory,
501            max_slots: profile.max_slots,
502            priced_as: profile.priced_as,
503        })
504    }
505}
506
507/// Whether a job asking for `wanted` may run on runners registered with `labels`: every label it asks for is one of
508/// theirs. GitHub compares labels without regard to case. A job asking for no label, as one that names only a runner
509/// group, matches no runners: nothing says which pool it is for (ADR 0058).
510pub fn labels_match(wanted: &[String], labels: &[String]) -> bool {
511    !wanted.is_empty()
512        && wanted.iter().all(|wanted| {
513            labels
514                .iter()
515                .any(|label| label.eq_ignore_ascii_case(wanted))
516        })
517}
518
519/// A repository to serve: `[[repositories]]`. Each entry is one of the repository's pools; entries with the same
520/// `name` serve it in several profiles, each with its own labels, which no two of them share (ADR 0058).
521#[derive(Debug, Deserialize)]
522#[serde(deny_unknown_fields)]
523pub struct Repository {
524    /// `owner/name` on GitHub.
525    pub name: String,
526    /// The profile the jobs this pool's labels match run in.
527    pub profile: String,
528    /// The labels its runners register with; a job runs on them when every label it asks for is one of these.
529    pub labels: Vec<String>,
530    /// How many idle runners it keeps registered for jobs not queued yet while it is active (ADR 0050, 0107); 0 turns
531    /// warm runners and bursts off. Default 1.
532    #[serde(default = "default_warm")]
533    pub warm: u32,
534    /// Whether its runners get the shared build cache, when `[caches.build]` is enabled. Default true.
535    #[serde(default = "default_true")]
536    pub build_cache: bool,
537    /// Whose runs may write to the shared build cache besides the branches' (ADR 0053), the same in every pool of
538    /// the repository. Default `"default-branch"`.
539    #[serde(default)]
540    pub build_cache_writers: BuildCacheWriters,
541}
542
543/// `build_cache_writers` of a `[[repositories]]`: whose jobs' uploads the shared build cache keeps (ADR 0053).
544#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
545#[serde(rename_all = "kebab-case")]
546pub enum BuildCacheWriters {
547    /// Pushes, scheduled and manually started runs of the default branch and of `[caches.build] branches`.
548    #[default]
549    DefaultBranch,
550    /// Those, and `pull_request` runs of the repository's own branches that people, not bots, opened and pushed.
551    PullRequests,
552}
553
554fn default_true() -> bool {
555    true
556}
557
558fn default_warm() -> u32 {
559    1
560}
561
562/// `[history]`: the job history database and how long it keeps what. Every field has a default.
563#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
564#[serde(deny_unknown_fields, default)]
565pub struct History {
566    /// The SQLite database; default `$XDG_STATE_HOME/runnerd/runnerd.db`.
567    pub database: Option<PathBuf>,
568    /// How long CPU and memory samples are kept; a job's totals and peaks stay. Default 7 days.
569    #[serde(deserialize_with = "duration")]
570    pub samples: Duration,
571    /// How long a finished job's log is kept. Default 30 days.
572    #[serde(deserialize_with = "duration")]
573    pub logs: Duration,
574    /// How long events are kept for clients resuming with `Last-Event-ID`. Default 30 days.
575    #[serde(deserialize_with = "duration")]
576    pub events: Duration,
577    /// How long a finished job's record is kept, with its steps, totals and runner. Default 90 days.
578    #[serde(deserialize_with = "duration")]
579    pub jobs: Duration,
580    /// The most log stored per job; later lines are dropped. Default 50M.
581    pub log_max: ByteSize,
582}
583
584impl Default for History {
585    fn default() -> History {
586        History {
587            database: None,
588            samples: Duration::from_hours(7 * 24),
589            logs: Duration::from_hours(30 * 24),
590            events: Duration::from_hours(30 * 24),
591            jobs: Duration::from_hours(90 * 24),
592            log_max: ByteSize(50 << 20),
593        }
594    }
595}
596
597/// `[records]`: how much the records of failed jobs may keep (`record_failures` under a profile turns them on).
598/// When a new record would pass a limit, the oldest records go first. Every field has a default.
599#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
600#[serde(deny_unknown_fields, default)]
601pub struct Records {
602    /// The most disk all records may take together. Default 20G.
603    pub max_total: ByteSize,
604    /// The most records kept. Default 10.
605    pub max_count: u32,
606    /// How long a record is kept. Default 7 days.
607    #[serde(deserialize_with = "duration")]
608    pub max_age: Duration,
609    /// The disk Docker must keep free: no record is made that would leave less. Default 10G.
610    pub min_free: ByteSize,
611}
612
613impl Default for Records {
614    fn default() -> Records {
615        Records {
616            max_total: ByteSize(20 << 30),
617            max_count: 10,
618            max_age: Duration::from_hours(7 * 24),
619            min_free: ByteSize(10 << 30),
620        }
621    }
622}
623
624/// `[sizing]`: how `runnerctl sizing` turns the job history's peaks into advice, and whether the daemon applies it
625/// itself. Every field has a default.
626#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
627#[serde(deny_unknown_fields, default)]
628pub struct Sizing {
629    /// The percent added to the largest sampled memory peak: a container is sampled every 2 s, so a spike between
630    /// two samples goes unseen. Default 15. Advice adds at least `api::PAGE_CACHE_ROOM`.
631    pub margin: u32,
632    /// The fewest jobs a profile, or a job of a repository's workflow, needs before its peaks become advice.
633    /// Default 10.
634    pub min_jobs: u32,
635    /// Whether the daemon writes each profile's advice into the config itself, within each profile's
636    /// `min_memory`, `max_memory` and `max_slots`. Default off.
637    pub auto: bool,
638    /// The least time between a change auto sizing makes to one profile and one that lowers anything in it. Default
639    /// 1 hour: a lowering that went too far is taken back at its first kill (docs/adr/0071).
640    #[serde(deserialize_with = "duration")]
641    pub interval: Duration,
642    /// The least time between a change auto sizing makes to one profile and one that only raises its `memory`,
643    /// `slots` or `cpus`; at most `interval`, which a longer one counts as. Default 1 hour.
644    #[serde(deserialize_with = "duration")]
645    pub raise_interval: Duration,
646    /// The most a change lowers a profile's `memory` or moves its `cpus`, in percent of them; a raise of `memory`,
647    /// which only a run that met the cap gives, goes straight to the advice. Default 50.
648    pub max_step: u32,
649}
650
651impl Sizing {
652    /// The least time between a change to one profile and one that only raises it: `raise_interval`, at most
653    /// `interval`.
654    pub fn raise_after(&self) -> Duration {
655        self.raise_interval.min(self.interval)
656    }
657}
658
659impl Default for Sizing {
660    fn default() -> Sizing {
661        Sizing {
662            margin: 15,
663            min_jobs: 10,
664            auto: false,
665            interval: Duration::from_hours(1),
666            raise_interval: Duration::from_hours(1),
667            max_step: 50,
668        }
669    }
670}
671
672/// `[web]`: the dashboard behind a reverse proxy, such as `tailscale serve`. Read when the daemon starts.
673#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
674#[serde(deny_unknown_fields, default)]
675pub struct Web {
676    /// The origins, besides the dashboard's own loopback address, whose pages may write: pause, reseed, save the
677    /// config. Default none.
678    pub origins: Vec<Origin>,
679    /// The one of `origins` that `runnerctl web` opens the dashboard on, such as a tailnet's address. Default none:
680    /// it opens the loopback address.
681    pub open: Option<Origin>,
682}
683
684impl Web {
685    /// Refuses an `open` that is not one of `origins`.
686    fn validate(&self) -> Result<(), ConfigError> {
687        match &self.open {
688            Some(open) if !self.origins.contains(open) => {
689                Err(ConfigError::OpenNotListed { open: open.clone() })
690            }
691            _ => Ok(()),
692        }
693    }
694}
695
696/// `[github]`: what runnerd may ask of GitHub on the owner's behalf (ADR 0134). A config with it is one the daemons
697/// before 0.2 refuse.
698#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
699#[serde(deny_unknown_fields, default)]
700pub struct Github {
701    /// Whether `POST /v1/jobs/{id}/cancel` and `POST /v1/jobs/{id}/rerun` may cancel a job's run or re-run it on
702    /// GitHub. Default on; off, both answer 403. A forced pause cancels runs either way.
703    pub job_actions: bool,
704}
705
706impl Default for Github {
707    fn default() -> Github {
708        Github { job_actions: true }
709    }
710}
711
712/// `[notify]`: where the daemon sends notifications (ADR 0051). Without targets nothing leaves the machine.
713#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
714#[serde(deny_unknown_fields, default)]
715pub struct Notify {
716    /// When the digest goes to the targets that want it, in the host's local time. Default `09:00`.
717    pub digest_at: DayTime,
718    /// The targets, each `[[notify.targets]]`.
719    pub targets: Vec<NotifyTarget>,
720}
721
722impl Default for Notify {
723    fn default() -> Notify {
724        Notify {
725            digest_at: DayTime { minutes: 9 * 60 },
726            targets: Vec::new(),
727        }
728    }
729}
730
731impl Notify {
732    /// Refuses a target without a name, with a name another has, with a URL that is not `http` or `https`, or with
733    /// a header that cannot be sent. Says which target and which field, never the URL or a header's value.
734    fn validate(&self) -> Result<(), ConfigError> {
735        let refuse = |target: &str, why: &'static str| {
736            Err(ConfigError::Notify {
737                target: target.to_owned(),
738                why,
739            })
740        };
741        for (index, target) in self.targets.iter().enumerate() {
742            let name = target.name.as_str();
743            if name.trim().is_empty() || name.chars().any(char::is_control) {
744                return refuse(name, "name is empty");
745            }
746            if self.targets[..index].iter().any(|other| other.name == name) {
747                return refuse(name, "another target has this name");
748            }
749            let url = target.url.expose();
750            if url == SECRET_SHOWN {
751                return refuse(
752                    name,
753                    "url is <secret>, which runnerd fills in only for a target of the same name that had one; write the url",
754                );
755            }
756            let Some(rest) = url
757                .strip_prefix("https://")
758                .or_else(|| url.strip_prefix("http://"))
759            else {
760                return refuse(name, "url does not start with https:// or http://");
761            };
762            let (host, path) = rest.split_once('/').unwrap_or((rest, ""));
763            if host.is_empty() || url.chars().any(|c| c.is_whitespace() || c.is_control()) {
764                return refuse(name, "url is not a URL");
765            }
766            if target.kind == NotifyKind::Ntfy
767                && (path.is_empty() || path.contains(['/', '?', '#']))
768            {
769                return refuse(
770                    name,
771                    "url is not an ntfy topic's, such as https://ntfy.sh/<topic>",
772                );
773            }
774            for (header, value) in &target.headers {
775                if value.expose() == SECRET_SHOWN {
776                    return refuse(
777                        name,
778                        "a header is <secret>, which runnerd fills in only for a target of the same name that had it; write its value",
779                    );
780                }
781                let token = |c: char| c.is_ascii_alphanumeric() || "!#$%&'*+-.^_`|~".contains(c);
782                if header.is_empty() || !header.chars().all(token) {
783                    return refuse(name, "a header's name is not a header name");
784                }
785                if value.expose().chars().any(char::is_control) {
786                    return refuse(name, "a header's value has a control character");
787                }
788            }
789            if target.events.contains(&api::NotifyEvent::Test) {
790                return refuse(
791                    name,
792                    "events lists test, which only runnerctl notify test sends",
793                );
794            }
795        }
796        Ok(())
797    }
798}
799
800/// `[[notify.targets]]`: one place notifications go.
801#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
802#[serde(deny_unknown_fields)]
803pub struct NotifyTarget {
804    /// What logs and `runnerctl notify test` call it, such as `phone`; the history keeps where it got to by it.
805    pub name: String,
806    /// What it takes.
807    pub kind: NotifyKind,
808    /// Where it is posted: the webhook's URL, Discord's included, or the ntfy topic's, such as `https://ntfy.sh/<topic>`.
809    /// A secret.
810    pub url: Secret,
811    /// Headers sent with each post, such as an ntfy access token's `Authorization`. Their values are secrets.
812    #[serde(default)]
813    pub headers: BTreeMap<String, Secret>,
814    /// What it is sent. Default `failed`, `lost`, `runner` and `insights`.
815    #[serde(default = "default_notify_events")]
816    pub events: Vec<api::NotifyEvent>,
817}
818
819fn default_notify_events() -> Vec<api::NotifyEvent> {
820    vec![
821        api::NotifyEvent::Failed,
822        api::NotifyEvent::Lost,
823        api::NotifyEvent::Runner,
824        api::NotifyEvent::Insights,
825    ]
826}
827
828/// What a notification target takes.
829#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
830#[serde(rename_all = "kebab-case")]
831pub enum NotifyKind {
832    /// `api::Notification` as JSON.
833    Webhook,
834    /// An ntfy topic: the title, message, priority and link, published as ntfy's JSON.
835    Ntfy,
836    /// A Discord channel's webhook: the title, message and link as one embed, coloured by event, that pings no one.
837    Discord,
838}
839
840/// A value no `Debug` output, log line or error shows: a notification target's URL or header.
841#[derive(Clone, PartialEq, Eq, Deserialize)]
842#[serde(transparent)]
843pub struct Secret(String);
844
845impl Secret {
846    /// The value, for the request that sends it.
847    pub fn expose(&self) -> &str {
848        &self.0
849    }
850}
851
852impl From<&str> for Secret {
853    fn from(value: &str) -> Secret {
854        Secret(value.to_owned())
855    }
856}
857
858impl fmt::Debug for Secret {
859    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
860        f.write_str("<secret>")
861    }
862}
863
864/// A time of day, `HH:MM`, 24-hour.
865#[derive(Debug, Clone, Copy, PartialEq, Eq)]
866pub struct DayTime {
867    /// Minutes after midnight.
868    pub minutes: u32,
869}
870
871impl FromStr for DayTime {
872    type Err = String;
873
874    fn from_str(text: &str) -> Result<DayTime, String> {
875        let invalid = || format!("invalid time of day {text:?}, expected HH:MM such as \"09:00\"");
876        let (hour, minute) = text.split_once(':').ok_or_else(invalid)?;
877        let digits = |part: &str| part.len() == 2 && part.chars().all(|c| c.is_ascii_digit());
878        if !digits(hour) || !digits(minute) {
879            return Err(invalid());
880        }
881        let (hour, minute): (u32, u32) = (
882            hour.parse().map_err(|_| invalid())?,
883            minute.parse().map_err(|_| invalid())?,
884        );
885        if hour > 23 || minute > 59 {
886            return Err(invalid());
887        }
888        Ok(DayTime {
889            minutes: hour * 60 + minute,
890        })
891    }
892}
893
894impl fmt::Display for DayTime {
895    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
896        write!(f, "{:02}:{:02}", self.minutes / 60, self.minutes % 60)
897    }
898}
899
900impl<'de> Deserialize<'de> for DayTime {
901    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
902        String::deserialize(deserializer)?
903            .parse()
904            .map_err(de::Error::custom)
905    }
906}
907
908/// An origin as a browser sends it in `Origin`: `https://host[:port]`, or `http://` for a loopback host, in lower
909/// case, without the scheme's default port, and an address written as the URL standard serializes it. Nothing after
910/// the port: no path, query or user.
911#[derive(Debug, Clone, PartialEq, Eq)]
912pub struct Origin(String);
913
914impl Origin {
915    /// The origin as a browser sends it, such as `https://host.example.ts.net:8443`.
916    pub fn as_str(&self) -> &str {
917        &self.0
918    }
919}
920
921impl FromStr for Origin {
922    type Err = String;
923
924    fn from_str(s: &str) -> Result<Origin, String> {
925        let invalid = |why: &str| {
926            format!(
927                "invalid origin {s:?}: {why}; write the scheme, host and port only, such as \
928                 \"https://host.example.ts.net:8443\""
929            )
930        };
931        let (scheme, rest) = s
932            .split_once("://")
933            .ok_or_else(|| invalid("it has no scheme"))?;
934        let scheme = scheme.to_ascii_lowercase();
935        if rest.contains(['/', '?', '#']) {
936            return Err(invalid("it has a path"));
937        }
938        if rest.contains('@') {
939            return Err(invalid("it names a user"));
940        }
941        let (host, port) = match rest.strip_prefix('[') {
942            Some(v6) => {
943                let (address, after) = v6
944                    .split_once(']')
945                    .ok_or_else(|| invalid("its IPv6 address has no closing ]"))?;
946                let port = match after {
947                    "" => None,
948                    _ => Some(after.strip_prefix(':').ok_or_else(|| invalid("its port"))?),
949                };
950                (format!("[{address}]"), port)
951            }
952            None => match rest.split_once(':') {
953                Some((host, port)) => (host.to_owned(), Some(port)),
954                None => (rest.to_owned(), None),
955            },
956        };
957        let host = host.to_ascii_lowercase();
958        let not_a_host = || invalid("its host is not a name or an address");
959        // An address is kept as a browser serializes it, or it would never match the `Origin` the browser sends.
960        let (host, loopback) =
961            if let Some(v6) = host.strip_prefix('[').and_then(|v6| v6.strip_suffix(']')) {
962                let address: Ipv6Addr = v6.parse().map_err(|_| not_a_host())?;
963                (format!("[{}]", ipv6_origin(address)), address.is_loopback())
964            } else {
965                if host.is_empty()
966                    || !host
967                        .chars()
968                        .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '.')
969                {
970                    return Err(not_a_host());
971                }
972                // As the URL standard reads a host: one whose last label is a number is an IPv4 address.
973                let name = host.strip_suffix('.').unwrap_or(&host);
974                let last = name.rsplit('.').next().unwrap_or_default();
975                let numeric = !last.is_empty()
976                    && (last.bytes().all(|byte| byte.is_ascii_digit())
977                        || last
978                            .strip_prefix("0x")
979                            .is_some_and(|hex| hex.bytes().all(|byte| byte.is_ascii_hexdigit())));
980                if numeric {
981                    let address: Ipv4Addr = name.parse().map_err(|_| {
982                        invalid("its IPv4 address is not four decimal numbers, such as 192.0.2.1")
983                    })?;
984                    (address.to_string(), address.is_loopback())
985                } else {
986                    let loopback = host == "localhost";
987                    (host, loopback)
988                }
989            };
990        let port = port
991            .map(|port| {
992                Some(port)
993                    .filter(|port| port.bytes().all(|byte| byte.is_ascii_digit()))
994                    .and_then(|port| port.parse::<u16>().ok())
995                    .filter(|port| *port != 0)
996                    .ok_or_else(|| invalid("its port is not a number from 1 to 65535"))
997            })
998            .transpose()?;
999        let default_port = match scheme.as_str() {
1000            "https" => 443,
1001            "http" if loopback => 80,
1002            "http" => {
1003                return Err(invalid(
1004                    "http is for a loopback host only, since the session cookie would cross the network in \
1005                     the clear; use https",
1006                ));
1007            }
1008            _ => return Err(invalid("its scheme is not https")),
1009        };
1010        Ok(Origin(match port {
1011            Some(port) if port != default_port => format!("{scheme}://{host}:{port}"),
1012            _ => format!("{scheme}://{host}"),
1013        }))
1014    }
1015}
1016
1017/// An IPv6 address as the URL standard serializes it: lower-case hex pieces, the first longest run of two or more
1018/// zero pieces as `::`, and no dotted IPv4 tail.
1019fn ipv6_origin(address: Ipv6Addr) -> String {
1020    let pieces = address.segments();
1021    let (mut zeros_at, mut zeros) = (0, 0);
1022    let mut at = 0;
1023    while at < pieces.len() {
1024        let run = pieces[at..].iter().take_while(|piece| **piece == 0).count();
1025        if run > zeros {
1026            (zeros_at, zeros) = (at, run);
1027        }
1028        at += run.max(1);
1029    }
1030    let hex = |pieces: &[u16]| {
1031        pieces
1032            .iter()
1033            .map(|piece| format!("{piece:x}"))
1034            .collect::<Vec<_>>()
1035            .join(":")
1036    };
1037    if zeros < 2 {
1038        return hex(&pieces);
1039    }
1040    format!(
1041        "{}::{}",
1042        hex(&pieces[..zeros_at]),
1043        hex(&pieces[zeros_at + zeros..])
1044    )
1045}
1046
1047impl fmt::Display for Origin {
1048    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1049        f.write_str(&self.0)
1050    }
1051}
1052
1053impl<'de> Deserialize<'de> for Origin {
1054    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
1055        String::deserialize(deserializer)?
1056            .parse()
1057            .map_err(de::Error::custom)
1058    }
1059}
1060
1061/// Where a config's text stops parsing ([`Config::parse_error`]).
1062#[derive(Debug, Clone, PartialEq, Eq)]
1063pub struct ParseError {
1064    /// The line, counted from 1.
1065    pub line: usize,
1066    /// What is wrong there, as the parser says it.
1067    pub message: String,
1068}
1069
1070/// Why a config cannot be used.
1071#[derive(Debug, thiserror::Error)]
1072pub enum ConfigError {
1073    /// The file cannot be read.
1074    #[error("cannot read {}: {source}", path.display())]
1075    Read {
1076        /// The config file.
1077        path: PathBuf,
1078        /// Why reading it failed.
1079        source: std::io::Error,
1080    },
1081    /// The file is not valid TOML or does not match the config's shape.
1082    #[error(transparent)]
1083    Parse(#[from] toml::de::Error),
1084    /// A repository names a profile `[profiles]` does not define.
1085    #[error(
1086        "repository {repository} uses profile {profile:?}, which is not defined under [profiles]; {}",
1087        defined_profiles(.defined)
1088    )]
1089    UnknownProfile {
1090        /// The repository's `owner/name`.
1091        repository: String,
1092        /// The profile it names.
1093        profile: String,
1094        /// The profiles `[profiles]` defines.
1095        defined: Vec<String>,
1096    },
1097    /// A repository has no labels, or an empty one.
1098    #[error("repository {repository} needs at least one non-empty label")]
1099    MissingLabels {
1100        /// The repository's `owner/name`.
1101        repository: String,
1102    },
1103    /// Two `[[repositories]]` entries of one repository use the same profile.
1104    #[error(
1105        "repository {repository} has two entries with profile {profile:?}; give each of its pools its own profile"
1106    )]
1107    PoolProfileTwice {
1108        /// The repository's `owner/name`.
1109        repository: String,
1110        /// The profile both entries name.
1111        profile: String,
1112    },
1113    /// Two `[[repositories]]` entries of one repository share a label, so a job asking only for labels they share
1114    /// could run in either.
1115    #[error(
1116        "repository {repository}'s pools in {first} and {second} both have the label {label:?}, so a job asking for \
1117         it could land in either; give each pool labels of its own, such as only {second:?}'s own label for the \
1118         lighter one"
1119    )]
1120    PoolLabelsOverlap {
1121        /// The repository's `owner/name`.
1122        repository: String,
1123        /// The profile of the first entry.
1124        first: String,
1125        /// The profile of the later entry.
1126        second: String,
1127        /// A label both have.
1128        label: String,
1129    },
1130    /// Two `[[repositories]]` entries of one repository say differently whose runs write to the build cache.
1131    #[error(
1132        "repository {repository}'s entries set build_cache_writers differently; whose runs may write to the build \
1133         cache is the repository's, so set the same in each"
1134    )]
1135    PoolWritersDiffer {
1136        /// The repository's `owner/name`.
1137        repository: String,
1138    },
1139    /// `unsafe-dind` without `allow_unsafe = true`.
1140    #[error(
1141        "isolation \"unsafe-dind\" runs runner containers privileged, so a job can take over the host; \
1142         set allow_unsafe = true under [host] to use it anyway"
1143    )]
1144    UnsafeNotAllowed,
1145    /// A limit is 0.
1146    #[error("{field} is 0; set it above 0")]
1147    ZeroLimit {
1148        /// The setting, such as `profiles.app.cpus`.
1149        field: String,
1150    },
1151    /// `cpu_overcommit` is not a number above 0 and at most `MAX_CPU_OVERCOMMIT`.
1152    #[error(
1153        "host.cpu_overcommit is {value}; set it above 0 and at most {MAX_CPU_OVERCOMMIT}, such as 1.0"
1154    )]
1155    CpuOvercommit {
1156        /// The value set.
1157        value: f64,
1158    },
1159    /// `[web] open` is not one of `[web] origins`.
1160    #[error(
1161        "web.open is {open}, which is not one of [web] origins; add it to origins, or remove open"
1162    )]
1163    OpenNotListed {
1164        /// The origin `open` names.
1165        open: Origin,
1166    },
1167    /// A profile's `memory` or `slots` are outside its `min_memory`, `max_memory` or `max_slots`, or its
1168    /// `min_memory` is above its `max_memory`.
1169    #[error("profiles.{profile}: {why}")]
1170    SizingBounds {
1171        /// The profile.
1172        profile: String,
1173        /// Which bound, such as `memory is above its max_memory`.
1174        why: &'static str,
1175    },
1176    /// A `[[notify.targets]]` entry cannot be used. Never says its URL or a header's value.
1177    #[error("notify target {target:?}: {why}")]
1178    Notify {
1179        /// The target's name.
1180        target: String,
1181        /// What is wrong, such as `url does not start with https:// or http://`.
1182        why: &'static str,
1183    },
1184    /// `[host] memory_ceiling` is under one runner of a profile and the mirror, so that profile could never start.
1185    #[error(
1186        "host.memory_ceiling is {ceiling}, under the {needs} one runner of {profile} and the mirror take; set it \
1187         to the most memory the host can grow to, such as the VM's maximum"
1188    )]
1189    CeilingUnderProfile {
1190        /// The profile.
1191        profile: String,
1192        /// Its `memory` and the mirror's.
1193        needs: ByteSize,
1194        /// The ceiling set.
1195        ceiling: ByteSize,
1196    },
1197    /// The caps add up past `u64::MAX` bytes.
1198    #[error("slots × memory over all profiles plus the mirror is too large to add up")]
1199    BudgetOverflow,
1200    /// Measured admission, the default, with a slice that has no `MemoryMax` to admit against.
1201    #[error(
1202        "measured admission, the default, admits runners against the slice {slice}'s MemoryMax, and it has none; \
1203         install a unit file for it (`runnerd doctor` prints one), or set [host] admission = \"caps\""
1204    )]
1205    MeasuredWithoutMemoryMax {
1206        /// The slice runners run in.
1207        slice: String,
1208    },
1209    /// Under `admission = "measured"`, one runner of a profile and the mirror do not fit `MemoryMax`.
1210    #[error(
1211        "one runner of {profile} and the mirror take {needs}, the slice {slice}'s MemoryMax is {memory_max}; lower \
1212         its `memory` or raise the slice's MemoryMax"
1213    )]
1214    ProfileOverBudget {
1215        /// The profile.
1216        profile: String,
1217        /// Its `memory` and the mirror's.
1218        needs: ByteSize,
1219        /// The slice runners run in.
1220        slice: String,
1221        /// The slice's `MemoryMax`.
1222        memory_max: ByteSize,
1223    },
1224    /// The caps add up to more than the slice's `MemoryMax`.
1225    #[error(
1226        "slots × memory over all profiles plus the mirror is {total}, \
1227         the slice {slice}'s MemoryMax is {memory_max}; lower `slots` or `memory`, or raise the slice's \
1228         MemoryMax (`runnerd doctor` prints its unit)"
1229    )]
1230    OverBudget {
1231        /// What every runner and the mirror may use at once.
1232        total: ByteSize,
1233        /// The slice runners run in.
1234        slice: String,
1235        /// The slice's `MemoryMax`.
1236        memory_max: ByteSize,
1237    },
1238}
1239
1240fn defined_profiles(defined: &[String]) -> String {
1241    if defined.is_empty() {
1242        "it defines none".to_owned()
1243    } else {
1244        format!("defined: {}", defined.join(", "))
1245    }
1246}
1247
1248/// What a valid config should still fix.
1249#[derive(Debug, Clone, PartialEq, Eq)]
1250pub enum Warning {
1251    /// The slice has no unit file, so systemd creates it without limits.
1252    UnlimitedSlice {
1253        /// The slice runners run in.
1254        slice: String,
1255        /// What every runner and the mirror may use at once.
1256        total: ByteSize,
1257    },
1258}
1259
1260impl fmt::Display for Warning {
1261    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1262        match self {
1263            Warning::UnlimitedSlice { slice, total } => write!(
1264                f,
1265                "the slice {slice} has no MemoryMax, so nothing holds runners to their {total} of caps; \
1266                 install a unit file for it"
1267            ),
1268        }
1269    }
1270}
1271
1272impl Config {
1273    /// Reads and parses a config file.
1274    pub fn load(path: &Path) -> Result<Config, ConfigError> {
1275        let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
1276            path: path.to_owned(),
1277            source,
1278        })?;
1279        Config::parse(&text)
1280    }
1281
1282    /// Parses a config from TOML text.
1283    pub fn parse(text: &str) -> Result<Config, ConfigError> {
1284        Ok(toml::from_str(text)?)
1285    }
1286
1287    /// Why a save from a diff is refused when the text changed after the diff was shown: the save would write lines
1288    /// nobody reviewed.
1289    pub fn unreviewed() -> &'static str {
1290        "not saved: the text changed after its changes were shown; review them again"
1291    }
1292
1293    /// Where `text` stops parsing as a config: the line, counted from 1, and the parser's words without its own
1294    /// excerpt of the text, for an editor that marks the line. `None` when it parses, and for an error the parser
1295    /// places nowhere.
1296    pub fn parse_error(text: &str) -> Option<ParseError> {
1297        let Err(error) = toml::from_str::<Config>(text) else {
1298            return None;
1299        };
1300        let span = error.span()?;
1301        let before = text.get(..span.start)?;
1302        Some(ParseError {
1303            line: before.matches('\n').count() + 1,
1304            message: error.message().trim().to_owned(),
1305        })
1306    }
1307
1308    /// Parses `text` and validates it against the `MemoryMax` that `memory_max` reads for the slice it names:
1309    /// what `runnerd check-config` prints and `POST /v1/config/check` answers. Returns the config if it is valid.
1310    pub fn check(
1311        text: &str,
1312        memory_max: impl FnOnce(&str) -> std::io::Result<Option<ByteSize>>,
1313    ) -> (Option<Config>, api::ConfigCheck) {
1314        let config = match Config::parse(text) {
1315            Ok(config) => config,
1316            Err(error) => return (None, budget::invalid(error.to_string(), None, None)),
1317        };
1318        let max = match memory_max(&config.host.slice) {
1319            Ok(max) => max,
1320            Err(error) => {
1321                return (
1322                    None,
1323                    budget::invalid(error.to_string(), Some(&config), None),
1324                );
1325            }
1326        };
1327        let check = config.check_against(max);
1328        if check.valid {
1329            (Some(config), check)
1330        } else {
1331            (None, check)
1332        }
1333    }
1334
1335    /// The mirror's memory cap, 0 when it is disabled.
1336    pub fn mirror_memory(&self) -> u64 {
1337        if self.caches.mirror.enabled {
1338            self.caches.mirror.memory.0
1339        } else {
1340            0
1341        }
1342    }
1343
1344    /// The memory every runner and the mirror may use at once.
1345    pub fn memory_caps(&self) -> Result<ByteSize, ConfigError> {
1346        let mirror = self.mirror_memory();
1347        self.profiles
1348            .values()
1349            .try_fold(mirror, |total, p| {
1350                p.memory
1351                    .0
1352                    .checked_mul(u64::from(p.slots))?
1353                    .checked_add(total)
1354            })
1355            .map(ByteSize)
1356            .ok_or(ConfigError::BudgetOverflow)
1357    }
1358
1359    /// The memory `[host] admission` must fit in `MemoryMax`: every cap at once under caps; under measured, the
1360    /// largest single runner with the mirror, since `slots` there only bounds how many run at once.
1361    pub fn memory_needed(&self) -> Result<ByteSize, ConfigError> {
1362        match self.host.admission {
1363            Admission::Caps => self.memory_caps(),
1364            Admission::Measured => {
1365                let largest = self
1366                    .profiles
1367                    .values()
1368                    .map(|p| p.memory.0)
1369                    .max()
1370                    .unwrap_or(0);
1371                largest
1372                    .checked_add(self.mirror_memory())
1373                    .map(ByteSize)
1374                    .ok_or(ConfigError::BudgetOverflow)
1375            }
1376        }
1377    }
1378
1379    /// The most `memory` one runner of any profile may have under `[host] memory_ceiling`: the ceiling less the
1380    /// mirror while it is enabled, as no host of that size starts more beside it. `None` without a ceiling. The
1381    /// config check refuses a profile above it, and auto sizing raises none past it (ADR 0086).
1382    pub fn runner_ceiling(&self) -> Option<u64> {
1383        self.host
1384            .memory_ceiling
1385            .map(|ceiling| ceiling.0.saturating_sub(self.mirror_memory()))
1386    }
1387
1388    /// Refuses a `[host] memory_ceiling` under one runner of the largest profile beside the mirror
1389    /// (`runner_ceiling`): no host of that size starts one, so it is a typo, such as `24M` for `24G`. Whether the
1390    /// host's `MemTotal` is already past it, and what the margin leaves, `runnerd doctor` says, as the config check
1391    /// does not read the host.
1392    fn check_memory_ceiling(&self) -> Result<(), ConfigError> {
1393        let (Some(ceiling), Some(most)) = (self.host.memory_ceiling, self.runner_ceiling()) else {
1394            return Ok(());
1395        };
1396        let largest = self
1397            .profiles
1398            .iter()
1399            .max_by_key(|(_, profile)| profile.memory.0);
1400        match largest {
1401            Some((profile, largest)) if largest.memory.0 > most => {
1402                Err(ConfigError::CeilingUnderProfile {
1403                    profile: profile.clone(),
1404                    needs: ByteSize(largest.memory.0.saturating_add(self.mirror_memory())),
1405                    ceiling,
1406                })
1407            }
1408            _ => Ok(()),
1409        }
1410    }
1411
1412    /// Refuses a profile outside the bounds auto sizing keeps it in, or whose bounds cross.
1413    fn check_sizing_bounds(&self) -> Result<(), ConfigError> {
1414        for (name, p) in &self.profiles {
1415            let memory = p.memory.0;
1416            let field = if p
1417                .min_memory
1418                .zip(p.max_memory)
1419                .is_some_and(|(min, max)| min.0 > max.0)
1420            {
1421                "min_memory is above its max_memory"
1422            } else if p.min_memory.is_some_and(|min| memory < min.0) {
1423                "memory is below its min_memory"
1424            } else if p.max_memory.is_some_and(|max| memory > max.0) {
1425                "memory is above its max_memory"
1426            } else if p.max_slots.is_some_and(|max| p.slots > max) {
1427                "slots are above its max_slots"
1428            } else {
1429                continue;
1430            };
1431            return Err(ConfigError::SizingBounds {
1432                profile: name.clone(),
1433                why: field,
1434            });
1435        }
1436        Ok(())
1437    }
1438
1439    /// Checks that each repository's pools tell its jobs apart: each in its own profile, with labels no other of its
1440    /// pools has, so at most one pool matches a job; and that they agree on whose runs write to the build cache.
1441    fn check_pools(&self) -> Result<(), ConfigError> {
1442        for (at, first) in self.repositories.iter().enumerate() {
1443            for second in self.repositories[at + 1..]
1444                .iter()
1445                .filter(|second| second.name == first.name)
1446            {
1447                if second.profile == first.profile {
1448                    return Err(ConfigError::PoolProfileTwice {
1449                        repository: first.name.clone(),
1450                        profile: first.profile.clone(),
1451                    });
1452                }
1453                if let Some(label) = first.labels.iter().find(|label| {
1454                    second
1455                        .labels
1456                        .iter()
1457                        .any(|other| other.eq_ignore_ascii_case(label))
1458                }) {
1459                    return Err(ConfigError::PoolLabelsOverlap {
1460                        repository: first.name.clone(),
1461                        first: first.profile.clone(),
1462                        second: second.profile.clone(),
1463                        label: label.clone(),
1464                    });
1465                }
1466                if second.build_cache_writers != first.build_cache_writers {
1467                    return Err(ConfigError::PoolWritersDiffer {
1468                        repository: first.name.clone(),
1469                    });
1470                }
1471            }
1472        }
1473        Ok(())
1474    }
1475
1476    /// The pool of `repository` whose labels match a job asking for `labels`: every label it asks for is one of
1477    /// the pool's. `None` when no pool of it does.
1478    pub fn pool(&self, repository: &str, labels: &[String]) -> Option<&Repository> {
1479        self.repositories
1480            .iter()
1481            .find(|pool| pool.name == repository && labels_match(labels, &pool.labels))
1482    }
1483
1484    /// The pool of `repository` in `profile`, whose runners start in that profile's slots.
1485    pub fn pool_in(&self, repository: &str, profile: &str) -> Option<&Repository> {
1486        self.repositories
1487            .iter()
1488            .find(|pool| pool.name == repository && pool.profile == profile)
1489    }
1490
1491    /// The GitHub-hosted runner each profile's jobs are priced at (ADR 0072).
1492    pub fn pricing(&self) -> api::Pricing {
1493        api::Pricing {
1494            profiles: self
1495                .profiles
1496                .iter()
1497                .filter_map(|(name, profile)| Some((name.clone(), profile.priced_as?)))
1498                .collect(),
1499            default_sku: api::Sku::standard_for(std::env::consts::ARCH),
1500        }
1501    }
1502
1503    /// The repositories served, each once, in the order the config first names them.
1504    pub fn repository_names(&self) -> Vec<String> {
1505        let mut names: Vec<String> = Vec::new();
1506        for repository in &self.repositories {
1507            if !names.contains(&repository.name) {
1508                names.push(repository.name.clone());
1509            }
1510        }
1511        names
1512    }
1513
1514    /// Checks the config against the slice's `MemoryMax` (`None` when the slice is unlimited).
1515    pub fn validate(&self, memory_max: Option<ByteSize>) -> Result<Vec<Warning>, ConfigError> {
1516        if self.host.isolation == Isolation::UnsafeDind && !self.host.allow_unsafe {
1517            return Err(ConfigError::UnsafeNotAllowed);
1518        }
1519        let zero_limits = self.profiles.iter().flat_map(|(name, p)| {
1520            [
1521                (p.memory.0 == 0, format!("profiles.{name}.memory")),
1522                (p.cpus == 0, format!("profiles.{name}.cpus")),
1523                (p.slots == 0, format!("profiles.{name}.slots")),
1524                (p.max_slots == Some(0), format!("profiles.{name}.max_slots")),
1525            ]
1526        });
1527        let mirror = &self.caches.mirror;
1528        let mirror_zero_limits = [
1529            (
1530                mirror.enabled && mirror.memory.0 == 0,
1531                "caches.mirror.memory".to_owned(),
1532            ),
1533            (
1534                mirror.enabled && mirror.cpus == 0,
1535                "caches.mirror.cpus".to_owned(),
1536            ),
1537            (
1538                self.host.poll_interval.is_zero(),
1539                "host.poll_interval".to_owned(),
1540            ),
1541            (
1542                self.host.memory_ceiling == Some(ByteSize(0)),
1543                "host.memory_ceiling".to_owned(),
1544            ),
1545            (self.records.max_count == 0, "records.max_count".to_owned()),
1546            (self.sizing.min_jobs == 0, "sizing.min_jobs".to_owned()),
1547            (self.sizing.interval.is_zero(), "sizing.interval".to_owned()),
1548            (
1549                self.sizing.raise_interval.is_zero(),
1550                "sizing.raise_interval".to_owned(),
1551            ),
1552            (self.sizing.max_step == 0, "sizing.max_step".to_owned()),
1553            (
1554                self.records.max_total.0 == 0,
1555                "records.max_total".to_owned(),
1556            ),
1557        ];
1558        if let Some((_, field)) = zero_limits
1559            .chain(mirror_zero_limits)
1560            .find(|(zero, _)| *zero)
1561        {
1562            return Err(ConfigError::ZeroLimit { field });
1563        }
1564        self.check_sizing_bounds()?;
1565        self.caches.build.validate()?;
1566        self.host.check_cpu_overcommit()?;
1567        self.check_memory_ceiling()?;
1568        self.web.validate()?;
1569        self.notify.validate()?;
1570        for repository in &self.repositories {
1571            if !self.profiles.contains_key(&repository.profile) {
1572                return Err(ConfigError::UnknownProfile {
1573                    repository: repository.name.clone(),
1574                    profile: repository.profile.clone(),
1575                    defined: self.profiles.keys().cloned().collect(),
1576                });
1577            }
1578            if repository.labels.is_empty() || repository.labels.iter().any(|l| l.trim().is_empty())
1579            {
1580                return Err(ConfigError::MissingLabels {
1581                    repository: repository.name.clone(),
1582                });
1583            }
1584        }
1585        self.check_pools()?;
1586        self.check_budget(memory_max)
1587    }
1588
1589    /// Holds what `[host] admission` needs to the slice's `MemoryMax`; warns when the slice has none to hold caps to.
1590    fn check_budget(&self, memory_max: Option<ByteSize>) -> Result<Vec<Warning>, ConfigError> {
1591        let total = self.memory_caps()?;
1592        if self.host.admission == Admission::Measured {
1593            let Some(memory_max) = memory_max else {
1594                return Err(ConfigError::MeasuredWithoutMemoryMax {
1595                    slice: self.host.slice.clone(),
1596                });
1597            };
1598            let mirror = self.mirror_memory();
1599            if let Some((profile, needs)) = self
1600                .profiles
1601                .iter()
1602                .map(|(name, profile)| (name, profile.memory.0.saturating_add(mirror)))
1603                .find(|(_, needs)| *needs > memory_max.0)
1604            {
1605                return Err(ConfigError::ProfileOverBudget {
1606                    profile: profile.clone(),
1607                    needs: ByteSize(needs),
1608                    slice: self.host.slice.clone(),
1609                    memory_max,
1610                });
1611            }
1612            // Without a profile, the mirror alone must fit: the caps sum, which is all `memory_needed` holds.
1613            let needed = self.memory_needed()?;
1614            if needed > memory_max {
1615                return Err(ConfigError::OverBudget {
1616                    total: needed,
1617                    slice: self.host.slice.clone(),
1618                    memory_max,
1619                });
1620            }
1621            return Ok(Vec::new());
1622        }
1623        match memory_max {
1624            Some(memory_max) if total > memory_max => Err(ConfigError::OverBudget {
1625                total,
1626                slice: self.host.slice.clone(),
1627                memory_max,
1628            }),
1629            Some(_) => Ok(Vec::new()),
1630            None => Ok(vec![Warning::UnlimitedSlice {
1631                slice: self.host.slice.clone(),
1632                total,
1633            }]),
1634        }
1635    }
1636}
1637
1638/// Why `resize_profile` cannot change a config.
1639#[derive(Debug, thiserror::Error)]
1640pub enum ResizeError {
1641    /// The text is not valid TOML.
1642    #[error(transparent)]
1643    Parse(#[from] toml_edit::TomlError),
1644    /// `[profiles]` does not define the profile.
1645    #[error("the config has no profile {0:?} under [profiles]")]
1646    NoProfile(String),
1647}
1648
1649/// `text` with the profile's `memory` and `slots` replaced, and its `cpus` when `resize` has them, everything else as
1650/// written, comments included: what applying a sizing suggestion sends to `PUT /v1/config`, which validates it.
1651pub fn resize_profile(
1652    text: &str,
1653    profile: &str,
1654    resize: api::Resize,
1655) -> Result<String, ResizeError> {
1656    let mut document: toml_edit::DocumentMut = text.parse()?;
1657    let table = document
1658        .get_mut("profiles")
1659        .and_then(|profiles| profiles.get_mut(profile))
1660        .and_then(toml_edit::Item::as_table_like_mut)
1661        .ok_or_else(|| ResizeError::NoProfile(profile.to_owned()))?;
1662    let values = [
1663        (
1664            "memory",
1665            toml_edit::Value::from(ByteSize(resize.memory).exact()),
1666        ),
1667        ("slots", toml_edit::Value::from(i64::from(resize.slots))),
1668    ];
1669    let cpus = resize
1670        .cpus
1671        .map(|cpus| ("cpus", toml_edit::Value::from(i64::from(cpus))));
1672    for (key, mut value) in values.into_iter().chain(cpus) {
1673        // The comment after the old value stays after the new one.
1674        if let Some(old) = table.get(key).and_then(toml_edit::Item::as_value) {
1675            *value.decor_mut() = old.decor().clone();
1676        }
1677        table.insert(key, toml_edit::Item::Value(value));
1678    }
1679    Ok(document.to_string())
1680}
1681
1682/// `profile`'s `memory`, `slots` and `cpus` in the config `text`, as a sizing start changes them from; `None` when
1683/// `text` is not a config or has no such profile.
1684pub fn profile_sizes(text: &str, profile: &str) -> Option<api::Resize> {
1685    let config = Config::parse(text).ok()?;
1686    let sizes = config.profiles.get(profile)?;
1687    Some(api::Resize {
1688        memory: sizes.memory.0,
1689        slots: sizes.slots,
1690        cpus: Some(sizes.cpus),
1691    })
1692}
1693
1694/// Where `resize_profile` wrote `resize` in `text`: the bytes from the first of the profile's `memory`, `slots` and,
1695/// when `resize` has them, `cpus` settings to the end of the last, so a client can select them. `None` when `text` is
1696/// not TOML or the profile sets none of them.
1697pub fn resized_at(
1698    text: &str,
1699    profile: &str,
1700    resize: api::Resize,
1701) -> Option<std::ops::Range<usize>> {
1702    let document = toml_edit::Document::parse(text).ok()?;
1703    let table = document
1704        .as_table()
1705        .get("profiles")?
1706        .get(profile)?
1707        .as_table_like()?;
1708    let cpus = resize.cpus.map(|_| "cpus");
1709    ["memory", "slots"]
1710        .into_iter()
1711        .chain(cpus)
1712        .filter_map(|key| {
1713            let (key, item) = table.get_key_value(key)?;
1714            Some(key.span()?.start..item.span()?.end)
1715        })
1716        .reduce(|first, next| first.start.min(next.start)..first.end.max(next.end))
1717}
1718
1719/// What `GET /v1/config` shows in place of a notification target's URL and header values (ADR 0051).
1720pub const SECRET_SHOWN: &str = "<secret>";
1721
1722/// `text` with each `[[notify.targets]]` entry's `url` and header values shown as [`SECRET_SHOWN`], everything else
1723/// as written: what `GET /v1/config` answers, so no client, the dashboard's browsers included, holds them. `None`
1724/// when `text` is not TOML.
1725pub fn mask_secrets(text: &str) -> Option<String> {
1726    let mut document: toml_edit::DocumentMut = text.parse().ok()?;
1727    let mut masked = false;
1728    for target in notify_targets(&mut document) {
1729        for (_, value) in secrets_of(target) {
1730            replace_value(value, toml_edit::Value::from(SECRET_SHOWN));
1731            masked = true;
1732        }
1733    }
1734    Some(if masked {
1735        document.to_string()
1736    } else {
1737        text.to_owned()
1738    })
1739}
1740
1741/// `text` with each [`SECRET_SHOWN`] in a target's `url` or headers replaced by the value `stored` has for the target
1742/// of the same name, everything else as written: what `PUT /v1/config` and `POST /v1/config/check` read, so a config
1743/// shown masked saves with its secrets. A value with nothing to keep stays [`SECRET_SHOWN`], which `Config::validate`
1744/// refuses. A text that does not parse as a config is answered as sent: a TOML error quotes the line it is on, and
1745/// that line must hold the mask, not the value put back. One that parses still does with the values put back, as they
1746/// are strings where strings were, and `Config::validate` names a target's field, never its value.
1747pub fn keep_secrets(text: &str, stored: &str) -> String {
1748    if !text.contains(SECRET_SHOWN) || Config::parse(text).is_err() {
1749        return text.to_owned();
1750    }
1751    let (Ok(mut document), Ok(mut old)) = (
1752        text.parse::<toml_edit::DocumentMut>(),
1753        stored.parse::<toml_edit::DocumentMut>(),
1754    ) else {
1755        return text.to_owned();
1756    };
1757    let mut kept: BTreeMap<String, Vec<(SecretField, toml_edit::Value)>> = BTreeMap::new();
1758    for target in notify_targets(&mut old) {
1759        let Some(name) = target_name(target) else {
1760            continue;
1761        };
1762        let secrets = secrets_of(target)
1763            .into_iter()
1764            .map(|(field, value)| (field, value.clone()))
1765            .collect();
1766        kept.insert(name, secrets);
1767    }
1768    for target in notify_targets(&mut document) {
1769        let Some(secrets) = target_name(target).and_then(|name| kept.get(&name)) else {
1770            continue;
1771        };
1772        for (field, value) in secrets_of(target) {
1773            if value.as_str() != Some(SECRET_SHOWN) {
1774                continue;
1775            }
1776            if let Some((_, old)) = secrets.iter().find(|(kept, _)| *kept == field) {
1777                replace_value(value, old.clone());
1778            }
1779        }
1780    }
1781    document.to_string()
1782}
1783
1784/// Where a target keeps a secret.
1785#[derive(Debug, PartialEq, Eq)]
1786enum SecretField {
1787    Url,
1788    Header(String),
1789}
1790
1791/// The tables of `[[notify.targets]]`, or of an inline `targets = [...]`.
1792fn notify_targets(document: &mut toml_edit::DocumentMut) -> Vec<&mut dyn toml_edit::TableLike> {
1793    match document
1794        .get_mut("notify")
1795        .and_then(|notify| notify.get_mut("targets"))
1796    {
1797        Some(toml_edit::Item::ArrayOfTables(tables)) => tables
1798            .iter_mut()
1799            .map(|table| table as &mut dyn toml_edit::TableLike)
1800            .collect(),
1801        Some(toml_edit::Item::Value(toml_edit::Value::Array(array))) => array
1802            .iter_mut()
1803            .filter_map(toml_edit::Value::as_inline_table_mut)
1804            .map(|table| table as &mut dyn toml_edit::TableLike)
1805            .collect(),
1806        _ => Vec::new(),
1807    }
1808}
1809
1810fn target_name(target: &dyn toml_edit::TableLike) -> Option<String> {
1811    target
1812        .get("name")
1813        .and_then(toml_edit::Item::as_str)
1814        .map(str::to_owned)
1815}
1816
1817/// A target's `url` and header values.
1818fn secrets_of(target: &mut dyn toml_edit::TableLike) -> Vec<(SecretField, &mut toml_edit::Value)> {
1819    let mut found = Vec::new();
1820    for (key, item) in target.iter_mut() {
1821        match key.get() {
1822            "url" => found.extend(item.as_value_mut().map(|value| (SecretField::Url, value))),
1823            "headers" => {
1824                let Some(headers) = item.as_table_like_mut() else {
1825                    continue;
1826                };
1827                for (name, item) in headers.iter_mut() {
1828                    let field = SecretField::Header(name.get().to_owned());
1829                    found.extend(item.as_value_mut().map(|value| (field, value)));
1830                }
1831            }
1832            _ => {}
1833        }
1834    }
1835    found
1836}
1837
1838/// Puts `new` in place of `value`, with the spaces and comment around it as they were.
1839fn replace_value(value: &mut toml_edit::Value, mut new: toml_edit::Value) {
1840    *new.decor_mut() = value.decor().clone();
1841    *value = new;
1842}
1843
1844/// A config text's revision: a hash of its bytes (64-bit FNV-1a, in hex), the same in every runnerd. `PUT
1845/// /v1/config?revision=` refuses a text sent against another revision than the daemon's.
1846pub fn revision(text: &str) -> String {
1847    let hash = text.bytes().fold(0xcbf2_9ce4_8422_2325_u64, |hash, byte| {
1848        (hash ^ u64::from(byte)).wrapping_mul(0x0100_0000_01b3)
1849    });
1850    format!("{hash:016x}")
1851}
1852
1853/// Reads a slice's `MemoryMax` from systemd; `None` when it is unlimited.
1854pub fn slice_memory_max(slice: &str) -> std::io::Result<Option<ByteSize>> {
1855    let output = Command::new("systemctl")
1856        .args(["show", slice, "--property=MemoryMax", "--value"])
1857        .output()?;
1858    if !output.status.success() {
1859        return Err(std::io::Error::other(format!(
1860            "systemctl show {slice} failed: {}",
1861            String::from_utf8_lossy(&output.stderr).trim()
1862        )));
1863    }
1864    let value = String::from_utf8_lossy(&output.stdout);
1865    parse_memory_max(value.trim()).ok_or_else(|| {
1866        std::io::Error::other(format!(
1867            "systemctl show {slice}: unexpected MemoryMax {value:?}"
1868        ))
1869    })
1870}
1871
1872/// The CPU budget, in millicores, of `millicores` of CPUs overcommitted `overcommit` times.
1873pub fn cpu_budget(millicores: u64, overcommit: f64) -> u64 {
1874    #[expect(
1875        clippy::cast_precision_loss,
1876        clippy::cast_possible_truncation,
1877        clippy::cast_sign_loss,
1878        reason = "a host's millicores are far below 2^52, and the config check holds the factor above 0 and at \
1879                  most 16"
1880    )]
1881    let budget = (millicores as f64 * overcommit.max(0.0)).round() as u64;
1882    budget
1883}
1884
1885/// Reads the CPUs a slice's processes may use from systemd, in millicores: its `EffectiveCPUs` (or `AllowedCPUs`,
1886/// else the host's CPUs), less when its `CPUQuota` is lower.
1887pub fn slice_cpus(slice: &str) -> std::io::Result<u64> {
1888    let output = Command::new("systemctl")
1889        .args([
1890            "show",
1891            slice,
1892            "--property=EffectiveCPUs",
1893            "--property=AllowedCPUs",
1894            "--property=CPUQuotaPerSecUSec",
1895        ])
1896        .output()?;
1897    if !output.status.success() {
1898        return Err(std::io::Error::other(format!(
1899            "systemctl show {slice} failed: {}",
1900            String::from_utf8_lossy(&output.stderr).trim()
1901        )));
1902    }
1903    let host = std::thread::available_parallelism().map_or(1, std::num::NonZero::get) as u64;
1904    parse_slice_cpus(&String::from_utf8_lossy(&output.stdout), host).ok_or_else(|| {
1905        std::io::Error::other(format!(
1906            "systemctl show {slice}: unexpected CPU properties {:?}",
1907            String::from_utf8_lossy(&output.stdout).trim()
1908        ))
1909    })
1910}
1911
1912/// The CPUs, in millicores, that `systemctl show`'s `EffectiveCPUs`, `AllowedCPUs` and `CPUQuotaPerSecUSec` lines
1913/// leave a slice on a host with `host` CPUs; `None` when a value does not parse.
1914pub fn parse_slice_cpus(properties: &str, host: u64) -> Option<u64> {
1915    let value = |name: &str| {
1916        properties.lines().find_map(|line| {
1917            line.strip_prefix(name)
1918                .and_then(|rest| rest.strip_prefix('='))
1919                .map(str::trim)
1920        })
1921    };
1922    let set = [value("EffectiveCPUs"), value("AllowedCPUs")]
1923        .into_iter()
1924        .flatten()
1925        .find(|cpus| !cpus.is_empty());
1926    let cpus = match set {
1927        Some(set) => cpu_count(set)?,
1928        None => host,
1929    };
1930    let quota = match value("CPUQuotaPerSecUSec") {
1931        None | Some("" | "infinity") => u64::MAX,
1932        Some(quota) => quota_millicores(quota)?,
1933    };
1934    Some(cpus.saturating_mul(1000).min(quota))
1935}
1936
1937/// How many CPUs a set names, as systemd prints it (`0-3 8-11`) or as it is written (`0-3,8,10-11`).
1938fn cpu_count(set: &str) -> Option<u64> {
1939    set.split([',', ' '])
1940        .filter(|range| !range.is_empty())
1941        .try_fold(0u64, |count, range| {
1942            let (first, last) = range.split_once('-').unwrap_or((range, range));
1943            let (first, last): (u64, u64) = (first.parse().ok()?, last.parse().ok()?);
1944            Some(count + last.checked_sub(first)? + 1)
1945        })
1946}
1947
1948/// A `CPUQuotaPerSecUSec` as systemd prints a timespan, such as `800ms`, `2.500000s` or `1min 4s`, as the
1949/// millicores it allows: a second of CPU time each second is 1000.
1950fn quota_millicores(quota: &str) -> Option<u64> {
1951    // Each unit's length in milliseconds, as systemd's `format_timespan` names them.
1952    const UNITS: [(&str, f64); 10] = [
1953        ("y", 31_557_600_000.0),
1954        ("M", 2_629_800_000.0),
1955        ("w", 604_800_000.0),
1956        ("d", 86_400_000.0),
1957        ("h", 3_600_000.0),
1958        ("min", 60_000.0),
1959        ("s", 1000.0),
1960        ("ms", 1.0),
1961        ("us", 0.001),
1962        ("µs", 0.001),
1963    ];
1964    let millicores = quota.split_whitespace().try_fold(0.0, |total, part| {
1965        let at = part.find(|c: char| !(c.is_ascii_digit() || c == '.'))?;
1966        let (number, unit) = part.split_at(at);
1967        let per_unit = UNITS
1968            .iter()
1969            .find_map(|(name, per_unit)| (*name == unit).then_some(*per_unit))?;
1970        Some(total + number.parse::<f64>().ok()? * per_unit)
1971    })?;
1972    #[allow(
1973        clippy::cast_possible_truncation,
1974        clippy::cast_sign_loss,
1975        reason = "a quota is a few thousand millicores per CPU, checked finite and not negative first"
1976    )]
1977    (!quota.trim().is_empty() && millicores.is_finite() && millicores >= 0.0)
1978        .then(|| millicores.round() as u64)
1979}
1980
1981/// Parses a `MemoryMax` value as `systemctl show` prints it: bytes, or `infinity`.
1982pub fn parse_memory_max(value: &str) -> Option<Option<ByteSize>> {
1983    if value == "infinity" {
1984        Some(None)
1985    } else {
1986        value.parse().ok().map(|bytes| Some(ByteSize(bytes)))
1987    }
1988}
1989
1990/// A size in bytes, written with a binary unit as Docker and systemd do: `512M`, `9G`, `32.5G`.
1991#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
1992pub struct ByteSize(pub u64);
1993
1994const UNITS: [(char, u64); 4] = [
1995    ('T', 1 << 40),
1996    ('G', 1 << 30),
1997    ('M', 1 << 20),
1998    ('K', 1 << 10),
1999];
2000
2001impl FromStr for ByteSize {
2002    type Err = String;
2003
2004    #[allow(
2005        clippy::cast_precision_loss,
2006        clippy::cast_possible_truncation,
2007        clippy::cast_sign_loss,
2008        reason = "sizes in a config are far below 2^52 bytes, and the result is checked against u64's range first"
2009    )]
2010    fn from_str(s: &str) -> Result<Self, Self::Err> {
2011        let invalid = || {
2012            format!(
2013                "invalid size {s:?}, expected a number and a unit (K, M, G or T), such as \"9G\""
2014            )
2015        };
2016        let unit = s.chars().last().ok_or_else(invalid)?.to_ascii_uppercase();
2017        let (_, factor) = UNITS.iter().find(|(u, _)| *u == unit).ok_or_else(invalid)?;
2018        let number = &s[..s.len() - 1];
2019        if number.is_empty() || !number.chars().all(|c| c.is_ascii_digit() || c == '.') {
2020            return Err(invalid());
2021        }
2022        let number: f64 = number.parse().map_err(|_| invalid())?;
2023        let bytes = (number * *factor as f64).round();
2024        // `u64::MAX as f64` is 2^64, the first value out of range.
2025        if bytes >= u64::MAX as f64 {
2026            return Err(format!("size {s:?} is too large"));
2027        }
2028        Ok(ByteSize(bytes as u64))
2029    }
2030}
2031
2032impl fmt::Display for ByteSize {
2033    #[allow(
2034        clippy::cast_precision_loss,
2035        reason = "shown with two decimals, far coarser than f64's precision"
2036    )]
2037    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2038        let Some((unit, factor)) = UNITS.iter().find(|(_, factor)| self.0 >= *factor) else {
2039            return write!(f, "{}B", self.0);
2040        };
2041        let number = format!("{:.2}", self.0 as f64 / *factor as f64);
2042        let number = number.trim_end_matches('0').trim_end_matches('.');
2043        write!(f, "{number}{unit}")
2044    }
2045}
2046
2047impl ByteSize {
2048    /// The size as a config file writes it, reading back to the byte: `Display`'s form when that reads back as it,
2049    /// else the shortest exact decimal in one of the units, such as `1029.5G` where `Display` says `1.01T`. A size
2050    /// written from it, as auto sizing writes `memory`, is the size the config check then reads.
2051    #[allow(
2052        clippy::cast_precision_loss,
2053        reason = "a unit is a power of two, so the quotient is exact below 2^53 bytes; the parse checks it"
2054    )]
2055    pub fn exact(self) -> String {
2056        let reads_back = |text: &String| text.parse::<ByteSize>() == Ok(self);
2057        let shown = self.to_string();
2058        if reads_back(&shown) {
2059            return shown;
2060        }
2061        let mut shortest: Option<String> = None;
2062        for (unit, factor) in UNITS {
2063            let text = format!("{}{unit}", self.0 as f64 / factor as f64);
2064            if reads_back(&text) && shortest.as_ref().is_none_or(|best| text.len() < best.len()) {
2065                shortest = Some(text);
2066            }
2067        }
2068        shortest.unwrap_or(shown)
2069    }
2070
2071    /// The size rounded to the nearest, for a label too narrow for its `Display`: two significant digits below 10
2072    /// of its unit, whole units above, and the next unit up once it rounds to 1024: `3.3G` for 3.25G, `12G`,
2073    /// `512M`, and `1G` for 1023.5M. Every client's budget bar labels a block with it.
2074    #[allow(
2075        clippy::cast_precision_loss,
2076        reason = "shown with one decimal at most, far coarser than f64's precision"
2077    )]
2078    pub fn short(self) -> String {
2079        let Some(index) = UNITS.iter().position(|(_, factor)| self.0 >= *factor) else {
2080            return format!("{}B", self.0);
2081        };
2082        let (mut unit, factor) = UNITS[index];
2083        let mut value = self.0 as f64 / factor as f64;
2084        if value.round() >= 1024.0
2085            && let Some(larger) = index.checked_sub(1)
2086        {
2087            unit = UNITS[larger].0;
2088            value /= 1024.0;
2089        }
2090        // Halves round up, as `f64::round` does and formatting, which rounds them to even, does not.
2091        let tenths = (value * 10.0).round() / 10.0;
2092        if tenths < 10.0 {
2093            let number = format!("{tenths:.1}");
2094            format!("{}{unit}", number.trim_end_matches(".0"))
2095        } else {
2096            format!("{:.0}{unit}", value.round())
2097        }
2098    }
2099}
2100
2101impl<'de> Deserialize<'de> for ByteSize {
2102    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
2103        String::deserialize(deserializer)?
2104            .parse()
2105            .map_err(de::Error::custom)
2106    }
2107}
2108
2109/// Parses a duration as Go and the registry write it, `30s`, `90m`, `168h`, or in days: `7d`.
2110pub fn parse_duration(s: &str) -> Result<Duration, String> {
2111    let invalid = || {
2112        format!(
2113            "invalid duration {s:?}, expected a number and s, m, h or d, such as \"168h\" or \"7d\""
2114        )
2115    };
2116    let (number, factor) = match s.chars().last() {
2117        Some('s') => (&s[..s.len() - 1], 1),
2118        Some('m') => (&s[..s.len() - 1], 60),
2119        Some('h') => (&s[..s.len() - 1], 3600),
2120        Some('d') => (&s[..s.len() - 1], 86400),
2121        _ => return Err(invalid()),
2122    };
2123    let number: u64 = number.parse().map_err(|_| invalid())?;
2124    number
2125        .checked_mul(factor)
2126        .map(Duration::from_secs)
2127        .ok_or_else(invalid)
2128}
2129
2130/// Parses an age as the clients' `--since` and `--older-than` take it: `30m`, `12h`, `7d`, `2w`.
2131pub fn parse_age(text: &str) -> Result<Duration, String> {
2132    let error = || "expected a number and s, m, h, d or w, such as 12h".to_owned();
2133    let split = text.find(|c: char| !c.is_ascii_digit()).ok_or_else(error)?;
2134    let (number, unit) = text.split_at(split);
2135    let number: u64 = number.parse().map_err(|_| error())?;
2136    let unit = match unit {
2137        "s" => 1,
2138        "m" => 60,
2139        "h" => 3600,
2140        "d" => 86_400,
2141        "w" => 7 * 86_400,
2142        _ => return Err(error()),
2143    };
2144    Ok(Duration::from_secs(number.saturating_mul(unit)))
2145}
2146
2147fn duration<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Duration, D::Error> {
2148    parse_duration(&String::deserialize(deserializer)?).map_err(de::Error::custom)
2149}
2150
2151#[cfg(test)]
2152mod tests;