eb_pipeline/
site.rs

1//! Loading and validating site files.
2
3use crate::exit::Fail;
4use crate::resolve::{Scope, MODULE_SHELLS};
5use crate::schema::*;
6use crate::util::parse_version;
7use std::collections::{BTreeMap, BTreeSet};
8use std::path::Path;
9
10/// Parse a site file from text. Unknown keys and type errors are usage errors.
11pub fn parse(text: &str) -> Result<Site, Fail> {
12    toml::from_str::<Site>(text).map_err(|e| Fail::usage(format!("invalid site file: {e}")))
13}
14
15/// Read and parse a site file, then apply the `EB_PIPELINE__*` overrides
16/// from the environment (see [`parse_with_overrides`]).
17pub fn load(path: &Path) -> Result<Site, Fail> {
18    let text = std::fs::read_to_string(path)
19        .map_err(|e| Fail::usage(format!("cannot read {}: {e}", path.display())))?;
20    let vars: Vec<(String, String)> = std::env::vars()
21        .filter(|(k, _)| k.starts_with(OVERRIDE_PREFIX))
22        .collect();
23    parse_with_overrides(&text, &vars)
24}
25
26/// Prefix of an environment variable that overrides one site file value.
27pub const OVERRIDE_PREFIX: &str = "EB_PIPELINE__";
28
29/// Parse a site file and set one value per `(name, value)` pair over it.
30///
31/// `EB_PIPELINE__FILESYSTEMS__SCRATCH=/scratch/x` sets `filesystems.scratch`:
32/// the name after the prefix is split on `__` and each part lowercased. The
33/// value is read as a TOML value (`true`, `16`, `["a", "b"]`, `"16"`) and
34/// taken as a string when it does not parse as one. Missing tables are
35/// created. A path through an array of tables (`targets`) is refused, so
36/// per-target values stay in the file. The result is checked by the same
37/// schema as the file, so an unknown key or a wrong type is a usage error.
38/// Pairs apply in name order, so the outcome does not depend on the order of
39/// the environment.
40pub fn parse_with_overrides(text: &str, vars: &[(String, String)]) -> Result<Site, Fail> {
41    if vars.is_empty() {
42        return parse(text);
43    }
44    let mut table: toml::Table =
45        toml::from_str(text).map_err(|e| Fail::usage(format!("invalid site file: {e}")))?;
46    let mut sorted: Vec<&(String, String)> = vars.iter().collect();
47    sorted.sort();
48    for (name, raw) in sorted {
49        apply_override(&mut table, name, raw)?;
50    }
51    toml::Value::Table(table).try_into::<Site>().map_err(|e| {
52        Fail::usage(format!(
53            "invalid site file after environment overrides: {e}"
54        ))
55    })
56}
57
58fn override_path(name: &str) -> Result<Vec<String>, Fail> {
59    let rest = name.strip_prefix(OVERRIDE_PREFIX).unwrap_or(name);
60    let parts: Vec<String> = rest.split("__").map(str::to_ascii_lowercase).collect();
61    let ok = parts.iter().all(|p| {
62        !p.is_empty()
63            && p.chars()
64                .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
65    });
66    if !ok {
67        return Err(Fail::usage(format!(
68            "{name}: an override names SECTION__KEY in letters, digits and single underscores"
69        )));
70    }
71    Ok(parts)
72}
73
74fn override_value(raw: &str) -> toml::Value {
75    toml::from_str::<toml::Table>(&format!("v = {raw}"))
76        .ok()
77        .and_then(|mut t| t.remove("v"))
78        .unwrap_or_else(|| toml::Value::String(raw.to_string()))
79}
80
81fn apply_override(table: &mut toml::Table, name: &str, raw: &str) -> Result<(), Fail> {
82    let path = override_path(name)?;
83    let (last, parents) = path.split_last().expect("split yields one part");
84    let mut here = table;
85    for (i, part) in parents.iter().enumerate() {
86        let entry = here
87            .entry(part.clone())
88            .or_insert(toml::Value::Table(toml::Table::new()));
89        here = match entry {
90            toml::Value::Table(t) => t,
91            _ => {
92                return Err(Fail::usage(format!(
93                    "{name}: `{}` is not a table; an override cannot reach inside it",
94                    path[..=i].join(".")
95                )))
96            }
97        };
98    }
99    match here.get(last) {
100        Some(toml::Value::Array(a)) if a.iter().any(|x| x.is_table()) => {
101            return Err(Fail::usage(format!(
102                "{name}: `{}` is an array of tables; set it in the site file",
103                path.join(".")
104            )))
105        }
106        Some(toml::Value::Table(_)) => {
107            return Err(Fail::usage(format!(
108                "{name}: `{}` is a table; name one of its keys",
109                path.join(".")
110            )))
111        }
112        _ => {}
113    }
114    crate::run::log(
115        "INFO",
116        "site",
117        "-",
118        &format!("{} set from {name}", path.join(".")),
119    );
120    here.insert(last.clone(), override_value(raw));
121    Ok(())
122}
123
124const PLACEHOLDERS: &[&str] = &["project", "build", "phase", "target"];
125
126/// Placeholders of a site path that takes one value per target.
127const PER_TARGET: &[&str] = &["target"];
128
129fn name_ok(s: &str) -> bool {
130    !s.is_empty()
131        && s.chars()
132            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'))
133}
134
135fn env_name_ok(s: &str) -> bool {
136    !s.is_empty()
137        && !s.starts_with(|c: char| c.is_ascii_digit())
138        && s.chars().all(|c| c.is_ascii_alphanumeric() || c == '_')
139}
140
141/// Report unknown or unbalanced `{placeholder}` uses in `text`.
142fn check_placeholders(key: &str, text: &str, allowed: &[&str], errs: &mut Vec<String>) {
143    let mut rest = text;
144    while let Some(i) = rest.find('{') {
145        match rest[i..].find('}') {
146            Some(j) => {
147                let name = &rest[i + 1..i + j];
148                if !allowed.contains(&name) {
149                    let known: Vec<String> = allowed.iter().map(|a| format!("{{{a}}}")).collect();
150                    errs.push(format!(
151                        "{key}: unknown placeholder {{{name}}}; known: {}",
152                        known.join(", ")
153                    ));
154                }
155                rest = &rest[i + j + 1..];
156            }
157            None => {
158                errs.push(format!("{key}: unbalanced `{{`"));
159                break;
160            }
161        }
162    }
163}
164
165const ROUTE_ALL: &[&str] = &[
166    "phase_dir",
167    "log_dir",
168    "work_dir",
169    "target",
170    "phase",
171    "runtime_root",
172    "shares_ro",
173    "shares_rw",
174];
175const ROUTE_BASIC: &[&str] = &["phase_dir", "log_dir", "work_dir", "target", "phase"];
176
177fn validate_route(t: &str, r: &Route, e: &mut Vec<String>) {
178    let extra = !r.args.is_empty()
179        || !r.env.is_empty()
180        || r.runtime_root.is_some()
181        || !r.shares_ro.is_empty()
182        || !r.shares_rw.is_empty()
183        || r.receipt_digest_env.is_some()
184        || r.phases != ["build"];
185    if r.kind == "none" && extra {
186        e.push(format!(
187            "targets.{t}.route: args, env, runtime_root, shares, receipt_digest_env and phases need kind command"
188        ));
189    }
190    for p in &r.phases {
191        if !matches!(p.as_str(), "build" | "sources") {
192            e.push(format!(
193                "targets.{t}.route.phases: expected build or sources, found `{p}`"
194            ));
195        }
196    }
197    if r.phases.is_empty() {
198        e.push(format!("targets.{t}.route.phases: must not be empty"));
199    }
200    for a in &r.args {
201        check_placeholders(&format!("targets.{t}.route.args"), a, ROUTE_ALL, e);
202    }
203    for (k, v) in &r.env {
204        check_placeholders(&format!("targets.{t}.route.env.{k}"), v, ROUTE_ALL, e);
205    }
206    for s in r.shares_ro.iter().chain(&r.shares_rw) {
207        check_placeholders(&format!("targets.{t}.route.shares"), s, ROUTE_BASIC, e);
208    }
209    if let Some(n) = &r.receipt_digest_env {
210        if !env_name_ok(n) {
211            e.push(format!(
212                "targets.{t}.route.receipt_digest_env: use letters, digits and `_`"
213            ));
214        }
215    }
216}
217
218fn validate_select(t: &str, s: &Select, e: &mut Vec<String>) {
219    if !s.option.starts_with("--") || s.option.len() < 3 || s.option.contains(['=', ' ']) {
220        let bare = s.option.trim_start_matches('-');
221        let hint = if bare.is_empty() || bare.contains(['=', ' ']) {
222            String::new()
223        } else {
224            format!("; write `--{bare}`")
225        };
226        e.push(format!(
227            "targets.{t}.select.option: expected a long option with its leading dashes, such as `--name`, found `{}`{hint}",
228            s.option
229        ));
230    }
231    if s.value.trim().is_empty() {
232        e.push(format!("targets.{t}.select.value: must not be empty"));
233    }
234    if s.separator.is_empty() {
235        e.push(format!("targets.{t}.select.separator: must not be empty"));
236    } else if s.value.contains(&s.separator) {
237        e.push(format!(
238            "targets.{t}.select.value: contains the separator `{}`",
239            s.separator
240        ));
241    }
242    if !matches!(s.when_absent.as_str(), "all" | "none") {
243        e.push(format!(
244            "targets.{t}.select.when_absent: expected all or none, found `{}`",
245            s.when_absent
246        ));
247    }
248}
249
250/// The forms EESSI accepts: `cpu_target` as `<arch>/<uarch>` or
251/// `<arch>/<vendor>/<uarch>`, `accel_target` as EESSI-extend matches it.
252fn validate_eessi_target(t: &Target, e: &mut Vec<String>) {
253    if let Some(c) = &t.cpu_target {
254        let parts: Vec<&str> = c.split('/').collect();
255        let ok = matches!(parts[0], "x86_64" | "aarch64" | "riscv64" | "ppc64le")
256            && (2..=3).contains(&parts.len())
257            && parts
258                .iter()
259                .all(|p| !p.is_empty() && !p.contains(char::is_whitespace));
260        if !ok {
261            e.push(format!(
262                "targets.{}.cpu_target: expected an EESSI CPU subdirectory such as `x86_64/amd/zen4` or `aarch64/neoverse_v1`, found `{c}`",
263                t.name
264            ));
265        }
266    }
267    if let Some(a) = t.accel_target.as_deref().filter(|a| !a.is_empty()) {
268        let nvidia = a
269            .strip_prefix("accel/nvidia/cc")
270            .is_some_and(|cc| !cc.is_empty() && cc.bytes().all(|b| b.is_ascii_digit()));
271        let amd = a.strip_prefix("accel/amd/gfx").is_some_and(|g| {
272            !g.is_empty()
273                && g.bytes()
274                    .all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
275        });
276        if !(nvidia || amd) {
277            e.push(format!(
278                "targets.{}.accel_target: expected `accel/nvidia/cc<digits>` or `accel/amd/gfx<hex>`, found `{a}`",
279                t.name
280            ));
281        }
282    }
283}
284
285/// Semantic validation. Returns every problem found.
286pub fn validate(site: &Site, lists_dir: Option<&Path>) -> Vec<String> {
287    let mut e = Vec::new();
288    if site.schema_version != 1 {
289        e.push(format!(
290            "schema_version: expected 1, found {}",
291            site.schema_version
292        ));
293    }
294    if site.kind != "site" {
295        e.push(format!("kind: expected \"site\", found \"{}\"", site.kind));
296    }
297    if !name_ok(&site.site.name) {
298        e.push("site.name: use letters, digits, `.`, `_` and `-`".into());
299    }
300    if let Some(p) = &site.site.project {
301        if !name_ok(p) {
302            e.push("site.project: use letters, digits, `.`, `_` and `-`".into());
303        }
304    }
305    if let Some(t) = &site.site.tools {
306        for (k, s) in [
307            ("eb_stack", &t.eb_stack),
308            ("eb_keep_logs", &t.eb_keep_logs),
309            ("eb_staged_rebuild", &t.eb_staged_rebuild),
310        ] {
311            if let Some(v) = s.as_ref().and_then(|s| s.min_version.as_ref()) {
312                if parse_version(v).is_none() {
313                    e.push(format!(
314                        "site.tools.{k}.min_version: `{v}` is not dotted numbers"
315                    ));
316                }
317            }
318        }
319    }
320    match site.scheduler.kind.as_str() {
321        "slurm" | "local" => {}
322        k => e.push(format!(
323            "scheduler.kind: expected slurm or local, found `{k}`"
324        )),
325    }
326    if site.scheduler.launch.trim().is_empty() {
327        e.push("scheduler.launch: must not be empty".into());
328    }
329    check_placeholders(
330        "scheduler.job_name_template",
331        &site.scheduler.job_name_template,
332        PLACEHOLDERS,
333        &mut e,
334    );
335
336    if site.targets.is_empty() {
337        e.push("targets: at least one target is required".into());
338    }
339    let mut seen = BTreeSet::new();
340    for t in &site.targets {
341        if !name_ok(&t.name) {
342            e.push(format!("targets: invalid name `{}`", t.name));
343        } else if matches!(t.name.as_str(), "." | "..") {
344            e.push(format!(
345                "targets: invalid name `{}`; a target name is a directory name, of its log directory and wherever {{target}} expands",
346                t.name
347            ));
348        }
349        if !seen.insert(t.name.clone()) {
350            e.push(format!("targets: duplicate name `{}`", t.name));
351        }
352        if let Some(r) = &t.route {
353            match r.kind.as_str() {
354                "none" => {}
355                "command" => {
356                    if r.command.as_deref().is_none_or(|c| c.trim().is_empty()) {
357                        e.push(format!(
358                            "targets.{}.route: kind command needs `command`",
359                            t.name
360                        ));
361                    }
362                }
363                k => e.push(format!(
364                    "targets.{}.route.kind: expected none or command, found `{k}`",
365                    t.name
366                )),
367            }
368            validate_route(&t.name, r, &mut e);
369        }
370        if let Some(s) = &t.select {
371            validate_select(&t.name, s, &mut e);
372        }
373        if site.eessi_on().is_some() {
374            validate_eessi_target(t, &mut e);
375        }
376        if let Some(dir) = lists_dir {
377            for l in &t.build_lists {
378                if !dir.join(l).is_file() {
379                    e.push(format!(
380                        "targets.{}.build_lists: `{}` not found in {}",
381                        t.name,
382                        l,
383                        dir.display()
384                    ));
385                }
386            }
387        }
388    }
389
390    let fs = &site.filesystems;
391    if !matches!(fs.export_install_vars.as_str(), "single" | "split") {
392        e.push(format!(
393            "filesystems.export_install_vars: expected single or split, found `{}`",
394            fs.export_install_vars
395        ));
396    }
397    if site.eessi_on().is_some_and(|es| es.site_install) && fs.export_install_vars != "split" {
398        for t in &site.targets {
399            let staged = site
400                .rebuild_on()
401                .is_some_and(|r| t.staged.unwrap_or(r.staged));
402            if staged && (t.software_root.is_none() || t.modules_root.is_none()) {
403                e.push(format!(
404                    "targets.{}: staged rebuilds with modules.eessi.site_install need software_root and modules_root; EESSI-extend installs into <site prefix>/versions/<release>/software/linux/<cpu_target>, so set them to its software and modules directories",
405                    t.name
406                ));
407            }
408        }
409    }
410    for (k, v) in [
411        ("scratch", &fs.scratch),
412        ("tmp", &fs.tmp),
413        ("build_path", &fs.build_path),
414        ("install_root", &fs.install_root),
415        ("log_root", &fs.log_root),
416    ] {
417        if v.trim().is_empty() {
418            e.push(format!("filesystems.{k}: must not be empty"));
419        }
420    }
421    check_placeholders("filesystems.build_path", &fs.build_path, PER_TARGET, &mut e);
422    for p in &fs.source_paths {
423        check_placeholders("filesystems.source_paths", p, PER_TARGET, &mut e);
424    }
425    let shared = [
426        ("scratch", Some(&fs.scratch)),
427        ("tmp", Some(&fs.tmp)),
428        ("install_root", Some(&fs.install_root)),
429        ("log_root", Some(&fs.log_root)),
430        ("shard_dir", fs.shard_dir.as_ref()),
431        ("configs_repo", fs.configs_repo.as_ref()),
432    ];
433    for (k, v) in shared {
434        if v.is_some_and(|v| v.contains("{target}")) {
435            e.push(format!(
436                "filesystems.{k}: {{target}} expands in filesystems.build_path, filesystems.source_paths and rebuild.state_root only"
437            ));
438        }
439    }
440
441    if let Some(a) = &site.admission {
442        if !matches!(a.lock_kind.as_str(), "flock" | "posix") {
443            e.push(format!(
444                "admission.lock_kind: expected flock or posix, found `{}`",
445                a.lock_kind
446            ));
447        }
448        if a.enabled && a.default_footprint.is_none() {
449            e.push("admission.default_footprint: required when admission is enabled".into());
450        }
451        let env_ok = !a.job_id_env.is_empty()
452            && a.job_id_env
453                .chars()
454                .all(|c| c.is_ascii_alphanumeric() || c == '_');
455        if !env_ok {
456            e.push("admission.job_id_env: use letters, digits and `_`".into());
457        }
458        if a.attempts == 0 {
459            e.push("admission.attempts: must be at least 1".into());
460        }
461    }
462    if let Some(s) = &site.shards {
463        for n in &s.installed_modules_dirs_from_env {
464            if !env_name_ok(n) {
465                e.push(format!(
466                    "shards.installed_modules_dirs_from_env: `{n}` is not a variable name"
467                ));
468            }
469        }
470        if s.enabled && s.count >= 2 && s.easyconfigs.is_empty() {
471            e.push("shards.easyconfigs: at least one tree is required when count >= 2".into());
472        }
473    }
474    for m in site
475        .modules
476        .init
477        .iter()
478        .filter(|m| m.contains(char::is_whitespace))
479    {
480        e.push(format!(
481            "modules.init: `{m}` has white space; an entry is one module name, so give each module its own entry"
482        ));
483    }
484    let shell = &site.modules.shell;
485    let shell_name = Path::new(shell).file_name().and_then(|n| n.to_str());
486    if !shell_name.is_some_and(|n| MODULE_SHELLS.contains(&n)) {
487        let (last, rest) = MODULE_SHELLS
488            .split_last()
489            .expect("MODULE_SHELLS is not empty");
490        e.push(format!(
491            "modules.shell: expected a POSIX shell that runs the module wrapper, one of {} or {last}, by name or by path, found `{shell}`",
492            rest.join(", ")
493        ));
494    }
495    // eb-staged-rebuild copies the one `target` of a ledger configuration into
496    // every record it writes.
497    if let Some(r) = site.rebuild_on() {
498        let mut first: BTreeMap<&str, &str> = BTreeMap::new();
499        for t in site.targets.iter().filter(|t| t.staged.unwrap_or(r.staged)) {
500            let Some(c) = t.ledger_config.as_deref().or(r.ledger_config.as_deref()) else {
501                continue;
502            };
503            match first.get(c) {
504                Some(other) => e.push(format!(
505                    "targets.{}: records staged rebuilds through {c} as targets.{other} does, under the one target that file names; set ledger_config in each target",
506                    t.name
507                )),
508                None => {
509                    first.insert(c, &t.name);
510                }
511            }
512        }
513    }
514    // eb-staged-rebuild locks a live tree through its state root, so one tree
515    // takes one state root.
516    if let Some(r) = site.rebuild_on().filter(|r| {
517        r.state_root
518            .as_deref()
519            .is_some_and(|s| s.contains("{target}"))
520    }) {
521        let mut trees: BTreeMap<String, &str> = BTreeMap::new();
522        for t in site.targets.iter().filter(|t| t.staged.unwrap_or(r.staged)) {
523            let scope = Scope {
524                site,
525                site_file: None,
526                target: t,
527                build_type: None,
528                run_id: String::new(),
529                log_stamp: String::new(),
530            };
531            let tree = scope.software_root().trim_end_matches('/').to_string();
532            match trees.get(&tree) {
533                Some(other) => e.push(format!(
534                    "targets.{}: takes staged rebuilds of the live tree {tree} as targets.{other} does, and rebuild.state_root has {{target}}, which gives that tree two state roots and two locks; drop {{target}} from state_root or give each target its own software_root",
535                    t.name
536                )),
537                None => {
538                    trees.insert(tree, &t.name);
539                }
540            }
541        }
542    }
543    if let Some(r) = &site.rebuild {
544        if let Some(s) = &r.state_root {
545            check_placeholders("rebuild.state_root", s, PER_TARGET, &mut e);
546        }
547        if !matches!(
548            r.backend.as_str(),
549            "auto" | "bwrap" | "userns" | "installpath"
550        ) {
551            e.push(format!(
552                "rebuild.backend: expected auto, bwrap, userns or installpath, found `{}`",
553                r.backend
554            ));
555        }
556    }
557    if let Some(r) = site.logs.as_ref().and_then(|l| l.rotate.as_ref()) {
558        if let Some(d) = r.delete_after_days.filter(|d| *d <= r.compress_after_days) {
559            e.push(format!(
560                "logs.rotate.delete_after_days: must be greater than compress_after_days ({}), found {d}",
561                r.compress_after_days
562            ));
563        }
564    }
565    if let Some(c) = &site.caches {
566        let mut seen = BTreeSet::new();
567        for ct in &c.targets {
568            if !site.targets.iter().any(|t| t.name == ct.target) {
569                e.push(format!("caches.targets: `{}` is not a target", ct.target));
570            }
571            if !seen.insert(ct.target.clone()) {
572                e.push(format!("caches.targets: duplicate target `{}`", ct.target));
573            }
574        }
575    }
576    if let Some(l) = &site.licences {
577        if l.enabled && l.enforce {
578            if l.groups.is_empty() && l.below_version.is_empty() && l.exempt.is_empty() {
579                e.push(
580                    "licences: enforce is set but no group, threshold or exemption is configured"
581                        .into(),
582                );
583            }
584            let required: &[String] = l.required.as_ref().map_or(&[], |r| &r.software);
585            for n in required {
586                if !l.groups.contains_key(n)
587                    && !l.below_version.contains_key(n)
588                    && !l.exempt.contains(n)
589                {
590                    e.push(format!(
591                        "licences.required: `{n}` has no group, threshold or exemption"
592                    ));
593                }
594            }
595        }
596        for (n, v) in &l.below_version {
597            if parse_version(v).is_none() {
598                e.push(format!(
599                    "licences.below_version.{n}: `{v}` is not dotted numbers"
600                ));
601            }
602            if !l.groups.contains_key(n) {
603                e.push(format!(
604                    "licences.below_version.{n}: no group set for `{n}`"
605                ));
606            }
607        }
608    }
609    e
610}
611
612impl Site {
613    /// Admission section when active.
614    pub fn admission_on(&self) -> Option<&Admission> {
615        self.admission.as_ref().filter(|a| a.enabled)
616    }
617    /// Shard section when it plans shards.
618    pub fn shards_on(&self) -> Option<&Shards> {
619        self.shards.as_ref().filter(|s| s.enabled && s.count >= 2)
620    }
621    /// Sources section when it prefetches.
622    pub fn sources_on(&self) -> Option<&Sources> {
623        self.sources.as_ref().filter(|s| s.enabled && s.prefetch)
624    }
625    /// Caches section when active.
626    pub fn caches_on(&self) -> Option<&Caches> {
627        self.caches.as_ref().filter(|c| c.enabled)
628    }
629    /// Logs section when active.
630    pub fn logs_on(&self) -> Option<&Logs> {
631        self.logs.as_ref().filter(|l| l.enabled)
632    }
633    /// Rebuild section when active and `staged` is set in it or on a target.
634    pub fn rebuild_on(&self) -> Option<&Rebuild> {
635        self.rebuild.as_ref().filter(|r| {
636            r.enabled && (r.staged || self.targets.iter().any(|t| t.staged == Some(true)))
637        })
638    }
639    /// Licences section when active and enforced.
640    pub fn licences_on(&self) -> Option<&Licences> {
641        self.licences.as_ref().filter(|l| l.enabled && l.enforce)
642    }
643    /// `[modules.eessi]` when active.
644    pub fn eessi_on(&self) -> Option<&Eessi> {
645        self.modules.eessi.as_ref().filter(|e| e.enabled)
646    }
647    /// The target called `name`.
648    ///
649    /// # Errors
650    ///
651    /// A usage [`Fail`] that lists the known targets when none has the name.
652    pub fn target(&self, name: &str) -> Result<&Target, Fail> {
653        self.targets.iter().find(|t| t.name == name).ok_or_else(|| {
654            Fail::usage(format!(
655                "unknown target `{name}`; known: {}",
656                self.targets
657                    .iter()
658                    .map(|t| t.name.as_str())
659                    .collect::<Vec<_>>()
660                    .join(", ")
661            ))
662        })
663    }
664    /// The `{project}` of job names: `site.project`, else `site.name`.
665    pub fn project(&self) -> &str {
666        self.site.project.as_deref().unwrap_or(&self.site.name)
667    }
668}
669
670#[cfg(test)]
671mod override_tests {
672    use super::*;
673
674    const BASE: &str = include_str!("../templates/small-cluster.toml");
675
676    fn set(pairs: &[(&str, &str)]) -> Result<Site, Fail> {
677        let v: Vec<(String, String)> = pairs
678            .iter()
679            .map(|(k, v)| (k.to_string(), v.to_string()))
680            .collect();
681        parse_with_overrides(BASE, &v)
682    }
683
684    #[test]
685    fn no_overrides_is_plain_parse() {
686        let a = set(&[]).unwrap();
687        let b = parse(BASE).unwrap();
688        assert_eq!(
689            serde_json::to_string(&a).unwrap(),
690            serde_json::to_string(&b).unwrap()
691        );
692    }
693
694    #[test]
695    fn sets_strings_and_arrays() {
696        let s = set(&[
697            ("EB_PIPELINE__FILESYSTEMS__SCRATCH", "/scratch/other"),
698            (
699                "EB_PIPELINE__FILESYSTEMS__SOURCE_PATHS",
700                r#"["/opt/a", "/opt/b"]"#,
701            ),
702            ("EB_PIPELINE__SITE__STACK_GENERATION", "2027a"),
703        ])
704        .unwrap();
705        assert_eq!(s.filesystems.scratch, "/scratch/other");
706        assert_eq!(s.filesystems.source_paths, vec!["/opt/a", "/opt/b"]);
707        assert_eq!(s.site.stack_generation.as_deref(), Some("2027a"));
708    }
709
710    #[test]
711    fn refuses_unknown_key_and_wrong_type() {
712        assert_eq!(
713            set(&[("EB_PIPELINE__SITE__NO_SUCH", "x")])
714                .unwrap_err()
715                .code,
716            2
717        );
718        assert_eq!(
719            set(&[("EB_PIPELINE__FILESYSTEMS__SOURCE_PATHS", "7")])
720                .unwrap_err()
721                .code,
722            2
723        );
724    }
725
726    #[test]
727    fn refuses_tables_arrays_of_tables_and_bad_names() {
728        for (k, v) in [
729            ("EB_PIPELINE__TARGETS__NAME", "x"),
730            ("EB_PIPELINE__TARGETS", "x"),
731            ("EB_PIPELINE__SITE", "x"),
732            ("EB_PIPELINE__SITE____NAME", "x"),
733            ("EB_PIPELINE__SITE__NA-ME", "x"),
734        ] {
735            assert_eq!(set(&[(k, v)]).unwrap_err().code, 2, "{k}");
736        }
737    }
738
739    #[test]
740    fn order_of_the_environment_does_not_matter() {
741        let a = set(&[
742            ("EB_PIPELINE__SITE__NAME", "one"),
743            ("EB_PIPELINE__SITE__PROJECT", "p"),
744        ])
745        .unwrap();
746        let b = set(&[
747            ("EB_PIPELINE__SITE__PROJECT", "p"),
748            ("EB_PIPELINE__SITE__NAME", "one"),
749        ])
750        .unwrap();
751        assert_eq!(
752            serde_json::to_string(&a).unwrap(),
753            serde_json::to_string(&b).unwrap()
754        );
755    }
756}
757
758#[cfg(test)]
759mod route_doc_tests {
760    use super::*;
761    use std::collections::BTreeSet;
762
763    /// The placeholders that the schema text of a route key names.
764    fn named(key: &str) -> BTreeSet<&'static str> {
765        let doc = Route::FIELDS.iter().find(|f| f.key == key).unwrap().doc;
766        let mut out = BTreeSet::new();
767        let mut rest = doc;
768        while let Some(i) = rest.find('{') {
769            let j = rest[i..].find('}').unwrap();
770            out.insert(&rest[i + 1..i + j]);
771            rest = &rest[i + j + 1..];
772        }
773        out
774    }
775
776    #[test]
777    fn route_texts_name_the_placeholders_check_accepts() {
778        assert_eq!(named("args"), ROUTE_ALL.iter().copied().collect());
779        assert_eq!(named("shares_ro"), ROUTE_BASIC.iter().copied().collect());
780    }
781}