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