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}