ktstr/test_support/eval/
scheduler.rs

1//! Scheduler-binary resolution: maps a `SchedulerSpec` to a path plus a
2//! `ResolveSource` provenance (the orchestrator manifest, env override,
3//! `$PATH` lookup, or on-demand workspace build) and dedups include-file
4//! lists. Split out of eval/mod.rs to keep the module under the size ceiling.
5
6use super::*;
7
8/// Dedupe a resolved include-file list produced by unioning the
9/// per-payload `include_files` specs through
10/// [`crate::cli::resolve_include_files`] and appending the scheduler
11/// config file entry. Each input tuple carries an `origin` label
12/// (e.g. `"declarative"`, `"scheduler config_file"`) that is
13/// surfaced in conflict diagnostics so the operator can trace which
14/// declaration contributed each side of a collision.
15///
16/// Policy:
17///
18/// - Identical `(archive_path, host_path)` pairs collapse silently
19///   (the same host file declared twice is harmless). Comparison
20///   uses [`Path::canonicalize`] so two spellings of the same real
21///   file (e.g. `./fio` vs `/usr/bin/fio` when `./fio` is a
22///   symlink) are treated as equal. Canonicalization failure
23///   (missing path, permission denied) falls back to byte-for-byte
24///   PathBuf comparison; literal duplicates still collapse, and a
25///   genuine conflict still surfaces.
26/// - Two entries sharing an `archive_path` but resolving to
27///   different canonical `host_path`s are a genuine ambiguity — a
28///   scheduler's and a payload's `include_files` both claiming
29///   `include-files/config.json` but pointing at different host
30///   paths means one of the two would silently overwrite the other
31///   in the initramfs. Bail with a diagnostic naming both host
32///   paths AND their origin labels so the author can rename one
33///   archive slot.
34///
35/// Case-sensitivity: `archive_path` keys are compared
36/// byte-for-byte (via `BTreeMap<String, _>`), so on a case-
37/// insensitive host filesystem (macOS HFS+, NTFS with the
38/// `case-insensitive` mount flag) two archive paths spelled
39/// `include-files/Helper` and `include-files/helper` are treated
40/// as distinct here even though the host filesystem would
41/// conflate them. This is intentional: `archive_path` is the
42/// path inside the guest initramfs, which is tmpfs / ext4-
43/// equivalent (always case-sensitive), so the guest-side
44/// identity is what governs.
45///
46/// Order is stabilized via `BTreeMap`'s sorted iteration so the
47/// emitted slice is deterministic regardless of which caller
48/// appended first. Extracted from `run_ktstr_test_inner` so the
49/// policy can be unit-tested without constructing a whole
50/// KtstrTestEntry + VmBuilder.
51pub(crate) fn dedupe_include_files(
52    resolved: &[(String, std::path::PathBuf, &'static str)],
53) -> Result<Vec<(String, std::path::PathBuf)>> {
54    let mut seen: std::collections::BTreeMap<String, (std::path::PathBuf, &'static str)> =
55        std::collections::BTreeMap::new();
56    for (archive, host, origin) in resolved {
57        if let Some((existing, existing_origin)) = seen.get(archive) {
58            // Canonicalize both sides before comparing so
59            // symlink-equivalent spellings collapse. A failed
60            // canonicalize (missing path, permission denied) falls
61            // back to the uncanonicalized value so the structural
62            // compare still runs — literal duplicates still collapse
63            // and genuine conflicts still surface.
64            let existing_canon = existing.canonicalize().unwrap_or_else(|_| existing.clone());
65            let host_canon = host.canonicalize().unwrap_or_else(|_| host.clone());
66            if existing_canon != host_canon {
67                anyhow::bail!(
68                    "include_files conflict for archive path '{archive}': sources disagree \
69                     on host path ({} [origin: {existing_origin}] vs {} [origin: {origin}]). \
70                     Remove the duplicate declaration or rename one of the archive entries.",
71                    existing.display(),
72                    host.display(),
73                );
74            }
75        } else {
76            seen.insert(archive.clone(), (host.clone(), origin));
77        }
78    }
79    Ok(seen
80        .into_iter()
81        .map(|(archive, (host, _origin))| (archive, host))
82        .collect())
83}
84
85/// Provenance of a scheduler binary returned by [`resolve_scheduler`].
86///
87/// Each variant identifies the resolution branch that produced the
88/// path, so downstream tooling (sidecar, cache-key construction, log
89/// lines) can distinguish "we located an *existing* binary whose git
90/// hash we don't control" from "we just built this binary in the
91/// declaring crate's workspace and therefore know its source commit
92/// matches that workspace's HEAD."
93///
94/// Only the [`AutoBuilt`](Self::AutoBuilt) variant carries an in-child
95/// source-commit guarantee. A manifest artifact was elected by the parent and
96/// can represent either a workspace build or the global operator override, so
97/// the child records that fact without guessing its source commit.
98///
99/// `Eevdf` / `KernelBuiltin` / `Path` resolutions do not go through
100/// the `Discover` flow:
101/// - `Eevdf` / `KernelBuiltin` → [`NotFound`](Self::NotFound) (no
102///   user-space binary involved; the tuple's `Option<PathBuf>` is
103///   `None`).
104/// - `Path(p)` → [`Path`](Self::Path) (the caller named the binary
105///   explicitly in the test entry — no env-var or filesystem search
106///   runs).
107///
108/// The variant ordering in the enum mirrors the resolution order in
109/// [`resolve_scheduler`] so a reviewer can scan both lists in lockstep.
110#[derive(Debug, Clone, Copy, PartialEq, Eq)]
111pub enum ResolveSource {
112    /// Resolved through the authoritative parent-written scheduler artifact
113    /// manifest. No per-child search or Cargo invocation ran.
114    Manifest,
115    /// Resolved via the literal path the caller supplied as
116    /// `SchedulerSpec::Path(p)`. No env-var or filesystem search
117    /// involved — the path arrived in the test entry directly.
118    /// Trusted to the extent the caller trusts the argument; git-
119    /// hash provenance is UNKNOWN to this process.
120    Path,
121    /// Resolved via the `KTSTR_SCHEDULER` environment variable on the
122    /// `SchedulerSpec::Discover` arm. Trusted to the extent the
123    /// caller trusts the variable; git-hash provenance is UNKNOWN
124    /// to this process.
125    EnvVar,
126    /// Resolved via a `$PATH` lookup. Only produced when
127    /// `KTSTR_CARGO_TEST_MODE` is active and a binary by the
128    /// requested name was found on the user's `$PATH` ahead of the
129    /// on-demand workspace build. Git-hash provenance UNKNOWN — the
130    /// binary on PATH may be a system-wide install, a prior build,
131    /// or a custom one the user staged for this run.
132    PathLookup,
133    /// Built on demand by [`crate::build_and_find_binary`] inside this
134    /// process, in the declaring crate's workspace. The build targets
135    /// that workspace's HEAD by construction — the ONLY variant where
136    /// the source commit is known to match the workspace tree the
137    /// tests run from.
138    AutoBuilt,
139    /// No user-space binary path was produced. Returned for
140    /// `SchedulerSpec::Eevdf` and `SchedulerSpec::KernelBuiltin` (the
141    /// kernel supplies the scheduler — no binary to locate). The
142    /// tuple's `Option<PathBuf>` is always `None` for this variant.
143    NotFound,
144}
145
146impl ResolveSource {
147    /// Stable snake_case tag for the sidecar `resolve_source` field and
148    /// the `stats` `--resolve-source` filter — the string analog of the
149    /// variant, mirroring the `run_source` tag convention so the
150    /// persisted JSON shape does not depend on this enum's Rust
151    /// representation. Variant order matches the resolution order.
152    pub const fn as_str(&self) -> &'static str {
153        match self {
154            Self::Manifest => "manifest",
155            Self::Path => "path",
156            Self::EnvVar => "env_var",
157            Self::PathLookup => "path_lookup",
158            Self::AutoBuilt => "auto_built",
159            Self::NotFound => "not_found",
160        }
161    }
162}
163
164/// Walk `$PATH` directories in order looking for an executable
165/// named `name`. Returns the first match that is a regular file
166/// with at least one execute permission bit set. None when `PATH`
167/// is unset, empty, or contains no matching executable.
168///
169/// Mirrors the semantics of `which(1)` and the
170/// `crate::export::search_path_for` helper without pulling in a
171/// new crate dependency. Used by [`resolve_scheduler`] only when
172/// `KTSTR_CARGO_TEST_MODE` is active, so an installed scheduler
173/// resolves without a workspace build; the orchestrated path skips
174/// it and always builds so gauntlet runs land on the workspace-built
175/// scheduler revision rather than a system-wide install on PATH.
176fn find_on_path(name: &str) -> Option<PathBuf> {
177    use std::os::unix::fs::PermissionsExt;
178    let path_var = std::env::var_os("PATH")?;
179    for dir in std::env::split_paths(&path_var) {
180        let candidate = dir.join(name);
181        if !candidate.is_file() {
182            continue;
183        }
184        let executable = candidate
185            .metadata()
186            .map(|m| m.permissions().mode() & 0o111 != 0)
187            .unwrap_or(false);
188        if executable {
189            return Some(candidate);
190        }
191    }
192    None
193}
194
195/// Resolve every entry in `entry.staged_schedulers` via a caller-
196/// supplied resolver, propagating resolver errors strictly (suitable
197/// for the primary-dispatch path where a missing staged binary is a
198/// hard failure operator should see at dispatch time, not later at
199/// Op-dispatch inside the VM). KernelBuiltin / Eevdf staged entries
200/// — whose resolver returns `Ok(None)` — are silently dropped:
201/// they have no binary to stage and the lifecycle ops resolve them
202/// via shell-script slots instead.
203///
204/// Returns `(name, resolved_host_path, sched_args)` tuples in the
205/// SAME order as `entry.staged_schedulers` iteration. Ordering is
206/// load-bearing: the initramfs packer iterates the result
207/// to emit per-scheduler `/staging/schedulers/<name>/` archive
208/// entries, and parent-directory dependencies are encounter-order
209/// sensitive. Tests pin the order-preservation against a future
210/// refactor that uses `.collect::<HashMap<_,_>>().into_iter()`
211/// (would silently scramble).
212///
213/// `resolver` is a closure rather than a direct call to
214/// [`resolve_scheduler`] so unit tests can drive the order-
215/// preservation contract with a synthetic resolver that returns
216/// known paths without touching the host filesystem. It receives the
217/// whole staged [`Scheduler`](crate::test_support::Scheduler) so the
218/// production closure can forward `manifest_dir` to `resolve_scheduler`.
219pub(crate) fn resolve_staged_schedulers_strict<F>(
220    entry: &KtstrTestEntry,
221    mut resolver: F,
222) -> Result<Vec<(String, PathBuf, Vec<String>)>>
223where
224    F: FnMut(&crate::test_support::Scheduler) -> Result<Option<PathBuf>>,
225{
226    let mut out = Vec::with_capacity(entry.staged_schedulers.len());
227    for staged in entry.staged_schedulers {
228        let Some(host_path) = resolver(staged)? else {
229            continue;
230        };
231        out.push((
232            staged.name.to_string(),
233            host_path,
234            staged.sched_args.iter().map(|s| s.to_string()).collect(),
235        ));
236    }
237    Ok(out)
238}
239
240/// Resolve a scheduler binary from a `SchedulerSpec`.
241///
242/// Returns the resolved path (if any) paired with the
243/// [`ResolveSource`] naming the branch that produced it. The source is
244/// load-bearing for downstream provenance: only
245/// [`ResolveSource::AutoBuilt`] guarantees the binary matches the
246/// declaring crate's workspace tree; every other variant locates a
247/// pre-existing file whose git hash is UNKNOWN to this process.
248///
249/// `manifest_dir` is the declaring crate's `CARGO_MANIFEST_DIR` (from
250/// [`Scheduler::manifest_dir`](crate::test_support::Scheduler::manifest_dir)),
251/// forwarded to [`crate::build_and_find_binary`] so the on-demand
252/// `Discover` build runs in the scheduler's OWN workspace.
253///
254/// Variant mapping:
255/// - `Eevdf` / `KernelBuiltin { .. }` → `(None, NotFound)` (no
256///   user-space binary).
257/// - `Path(p)` → `(Some(p), Path)` (explicit caller-named path;
258///   validated for existence).
259/// - `Discover(name)` → four steps:
260///   1. exact parent manifest lookup
261///      ([`Manifest`](ResolveSource::Manifest)). Presence is authoritative:
262///      invalid or missing data is a hard error and cannot fall through.
263///   2. `KTSTR_SCHEDULER` env override
264///      ([`EnvVar`](ResolveSource::EnvVar)) — a global, name-agnostic
265///      binary path applying to every `Discover` scheduler.
266///   3. cargo-test mode only: `$PATH` lookup
267///      ([`PathLookup`](ResolveSource::PathLookup)), so an installed
268///      scheduler resolves without a workspace build.
269///   4. `cargo build -p <name>` in the declaring crate's workspace
270///      ([`AutoBuilt`](ResolveSource::AutoBuilt)), in BOTH modes.
271///
272///   Cargo owns freshness: it rebuilds when the scheduler's sources
273///   (incl. `src/bpf/*.bpf.c` via its build.rs) change, is a no-op when
274///   they are up to date, and fails when the scheduler cannot build. A
275///   failed build is a hard error, full stop — a scheduler that will
276///   not build is a failed test, never a silently-stale pre-built
277///   binary. The error carries the `SchedulerBuildRefused`
278///   marker so dispatch forces a hard FAIL even under `expect_err`: a
279///   host-side build fault must not invert to PASS. The `$PATH` lookup
280///   is gated to cargo-test mode so gauntlet runs always land on the
281///   workspace-built scheduler revision rather than a system-wide
282///   install.
283pub fn resolve_scheduler(
284    spec: &SchedulerSpec,
285    manifest_dir: &str,
286) -> Result<(Option<PathBuf>, ResolveSource)> {
287    if matches!(spec, SchedulerSpec::Discover(_) | SchedulerSpec::Path(_)) {
288        match crate::scheduler_artifact::scheduler_artifact_from_env(None, spec, manifest_dir) {
289            Ok(Some(path)) => return Ok((Some(path), ResolveSource::Manifest)),
290            Ok(None) => {}
291            Err(error) => {
292                return Err(error
293                    .context(FrameworkInfrastructureFailure)
294                    .context("ktstr_test: parent scheduler artifact handoff is invalid"));
295            }
296        }
297    }
298
299    match spec {
300        SchedulerSpec::Eevdf | SchedulerSpec::KernelBuiltin { .. } => {
301            Ok((None, ResolveSource::NotFound))
302        }
303        SchedulerSpec::Path(p) => {
304            let path = PathBuf::from(p);
305            anyhow::ensure!(
306                path.exists(),
307                "scheduler binary at '{p}' does not exist on disk. \
308                 SchedulerSpec::Path treats its argument as an \
309                 already-built binary — build the scheduler first \
310                 (e.g. cargo build -p scx_<name>) and pass its \
311                 target/debug/scx_<name> path, or correct the path if \
312                 it has shifted."
313            );
314            Ok((Some(path), ResolveSource::Path))
315        }
316        SchedulerSpec::Discover(name) => {
317            // 2. KTSTR_SCHEDULER env override (global / name-agnostic —
318            // applies to every Discover scheduler regardless of name).
319            if let Ok(p) = std::env::var(crate::KTSTR_SCHEDULER_ENV) {
320                let path = PathBuf::from(&p);
321                if path.exists() {
322                    return Ok((Some(path), ResolveSource::EnvVar));
323                }
324            }
325
326            // 3. cargo-test mode only: $PATH lookup, so a user who
327            // installed the scheduler on PATH can run the test without a
328            // workspace build. Gated to cargo-test mode — the
329            // orchestrated path skips it and always builds so gauntlet
330            // runs land on the workspace-built scheduler revision, not a
331            // system-wide install.
332            if crate::cargo_test_mode::cargo_test_mode_active()
333                && let Some(found) = find_on_path(name)
334            {
335                return Ok((Some(found), ResolveSource::PathLookup));
336            }
337
338            // 4. Build the scheduler in its declaring crate's workspace.
339            // Cargo owns freshness: `cargo build -p {name}` rebuilds on
340            // source change, no-ops when fresh, and errors when the
341            // scheduler cannot build (or cargo is absent, or no bin
342            // artifact is produced). A build FAILURE is a hard error —
343            // there is no pre-built fallback: a scheduler that will not
344            // build is a failed test, not a reason to validate against a
345            // possibly-stale binary. Attach the SchedulerBuildRefused
346            // marker (inner) so dispatch forces a hard FAIL even under
347            // expect_err, then the operator-facing message (outer, shown
348            // first by {e:#}). build_and_find_binary's cargo-stderr stays
349            // innermost in the chain.
350            match crate::build_and_find_binary(name, manifest_dir) {
351                Ok(path) => Ok((Some(path), ResolveSource::AutoBuilt)),
352                Err(e) => Err(e
353                    .context(crate::test_support::eval::SchedulerBuildRefused)
354                    .context(format!(
355                        "ktstr_test: workspace build of scheduler '{name}' \
356                         failed; a scheduler that cannot be built is a failed \
357                         test. Fix the build."
358                    ))),
359            }
360        }
361    }
362}