ktstr/scenario/payload_run.rs
1//! Runtime builder for launching a [`Payload`] from a test body.
2//!
3//! `ctx.payload(&X)` returns a [`PayloadRun`] whose chainable
4//! methods configure args, checks, and cgroup placement before the
5//! terminal `.run()` (foreground) or `.spawn()` (background)
6//! executes the binary inside the guest VM.
7//!
8//! `.run()` blocks until the child exits and returns
9//! `Result<(AssertResult, PayloadMetrics)>`. The builder is a pure
10//! guest-side std::process::Child wrapper — no cross-VM proxy.
11//!
12//! `PayloadKind::Scheduler` payloads are rejected at `.run()`:
13//! schedulers are launched by the framework at test start, not by
14//! test-body invocation. Only `PayloadKind::Binary` payloads are
15//! runnable via this builder.
16//!
17//! Args composition:
18//! 1. `payload.default_args` unless `.clear_args()` was called.
19//! 2. Plus any runtime `.arg(...)` / `.args(...)` appends.
20//!
21//! Checks composition is identical in shape.
22//!
23//! # Stdout-primary, stderr-fallback metric extraction
24//!
25//! The extraction pipeline runs `extract_metrics`
26//! against **stdout first**. When that returns an empty metric set
27//! AND stderr is non-empty, the extractor retries against stderr.
28//! This preserves the stdout-primary contract for well-behaved
29//! binaries (noisy stderr never corrupts the metric stream) while
30//! still handling payloads that emit their structured output only on
31//! stderr — e.g. schbench's default percentile tables via
32//! `show_latencies` → `fprintf(stderr, ...)`. The two streams are
33//! never merged: concurrent drain threads for stdout/stderr provide
34//! no ordering guarantee, so interleaving would corrupt any document
35//! whose bytes span both streams.
36//!
37//! Stderr is still forwarded verbatim into the exit-code-mismatch
38//! detail produced by [`MetricCheck::ExitCodeEq`] (see the
39//! `format_exit_mismatch` path) so failing binaries surface their
40//! error output directly.
41
42use std::borrow::Cow;
43use std::path::PathBuf;
44use std::sync::OnceLock;
45use std::sync::atomic::{AtomicUsize, Ordering};
46use std::thread::ThreadId;
47
48use std::time::Duration;
49
50use anyhow::{Context, Result, anyhow};
51
52use crate::assert::{AssertDetail, AssertResult, DetailKind};
53use crate::scenario::Ctx;
54use crate::test_support::{
55 Metric, MetricCheck, Payload, PayloadKind, PayloadMetrics, extract_metrics,
56};
57
58/// Per-process monotonic counter for payload-invocation indexing.
59///
60/// Increments once per `.run()` / `.wait()` / `.kill()` /
61/// `.try_wait()` terminal call (whichever produces the
62/// [`crate::test_support::PayloadMetrics`] emission). Each guest VM is a fresh process, so
63/// the counter starts at 0 every test boot. Stamped onto
64/// [`PayloadMetrics::payload_index`] so the host preserves
65/// per-invocation identity independent of SHM emission order.
66///
67/// `Ordering::Relaxed` is sufficient: the counter's only consumer
68/// is the same thread that incremented (the emit happens inside
69/// the calling thread's `.run()` / `.wait()` / etc.), and the only
70/// invariant required is "every call returns a unique value." A
71/// future multi-thread caller would need `Ordering::SeqCst` only
72/// if it wanted total ordering; `fetch_add(1, Relaxed)` already
73/// guarantees unique values across threads.
74static PAYLOAD_INVOCATION_COUNTER: AtomicUsize = AtomicUsize::new(0);
75
76/// Allocate the next per-invocation index. See
77/// [`PAYLOAD_INVOCATION_COUNTER`] for the lifecycle and ordering
78/// rationale.
79fn next_payload_index() -> usize {
80 PAYLOAD_INVOCATION_COUNTER.fetch_add(1, Ordering::Relaxed)
81}
82
83/// Builder returned by [`Ctx::payload`](crate::scenario::Ctx).
84///
85/// Configure the run via chainable methods, then invoke `.run()`
86/// (foreground, blocking) or `.spawn()` (background) to execute the
87/// payload's binary inside the guest VM and receive the extracted
88/// [`crate::test_support::PayloadMetrics`] plus an [`AssertResult`] for any declared
89/// [`MetricCheck`]s.
90pub struct PayloadRun<'a> {
91 ctx: &'a Ctx<'a>,
92 payload: &'static Payload,
93 /// Effective argv. Initialized to `payload.default_args` on
94 /// construction; `.arg`/`.args` append, `.clear_args` truncates.
95 args: Vec<String>,
96 /// Effective check list. Initialized to `payload.default_checks`;
97 /// `.check` appends, `.clear_checks` truncates.
98 checks: Vec<MetricCheck>,
99 /// User-supplied relative cgroup name (from the `in_cgroup` arg). The
100 /// absolute path is resolved + validated at `.run()`/`.spawn()`.
101 /// [`Cow`] keeps static-name callers zero-alloc while still
102 /// accepting owned Strings from dynamic call sites.
103 cgroup: Option<Cow<'static, str>>,
104 /// Optional runtime bound for the foreground `.run()` path. `None`
105 /// means wait indefinitely; `Some(duration)` arms a deadline
106 /// watchdog that SIGKILLs the payload's process group if it has
107 /// not exited by the deadline. Set via [`timeout`](Self::timeout).
108 /// Ignored by `.spawn()` — background handles manage their own
109 /// lifetime via [`PayloadHandle::wait`] / `.kill()` / `.try_wait()`.
110 timeout: Option<Duration>,
111}
112
113impl std::fmt::Debug for PayloadRun<'_> {
114 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115 f.debug_struct("PayloadRun")
116 .field("payload", &self.payload.name)
117 .field("args_len", &self.args.len())
118 .field("checks_len", &self.checks.len())
119 .field("cgroup", &self.cgroup)
120 .field("timeout", &self.timeout)
121 .finish()
122 }
123}
124
125impl<'a> PayloadRun<'a> {
126 pub(crate) fn new(ctx: &'a Ctx<'a>, payload: &'static Payload) -> Self {
127 let args = payload.default_args.iter().map(|s| s.to_string()).collect();
128 let checks = payload.default_checks.to_vec();
129 Self {
130 ctx,
131 payload,
132 args,
133 checks,
134 cgroup: None,
135 timeout: None,
136 }
137 }
138
139 /// Append one CLI argument to the effective argv.
140 #[must_use = "builder methods consume self; bind the result"]
141 pub fn arg(mut self, arg: impl Into<String>) -> Self {
142 self.args.push(arg.into());
143 self
144 }
145
146 /// Append multiple CLI arguments to the effective argv.
147 #[must_use = "builder methods consume self; bind the result"]
148 pub fn args<I, S>(mut self, args: I) -> Self
149 where
150 I: IntoIterator<Item = S>,
151 S: Into<String>,
152 {
153 self.args.extend(args.into_iter().map(Into::into));
154 self
155 }
156
157 /// Wipe ALL args (both `payload.default_args` and any prior
158 /// `.arg()` calls). Subsequent `.arg()` calls start from empty.
159 #[must_use = "builder methods consume self; bind the result"]
160 pub fn clear_args(mut self) -> Self {
161 self.args.clear();
162 self
163 }
164
165 /// Append a [`MetricCheck`] to the effective check list.
166 #[must_use = "builder methods consume self; bind the result"]
167 pub fn check(mut self, c: MetricCheck) -> Self {
168 self.checks.push(c);
169 self
170 }
171
172 /// Wipe ALL checks (both `payload.default_checks` and any prior
173 /// `.check()` calls).
174 #[must_use = "builder methods consume self; bind the result"]
175 pub fn clear_checks(mut self) -> Self {
176 self.checks.clear();
177 self
178 }
179
180 /// Place the spawned child in the named cgroup (a plain name,
181 /// resolved relative to `ctx.cgroups.parent_path()`). When
182 /// omitted, the child inherits the spawning process's cgroup.
183 ///
184 /// Accepts `&'static str` (zero-alloc, the common case of a
185 /// const cgroup name) or any owned string type via [`Cow`]'s
186 /// `From` impls.
187 ///
188 /// The name is validated at `.run()`/`.spawn()` — leading `/`
189 /// is stripped, `..` and NUL bytes are rejected.
190 #[must_use = "builder methods consume self; bind the result"]
191 pub fn in_cgroup(mut self, name: impl Into<Cow<'static, str>>) -> Self {
192 self.cgroup = Some(name.into());
193 self
194 }
195
196 /// Bound `.run()`'s wait for the payload to exit. `None` (the
197 /// default when `.timeout` is not called) waits indefinitely —
198 /// suitable for payloads whose runtime is bounded internally
199 /// (schbench `-r 10`, fio `--runtime`, ...). `Some(duration)`
200 /// arms a deadline watchdog inside `.run()` that SIGKILLs the
201 /// payload's whole process group if it has not exited by the
202 /// deadline. Ignored by `.spawn()` — background handles manage
203 /// their own timing.
204 ///
205 /// The builder shape keeps `.run()` zero-arg so non-timeout
206 /// call sites read naturally, and leaves room for future
207 /// knobs (per-test environment, stdin, …) without another
208 /// signature break.
209 #[must_use = "builder methods consume self; bind the result"]
210 pub fn timeout(mut self, duration: Duration) -> Self {
211 self.timeout = Some(duration);
212 self
213 }
214
215 /// Blocking foreground run. Spawns the payload binary, waits
216 /// for it to exit, extracts metrics from its output per the
217 /// payload's [`OutputFormat`](crate::test_support::OutputFormat) (stdout-primary with stderr
218 /// fallback for `Json`; no extraction for
219 /// `ExitCode`), and evaluates declared [`MetricCheck`]s into an
220 /// [`AssertResult`]. See the module-level
221 /// `# Stdout-primary, stderr-fallback metric extraction`
222 /// section for the full contract.
223 ///
224 /// Runtime is bounded by the value set via
225 /// [`timeout`](Self::timeout). When the deadline expires,
226 /// `kill_payload_process_group` fires and the returned
227 /// `(AssertResult, PayloadMetrics)` reflects the captured
228 /// output plus the killed-child exit code; `status.code()`
229 /// returns `None` for a SIGKILL'd child, which
230 /// `spawn_and_wait` surfaces as `exit_code = -1` in
231 /// `SpawnOutput`. The timeout case is not an error — the
232 /// caller can still inspect metrics collected before the kill.
233 /// A post-kill drain failure is reported as `Err` (wraps the
234 /// original I/O error with "drain after timeout of N"); the
235 /// caller loses no output that was already captured because
236 /// the partial reader-thread buffers have been consumed in
237 /// the error path too.
238 ///
239 /// Metrics are also recorded to the per-test sidecar via the
240 /// SHM ring; the returned tuple is a convenience view of the
241 /// same values.
242 ///
243 /// Returns `Err` when the payload is not
244 /// [`PayloadKind::Binary`] (schedulers are framework-launched,
245 /// not test-body-launched), when the cgroup name fails
246 /// validation, when the spawn itself fails, or when post-kill
247 /// drain fails (see the timeout paragraph).
248 pub fn run(self) -> Result<(AssertResult, PayloadMetrics)> {
249 let binary = payload_binary(self.payload)?;
250 let cgroup_path = resolve_cgroup_path(self.ctx, self.cgroup.as_deref(), "PayloadRun::run")?;
251 let cgroup_arg: Option<(&str, &std::path::Path)> = cgroup_path.as_deref().map(|path| {
252 (
253 self.cgroup
254 .as_deref()
255 .expect("cgroup_path Some ⇒ cgroup name Some"),
256 path,
257 )
258 });
259 let output = spawn_and_wait(
260 binary,
261 &self.args,
262 cgroup_arg,
263 self.timeout,
264 self.payload.uses_parent_pgrp,
265 self.ctx.cgroups,
266 )
267 .with_context(|| format!("spawn payload '{}'", self.payload.name))?;
268 Ok(evaluate(self.payload, &self.checks, output))
269 }
270
271 /// Spawn the payload binary in the background and return a
272 /// [`PayloadHandle`] the caller can `.wait()`, `.kill()`, or
273 /// `.try_wait()` on.
274 ///
275 /// The child runs in the guest's process namespace (all ktstr
276 /// tests execute inside the VM); `PayloadHandle` is a thin
277 /// wrapper over [`std::process::Child`]. No cross-VM proxy.
278 ///
279 /// Dropping the handle without first calling one of the waiters
280 /// emits a stderr warning and SIGKILLs the child — leaked
281 /// handles would lose metrics and potentially outlive the test.
282 ///
283 /// Returns `Err` when the payload is not
284 /// [`PayloadKind::Binary`] or when the spawn itself fails.
285 pub fn spawn(self) -> Result<PayloadHandle> {
286 let binary = payload_binary(self.payload)?;
287 let cgroup_path =
288 resolve_cgroup_path(self.ctx, self.cgroup.as_deref(), "PayloadRun::spawn")?;
289 let cgroup_arg: Option<(&str, &std::path::Path)> = cgroup_path.as_deref().map(|path| {
290 (
291 self.cgroup
292 .as_deref()
293 .expect("cgroup_path Some ⇒ cgroup name Some"),
294 path,
295 )
296 });
297 let (child, sigchld) = spawn_child(
298 binary,
299 &self.args,
300 cgroup_arg,
301 self.payload.uses_parent_pgrp,
302 self.ctx.cgroups,
303 )
304 .with_context(|| format!("spawn payload '{}'", self.payload.name))?;
305 Ok(PayloadHandle {
306 child: Some(child),
307 payload: self.payload,
308 checks: self.checks,
309 _sigchld: sigchld,
310 })
311 }
312}
313
314/// Unwrap [`PayloadKind::Binary`] to its binary name, erroring when
315/// a scheduler-kind payload is passed.
316fn payload_binary(payload: &Payload) -> Result<&'static str> {
317 match payload.kind {
318 PayloadKind::Binary(name) => Ok(name),
319 PayloadKind::Scheduler(_) => anyhow::bail!(
320 "ctx.payload({}) called on a scheduler-kind payload; \
321 schedulers are launched by the test framework, not from \
322 the test body. Use ctx.payload(&BINARY_PAYLOAD) instead.",
323 payload.name,
324 ),
325 }
326}
327
328/// Common post-exit pipeline: extract metrics, resolve polarities,
329/// evaluate checks. Shared between foreground `.run()` and
330/// background handle `wait`/`kill` paths. The [`crate::test_support::PayloadMetrics`] is
331/// serialized to the guest-to-host SHM ring here — once per
332/// invocation — so the host can reconstruct per-call provenance in
333/// the sidecar without any Ctx-side accumulator.
334///
335/// # Per-format behavior
336///
337/// `OutputFormat::ExitCode` and `OutputFormat::Json` extract
338/// in-process: stdout-primary with a stderr fallback when stdout
339/// yields an empty metric set. The streams are never concatenated —
340/// the two drain threads in [`wait_and_capture`] run concurrently and
341/// provide no ordering guarantee, so a merged blob would corrupt any
342/// document whose bytes span both. Stderr is still passed separately
343/// to [`evaluate_checks`] so the exit-code-mismatch detail renders
344/// stderr without stdout prefix.
345fn evaluate(
346 payload: &Payload,
347 checks: &[MetricCheck],
348 output: SpawnOutput,
349) -> (AssertResult, PayloadMetrics) {
350 // `extract_metrics` is infallible for both `ExitCode` and `Json`
351 // (the two OutputFormat variants); the `Result` return type is
352 // preserved only for a uniform call signature.
353 let stdout_result = extract_metrics(
354 &output.stdout,
355 &payload.output,
356 crate::test_support::MetricStream::Stdout,
357 );
358 let mut metrics = stdout_result.unwrap_or_default();
359 if metrics.is_empty() && !output.stderr.is_empty() {
360 // Stderr fallback — runs only when stdout produced no
361 // metrics. Variant-agnostic by design:
362 //
363 // * `ExitCode`: `extract_metrics` returns `Ok(vec![])` on
364 // both stdout and stderr for this variant (no parsing
365 // path), so running the fallback is a no-op — no stored
366 // state, no wasted work beyond one function call. A
367 // per-variant gate would be complexity without behavioral
368 // difference.
369 // * `Json`: BENEFITS from the fallback. The motivating case
370 // is schbench-like payloads that write structured output
371 // to stderr only (see `SchbenchJsonPayload` in
372 // tests/common/fixtures.rs for the long-form rationale).
373 //
374 // The streams are never merged — fallback replaces, not
375 // concatenates — so an upstream that genuinely writes to
376 // both stdout and stderr gets only the stdout metrics,
377 // which matches the "well-behaved binaries keep stdout
378 // canonical" language on the `OutputFormat` doc.
379 let stderr_result = extract_metrics(
380 &output.stderr,
381 &payload.output,
382 crate::test_support::MetricStream::Stderr,
383 );
384 if let Ok(m) = stderr_result {
385 metrics = m;
386 }
387 }
388 resolve_polarities(&mut metrics, payload);
389
390 let payload_metrics = PayloadMetrics {
391 payload_index: next_payload_index(),
392 metrics,
393 exit_code: output.exit_code,
394 };
395
396 emit_payload_metrics(&payload_metrics);
397
398 let result = evaluate_checks(checks, &payload_metrics, &output.stderr);
399 (result, payload_metrics)
400}
401
402/// Emit a [`crate::test_support::PayloadMetrics`] on the guest-to-host bulk data channel
403/// (virtio-console port 1) under
404/// `MSG_TYPE_PAYLOAD_METRICS`(crate::vmm::wire::MSG_TYPE_PAYLOAD_METRICS).
405///
406/// The encoding (postcard v1) and the bulk-port fire-and-forget
407/// semantics live inside
408/// [`crate::vmm::guest_comms::send_payload_metrics`]; this thin
409/// wrapper exists only so the call site reads as the post-extraction
410/// emit step rather than reaching across modules. Backpressure is
411/// handled inside `write_msg`: a busy port-1 virtqueue blocks the
412/// writer until the host's `add_used` rate catches up.
413///
414/// Forwards the underlying `send_payload_metrics` boolean: `true`
415/// when the frame was written, `false` when the bulk port was not
416/// open, the write failed, or the call ran in host context (the
417/// `assert_guest_context` early-return). The emit call site in
418/// `evaluate` discards it at statement position; the boolean exists
419/// so the host-context no-op is observable to a test.
420fn emit_payload_metrics(pm: &PayloadMetrics) -> bool {
421 crate::vmm::guest_comms::send_payload_metrics(pm)
422}
423
424// ---------------------------------------------------------------------------
425// PayloadHandle — background spawn result
426// ---------------------------------------------------------------------------
427
428/// Handle to a background payload spawned via
429/// [`PayloadRun::spawn`]. Wraps a guest-local
430/// [`std::process::Child`]; `wait` / `kill` both consume the handle
431/// and return the collected metrics + assertion verdict.
432///
433/// Drop behavior: if the handle is dropped without `wait`/`kill`,
434/// the child and every process it forked are SIGKILLed via the
435/// process group headed by the child, then the child is reaped with
436/// `child.wait()`, and a stderr warning is emitted so the test
437/// author sees the implicit drop. The process-group kill reaches
438/// every descendant of multi-process payloads (stress-ng, schbench
439/// worker mode, fio `--numjobs`); without it the orphans keep
440/// stdout/stderr open, block `wait_and_capture`, and lose metrics.
441///
442/// When multiple handles are active, sidecar entries appear in
443/// finalization order (the order `.wait()`, `.kill()`, or
444/// `.try_wait()` returning `Ok(Some(..))` are called), not spawn
445/// order. `.try_wait()` only records on its terminal branch; an
446/// `Ok(None)` return keeps the handle live and defers the sidecar
447/// write to the next terminal call.
448// DROP-ORDER-CRITICAL: keep `_sigchld` LAST in the field list.
449//
450// Rust drops fields in declaration order, so the LAST field is the
451// LAST to drop. `SigchldScope::drop` re-installs the previously
452// captured disposition; multiple live `SigchldScope`s on the same
453// thread form a LIFO stack whose unwinding is what restores the
454// outermost original disposition. Any field added between `child`
455// and `_sigchld` would still keep `_sigchld` last, but a field
456// added AFTER `_sigchld` would reorder the drop sequence and break
457// the LIFO invariant — drop the new field first, signal-restore
458// path runs second, the disposition handler captured BEFORE the
459// new field was constructed gets restored even though the new
460// field outlived nothing. Also: when the caller holds two
461// `PayloadHandle`s and drops them in non-creation order, the LIFO
462// invariant is preserved by the field-order rule WITHIN each
463// handle but not ACROSS handles — non-LIFO drop across handles
464// will leak `SIG_DFL` into the rest of the process. Test authors
465// must drop handles in reverse creation order; the LIFO test in
466// the unit-test module pins the within-handle field-order rule
467// to catch a future refactor that re-orders the struct.
468#[must_use = "dropping a PayloadHandle SIGKILLs the child's process group; call .wait() or .kill() explicitly"]
469pub struct PayloadHandle {
470 /// Live child process. Wrapped in `Option` so consumers can
471 /// take ownership in `wait`/`kill` without making the drop-guard
472 /// reach into a `None`.
473 child: Option<std::process::Child>,
474 payload: &'static Payload,
475 checks: Vec<MetricCheck>,
476 /// `SIGCHLD` guard installed at spawn time. Kept alive until
477 /// the handle is consumed (via `wait`/`kill`/Drop) so the
478 /// child's eventual `waitpid` sees `SIG_DFL` instead of the
479 /// guest init's `SIG_IGN`. See [`SigchldScope`] for the full
480 /// rationale.
481 ///
482 /// DROP-ORDER-CRITICAL: keep this field LAST. See struct-level
483 /// note above.
484 _sigchld: SigchldScope,
485}
486
487impl std::fmt::Debug for PayloadHandle {
488 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
489 // Payload's manual Debug renders identity fields; the inner
490 // Child is omitted (not Debug-rendering-friendly and carries
491 // OS handles) — a one-line summary is enough for panics /
492 // test output.
493 f.debug_struct("PayloadHandle")
494 .field("payload", &self.payload.name)
495 .field("child_alive", &self.child.is_some())
496 .field("checks_len", &self.checks.len())
497 .finish()
498 }
499}
500
501impl PayloadHandle {
502 /// Name of the [`Payload`] this handle was spawned from — i.e.
503 /// the identity key used by step-level ops to address a running
504 /// payload. Step-local ops ([`Op::WaitPayload`](crate::scenario::ops::Op::WaitPayload),
505 /// [`Op::KillPayload`](crate::scenario::ops::Op::KillPayload))
506 /// match handles by this name.
507 pub fn payload_name(&self) -> &'static str {
508 self.payload.name
509 }
510
511 /// Live child's OS-level pid, or `None` once `wait`/`kill`/
512 /// `try_wait` has consumed the child.
513 ///
514 /// Integration tests that spawn a workload and then need to
515 /// target it with a second tool (for example the jemalloc-TLS
516 /// probe in `tests/jemalloc_probe_tests.rs`, which passes the
517 /// workload's pid to `ktstr-jemalloc-probe --pid`) read this
518 /// value between `spawn` and `wait`/`kill`/`try_wait`. The
519 /// internal fork-descendant reap test also uses it to probe
520 /// the process group via `killpg(_, 0)` after `kill()` without
521 /// reaching into the private `child` field.
522 pub fn pid(&self) -> Option<u32> {
523 self.child.as_ref().map(|c| c.id())
524 }
525
526 /// Block until the child exits naturally, then extract metrics
527 /// and evaluate checks, matching the foreground `.run()` return
528 /// shape.
529 ///
530 /// Metrics are also recorded to the per-test sidecar via the
531 /// SHM ring; the returned tuple is a convenience view of the
532 /// same values.
533 pub fn wait(mut self) -> Result<(AssertResult, PayloadMetrics)> {
534 let mut child = self
535 .child
536 .take()
537 .ok_or_else(|| already_consumed(self.payload))?;
538 // Block until the leader exits naturally first, BEFORE
539 // spawning reader threads inside `wait_and_capture`. Then
540 // killpg the group to reap any descendants (stress-ng workers,
541 // schbench worker mode, fio --numjobs threads) that survived
542 // the leader and still hold the inherited stdout/stderr pipes
543 // open. Without this killpg-before-drain step the reader
544 // threads would block forever waiting for descendants to
545 // release the pipes — the same blocking-pipe failure mode
546 // that try_wait's kill_payload_process_group step guards
547 // against. `Child::wait`
548 // caches the exit status so the second call inside
549 // `wait_and_capture` returns immediately without a syscall.
550 if let Err(e) = child.wait() {
551 kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
552 let _ = child.wait();
553 return Err(e).with_context(|| format!("wait payload '{}'", self.payload.name));
554 }
555 kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
556 match wait_and_capture(&mut child) {
557 Ok(output) => Ok(evaluate(self.payload, &self.checks, output)),
558 Err(e) => {
559 // killpg already ran above; one more `wait` clears
560 // the zombie so the pid slot is freed regardless of
561 // the capture error.
562 let _ = child.wait();
563 Err(e).with_context(|| format!("wait payload '{}'", self.payload.name))
564 }
565 }
566 }
567
568 /// SIGKILL the child **and every process it forked**, reap it,
569 /// and return whatever stdout+stderr was captured along with the
570 /// process exit code. Suitable for time-boxed background loads.
571 ///
572 /// The signal is delivered via `killpg(child_pid, SIGKILL)`
573 /// rather than `child.kill()` because `build_command` places the
574 /// payload at the head of its own process group. Multi-process
575 /// payloads (stress-ng, schbench worker mode, fio --numjobs) fork
576 /// descendants that keep stdout/stderr open; killing only the
577 /// head would orphan those writers and block
578 /// `wait_and_capture` forever, losing every metric.
579 ///
580 /// Metrics are also recorded to the per-test sidecar via the
581 /// SHM ring; the returned tuple is a convenience view of the
582 /// same values.
583 pub fn kill(mut self) -> Result<(AssertResult, PayloadMetrics)> {
584 let mut child = self
585 .child
586 .take()
587 .ok_or_else(|| already_consumed(self.payload))?;
588 kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
589 match wait_and_capture(&mut child) {
590 Ok(output) => Ok(evaluate(self.payload, &self.checks, output)),
591 Err(e) => {
592 // killpg + single-pid SIGKILL already ran at the
593 // start; the reap or pipe-drain failed afterwards.
594 // One more `wait` clears the zombie so the pid slot
595 // is freed regardless of the capture error.
596 let _ = child.wait();
597 Err(e).with_context(|| format!("reap killed payload '{}'", self.payload.name))
598 }
599 }
600 }
601
602 /// Non-blocking check for exit without consuming the handle.
603 /// Returns `Ok(Some((result, metrics)))` once the child has
604 /// exited and output is drained; `Ok(None)` while still
605 /// running. The handle remains live on `Ok(None)`.
606 ///
607 /// On the terminal `Ok(Some(..))` return, metrics are also
608 /// recorded to the per-test sidecar via the SHM ring; the
609 /// returned tuple is a convenience view of the same values.
610 pub fn try_wait(&mut self) -> Result<Option<(AssertResult, PayloadMetrics)>> {
611 let child = self
612 .child
613 .as_mut()
614 .ok_or_else(|| already_consumed(self.payload))?;
615 match child.try_wait()? {
616 Some(_status) => {
617 // `child` was Some above; the earlier branch didn't
618 // `take()` it, so this unwrap is guaranteed to hold.
619 let mut child = self
620 .child
621 .take()
622 .expect("child still present on terminal branch");
623 // The leader has exited (try_wait returned Some), but
624 // descendants forked off the leader (stress-ng workers,
625 // schbench worker mode, fio --numjobs threads) may
626 // still be alive and holding the inherited
627 // stdout/stderr pipes open. Without first SIGKILLing
628 // the process group, `wait_and_capture` would block
629 // forever on the read syscall waiting for those
630 // descendants to release the pipes. This mirrors the
631 // kill() path's kill_payload_process_group call which
632 // always SIGKILLs the group before draining — the
633 // only difference here is
634 // the leader has already exited, so killpg is reaping
635 // descendants only.
636 kill_payload_process_group(
637 &child,
638 self.payload.name,
639 self.payload.uses_parent_pgrp,
640 );
641 match wait_and_capture(&mut child) {
642 Ok(output) => Ok(Some(evaluate(self.payload, &self.checks, output))),
643 Err(e) => {
644 // killpg + single-pid SIGKILL already ran at
645 // the top of this branch; the reap or
646 // pipe-drain failed afterwards. One more
647 // `wait` clears the zombie so the pid slot is
648 // freed regardless of the capture error.
649 let _ = child.wait();
650 Err(e).with_context(|| format!("reap payload '{}'", self.payload.name))
651 }
652 }
653 }
654 None => Ok(None),
655 }
656 }
657}
658
659/// Error value produced when `wait`/`kill`/`try_wait` is called on a
660/// handle whose child has already been taken by a prior call. The
661/// payload name anchors the error to a specific handle so the
662/// test log points directly at the misuse site.
663fn already_consumed(payload: &'static Payload) -> anyhow::Error {
664 anyhow!(
665 "PayloadHandle for '{}' already consumed by a prior \
666 wait/kill/try_wait call; each handle can only produce \
667 one (AssertResult, PayloadMetrics) pair",
668 payload.name,
669 )
670}
671
672/// Drop-safety net for handles that fall out of scope without
673/// going through [`PayloadHandle::wait`], [`PayloadHandle::kill`],
674/// or [`PayloadHandle::try_wait`] (the three paths that
675/// `.take()` the child normally). Drop routes the process group
676/// through `kill_payload_process_group` — the SAME kill path the
677/// explicit `kill()` method uses — so there is no redundant
678/// `child.kill()` call: the killpg + single-pid SIGKILL inside
679/// `kill_payload_process_group` is belt-and-suspenders-by-design
680/// (see its doc for the pre-exec ESRCH race rationale), not
681/// two independent kills stacked. `child.wait()` reaps the
682/// zombie so the pid slot is freed even on the "dropped without
683/// consume" path, and the one-shot eprintln tells the operator
684/// metrics were lost.
685impl Drop for PayloadHandle {
686 fn drop(&mut self) {
687 if let Some(mut child) = self.child.take() {
688 kill_payload_process_group(&child, self.payload.name, self.payload.uses_parent_pgrp);
689 let _ = child.wait();
690 eprintln!(
691 "ktstr: PayloadHandle for '{}' dropped without wait/kill — \
692 process group SIGKILLed, metrics not recorded.",
693 self.payload.name,
694 );
695 }
696 }
697}
698
699/// Send `SIGKILL` to the process group headed by `child` AND to the
700/// leader pid directly.
701///
702/// `build_command` requests `CommandExt::process_group(0)` by default
703/// so the child's pid becomes its own process-group leader, coordinated
704/// with exec setup by the standard library. `killpg(pgid, SIGKILL)`
705/// on the child's pid therefore reaches every fork descendant in
706/// one shot — a single `child.kill()` would otherwise miss
707/// grandchildren of multi-process payloads (stress-ng, schbench
708/// worker mode, fio --numjobs) and those orphans would keep the
709/// stdout/stderr pipes open, hanging `wait_and_capture` forever.
710///
711/// When `uses_parent_pgrp` is `true`, the child shares its parent's
712/// pgrp ([`Payload::uses_parent_pgrp`] opted out of the fresh
713/// process group for tty-dependent binaries). The `killpg` call is
714/// skipped entirely in that case — issuing it would either hit
715/// `ESRCH` (child is not a pgrp leader) in the common case or, worse,
716/// target an unrelated group if the pgrp id happened to match a stale
717/// value. Only the direct `kill(pid)` on the leader runs; opt-out
718/// payloads accept responsibility for cleaning up their own
719/// descendants.
720///
721/// The follow-up `kill(pid, SIGKILL)` on the leader pid is
722/// belt-and-suspenders coverage for the edge case where `killpg`
723/// alone is insufficient: the kernel-side pgid transition during
724/// exec may not have completed yet when `killpg` fires, so
725/// `killpg` returns `ESRCH` (no such group) and the leader
726/// survives. A direct `kill(pid, SIGKILL)` always reaches the
727/// leader, and the SIGKILL survives `execve(2)` to take effect
728/// once exec completes (signal disposition is preserved across
729/// exec; the pending signal is delivered once the new image
730/// starts). SIGKILL is idempotent against zombies and
731/// already-dead processes, so the extra signal is safe after a
732/// successful `killpg` — a killpg that reached the leader has
733/// already queued it for SIGKILL, and the follow-up `kill(pid)`
734/// is a no-op on the terminated process.
735///
736/// `child.id()` returns `u32` for API ergonomics; on Linux the
737/// kernel's `pid_max ≤ 2²²` guarantees the value fits in
738/// [`libc::pid_t`]'s positive `i32` range, so `try_from` succeeds on
739/// every live child. `debug_assert!(pgid > 0)` catches the
740/// theoretically-impossible non-positive case before
741/// [`nix::sys::signal::killpg`] would otherwise interpret it as a
742/// broadcast target. `ESRCH` is logged as-a-no-op for both calls
743/// — it means either "group/process already reaped" or "group not
744/// yet set up"; the follow-up direct `kill` plus the leader's
745/// eventual `waitpid` consumer handle both.
746///
747/// # Process-group escape (not handled here)
748///
749/// `killpg` reaches every process whose `getpgrp()` equals the
750/// leader's pgid. A descendant that calls `setpgid(0, 0)` or
751/// `setsid(2)` between fork and exit leaves the leader's process
752/// group and becomes invisible to this helper — the escaping
753/// descendant keeps running after SIGKILL and may continue holding
754/// pipe fds that stall `wait_and_capture`. The bundled payloads
755/// (stress-ng, schbench, fio) have not been audited for these
756/// syscalls. `build_command` does not place an exec'd
757/// child into any other group; this limitation applies only to
758/// third-party payloads that deliberately re-parent themselves. The
759/// mitigation path is the caller's: wrap the misbehaving payload in
760/// a shell that traps SIGTERM → SIGKILL of its own descendants, or
761/// register the leader as a subreaper
762/// (`PR_SET_CHILD_SUBREAPER`) and reap orphans explicitly.
763///
764/// # Caller contract
765///
766/// Every caller MUST hold a live [`SigchldScope`] for the duration of
767/// the `wait` / `waitpid` that reaps the leader after this call
768/// returns. Without `SIG_DFL` for `SIGCHLD`, the guest init's
769/// `SIG_IGN` default causes `wait` to block until the child is
770/// re-reaped by init or to return `ECHILD` on an already-ignored
771/// SIGCHLD. Audited caller set — every invocation of this function:
772///
773/// - `PayloadHandle::wait` (one site: error arm after a
774/// `wait_and_capture` failure) — holds `self._sigchld`.
775/// - `PayloadHandle::kill` (one site: top of the method, before
776/// drain) — holds `self._sigchld`.
777/// - `PayloadHandle::try_wait` (one site: error arm after a
778/// terminal `try_wait` when drain fails) — holds `self._sigchld`.
779/// - `impl Drop for PayloadHandle` (one site: handle dropped without
780/// an explicit `wait`/`kill`/`try_wait` consume) — holds
781/// `self._sigchld` for the full Drop body.
782/// - `spawn_and_wait` (one site: error arm when `wait_and_capture`
783/// fails on a timeout-less foreground spawn) — opens a local
784/// `let _sigchld = SigchldScope::new()` at the top of the
785/// function.
786/// - `wait_with_deadline` (two sites: deadline-miss kill on expiry,
787/// and error arm for drain failure on natural child exit) — runs
788/// inside `spawn_and_wait`'s `_sigchld` scope, which is held
789/// across the callee as a local binding.
790///
791/// Every `PayloadHandle` method is safe because `_sigchld` is
792/// declared after `child` in the struct body; Rust drops fields in
793/// declaration order so `_sigchld` lives longer than the child
794/// `Option`, keeping the scope live for the full method body.
795///
796/// A future caller that skips either pattern will see
797/// `waitpid` hang on some guest runtimes — add a `SigchldScope` at
798/// the call site, or extend an enclosing type with a
799/// `_sigchld: SigchldScope` field, before landing.
800fn kill_payload_process_group(
801 child: &std::process::Child,
802 payload_name: &str,
803 uses_parent_pgrp: bool,
804) {
805 let raw_pid = child.id();
806 let pgid = match libc::pid_t::try_from(raw_pid) {
807 Ok(p) if p > 0 => p,
808 Ok(p) => {
809 tracing::error!(
810 payload = payload_name,
811 pid = p,
812 "child pid is non-positive — cannot kill process group; \
813 skipping kill (kernel's pid_max invariant violated, \
814 no safe target)"
815 );
816 return;
817 }
818 Err(_) => {
819 tracing::error!(
820 payload = payload_name,
821 pid = raw_pid,
822 "child pid exceeds pid_t range — cannot kill process group; \
823 skipping kill (Linux pid_max is 2^22 so this is only \
824 reachable on a non-Linux target or a kernel with an \
825 extended pid space)"
826 );
827 return;
828 }
829 };
830 let pid = nix::unistd::Pid::from_raw(pgid);
831 // `uses_parent_pgrp=true` means `build_command` did NOT request
832 // `process_group(0)`, so the child shares its parent's process
833 // group. A `killpg(pgid=child_pid, …)` call would target a group
834 // the child does not lead — `ESRCH` in the common case, or (worse)
835 // reach the ktstr process itself if a stale pid matches. Skip the
836 // group kill entirely and rely on the direct `kill(pid)` below to
837 // reap the leader. Multi-process tty-dependent payloads that
838 // opt out of the fresh pgrp accept responsibility for their own
839 // descendant cleanup (see `Payload::uses_parent_pgrp` doc).
840 if !uses_parent_pgrp {
841 match nix::sys::signal::killpg(pid, nix::sys::signal::Signal::SIGKILL) {
842 Ok(()) => {}
843 Err(nix::errno::Errno::ESRCH) => {
844 tracing::debug!(
845 payload = payload_name,
846 pgid,
847 "ESRCH — payload process group already reaped",
848 );
849 }
850 Err(e) => {
851 tracing::warn!(payload = payload_name, pgid, %e, "killpg failed for payload process group");
852 }
853 }
854 }
855 match nix::sys::signal::kill(pid, nix::sys::signal::Signal::SIGKILL) {
856 Ok(()) => {}
857 Err(nix::errno::Errno::ESRCH) => {
858 tracing::debug!(
859 payload = payload_name,
860 pid = pgid,
861 "ESRCH — payload leader already reaped",
862 );
863 }
864 Err(e) => {
865 tracing::warn!(payload = payload_name, pid = pgid, %e, "direct kill failed for payload leader");
866 }
867 }
868}
869
870/// Resolve each extracted metric's polarity + unit against the
871/// payload's declared `metrics` hints.
872///
873/// Unhinted metrics keep [`crate::test_support::Polarity::Unknown`] and empty unit.
874///
875/// Complexity: O(N + M) — build a `HashMap<&str, &MetricHint>` from
876/// the hint slice once, then look up each metric by name in O(1).
877/// The prior linear-scan implementation was O(N × M) where N is
878/// extracted metrics and M is declared hints; fio JSON with
879/// thousands of leaves + a dozen hints was the hottest path this
880/// module sees per payload run.
881fn resolve_polarities(metrics: &mut [Metric], payload: &Payload) {
882 if payload.metrics.is_empty() || metrics.is_empty() {
883 return;
884 }
885 let hints: std::collections::HashMap<&str, &crate::test_support::MetricHint> =
886 payload.metrics.iter().map(|h| (h.name, h)).collect();
887 for metric in metrics {
888 if let Some(hint) = hints.get(metric.name.as_str()) {
889 metric.polarity = hint.polarity;
890 metric.unit = hint.unit.to_string();
891 }
892 }
893}
894
895/// Evaluate [`MetricCheck`]s against a [`crate::test_support::PayloadMetrics`] and fold the
896/// verdict into an [`AssertResult`].
897///
898/// Evaluation order:
899/// 1. [`MetricCheck::ExitCodeEq`] pre-pass — evaluated FIRST so a
900/// misconfigured binary fails with an actionable exit-code error
901/// rather than "metric X not found".
902/// 2. Metric-path checks ([`MetricCheck::Min`], [`MetricCheck::Max`],
903/// [`MetricCheck::Range`], [`MetricCheck::Exists`]).
904///
905/// `stderr` is folded into the exit-code-mismatch detail when
906/// present — when a binary fails with "expected 0 got 1", the
907/// captured stderr almost always explains why, and forcing the test
908/// author to go hunt it down defeats actionable diagnostics.
909///
910/// Missing metrics fail loudly — a `Min` / `Max` / `Range` / `Exists`
911/// check against an absent metric reports a "not found" detail
912/// instead of silently passing.
913fn evaluate_checks(checks: &[MetricCheck], pm: &PayloadMetrics, stderr: &str) -> AssertResult {
914 let mut result = AssertResult::pass();
915 // Pre-pass: exit-code checks first. Delegates to
916 // `exit_code_mismatch_detail` for the detail's kind + message.
917 // Short-circuit on mismatch — a bad exit probably means the
918 // metric extraction found nothing useful.
919 if let Some(detail) = exit_code_mismatch_detail(checks, pm.exit_code, stderr) {
920 result.merge(AssertResult::fail(detail));
921 return result;
922 }
923 // Metric-path pass.
924 //
925 // Each comparator below routes a NaN observed value through
926 // `nan_metric` BEFORE the bound comparison. IEEE 754 makes
927 // every comparison against NaN evaluate to false (`NaN < x`,
928 // `NaN > x`, and `NaN == x` are all false), which would let
929 // a NaN-valued metric silently pass `Min` / `Max` / `Range` —
930 // exactly the case operators most need to flag, since a NaN
931 // value indicates the payload's metric extraction itself is
932 // broken (a divide-by-zero, an unparsed token, or a typed-
933 // measurement error). Surface NaN as a hard failure with a
934 // dedicated message so the bound check never silently green-
935 // lights an unmeasurable value.
936 for check in checks {
937 let detail = match check {
938 MetricCheck::Min { metric, value } => pm.get(metric).map_or_else(
939 || Some(missing_metric(metric)),
940 |actual| {
941 if actual.is_nan() {
942 Some(nan_metric(metric))
943 } else if actual < *value {
944 Some(AssertDetail::new(
945 DetailKind::Other,
946 format!("metric '{metric}' = {actual} below minimum {value}"),
947 ))
948 } else {
949 None
950 }
951 },
952 ),
953 MetricCheck::Max { metric, value } => pm.get(metric).map_or_else(
954 || Some(missing_metric(metric)),
955 |actual| {
956 if actual.is_nan() {
957 Some(nan_metric(metric))
958 } else if actual > *value {
959 Some(AssertDetail::new(
960 DetailKind::Other,
961 format!("metric '{metric}' = {actual} exceeds maximum {value}"),
962 ))
963 } else {
964 None
965 }
966 },
967 ),
968 MetricCheck::Range { metric, lo, hi } => pm.get(metric).map_or_else(
969 || Some(missing_metric(metric)),
970 |actual| {
971 if actual.is_nan() {
972 Some(nan_metric(metric))
973 } else if actual < *lo || actual > *hi {
974 Some(AssertDetail::new(
975 DetailKind::Other,
976 format!("metric '{metric}' = {actual} outside [{lo}, {hi}]"),
977 ))
978 } else {
979 None
980 }
981 },
982 ),
983 MetricCheck::Exists(metric) => pm.get(metric).is_none().then(|| missing_metric(metric)),
984 MetricCheck::ExitCodeEq(_) => None, // already evaluated in pre-pass
985 };
986 if let Some(d) = detail {
987 result.merge(AssertResult::fail(d));
988 }
989 }
990 result
991}
992
993/// Build the NaN-value [`AssertDetail`] surfaced by every
994/// magnitude comparator ([`MetricCheck::Min`], [`MetricCheck::Max`],
995/// [`MetricCheck::Range`]) when a metric extracts as NaN. Pulled
996/// out so the three call sites share one message format — a
997/// renamer-resistant single source of truth that pairs naturally
998/// with [`missing_metric`] for the absent-metric counterpart.
999fn nan_metric(metric: &str) -> AssertDetail {
1000 AssertDetail::new(DetailKind::Other, format!("metric '{metric}' value is NaN"))
1001}
1002
1003fn missing_metric(metric: &str) -> AssertDetail {
1004 AssertDetail::new(
1005 DetailKind::Other,
1006 format!("metric '{metric}' not found in payload output"),
1007 )
1008}
1009
1010/// Scan `checks` for the first `MetricCheck::ExitCodeEq` whose expected
1011/// value differs from `actual_exit_code` and return a matching
1012/// diagnostic [`AssertDetail`]. Returns `None` when no
1013/// `ExitCodeEq` check is declared, or when every declared one
1014/// matches the observed exit code.
1015///
1016/// Factored out of [`evaluate_checks`]'s pre-pass so the exit-code
1017/// mismatch detail has one source of truth for kind, message format,
1018/// and the "which MetricCheck wins" order.
1019fn exit_code_mismatch_detail(
1020 checks: &[MetricCheck],
1021 actual_exit_code: i32,
1022 stderr: &str,
1023) -> Option<AssertDetail> {
1024 checks.iter().find_map(|c| match c {
1025 MetricCheck::ExitCodeEq(expected) if actual_exit_code != *expected => {
1026 Some(AssertDetail::new(
1027 DetailKind::Other,
1028 format_exit_mismatch(actual_exit_code, *expected, stderr),
1029 ))
1030 }
1031 _ => None,
1032 })
1033}
1034
1035/// Render an exit-code mismatch with a trailing stderr tail when
1036/// non-empty. Long stderr is tail-truncated (last 1 KiB) — the end
1037/// of a failing process usually carries the actionable error.
1038const STDERR_TAIL_BYTES: usize = 1024;
1039
1040fn format_exit_mismatch(actual: i32, expected: i32, stderr: &str) -> String {
1041 let trimmed = stderr.trim_end();
1042 if trimmed.is_empty() {
1043 return format!("payload exited with code {actual}, expected {expected}");
1044 }
1045 let tail = stderr_tail(trimmed, STDERR_TAIL_BYTES);
1046 format!("payload exited with code {actual}, expected {expected}; stderr:\n{tail}")
1047}
1048
1049/// Return the final `max_bytes` of `s`, snapped forward to a char
1050/// boundary so slicing never panics on multi-byte input. Emits a
1051/// leading `...` when truncation actually happens.
1052fn stderr_tail(s: &str, max_bytes: usize) -> String {
1053 if s.len() <= max_bytes {
1054 return s.to_string();
1055 }
1056 let mut start = s.len() - max_bytes;
1057 while start < s.len() && !s.is_char_boundary(start) {
1058 start += 1;
1059 }
1060 format!("...{}", &s[start..])
1061}
1062
1063/// Captured output from a payload process invocation. `stderr`
1064/// is kept so the evaluator can surface it on non-zero exit — the
1065/// extracted metrics alone don't explain why a binary failed.
1066struct SpawnOutput {
1067 stdout: String,
1068 stderr: String,
1069 exit_code: i32,
1070}
1071
1072/// Resolve the user-supplied cgroup name to an absolute path
1073/// under `ctx.cgroups.parent_path()`, validating BEFORE fork so a
1074/// bad name produces a clear error rather than a `pre_exec` failure
1075/// that surfaces as an `io::Error` after the child is already spawning.
1076///
1077/// `op` is a caller-supplied label (typically `"PayloadRun::run"`
1078/// or `"PayloadRun::spawn"`) that prefixes every validation-error
1079/// message so an operator reading the failure can identify which
1080/// Op-method bubbled the error without re-running the test.
1081///
1082/// Rules:
1083/// - `None` → child inherits caller's cgroup (returns `Ok(None)`).
1084/// - A leading `/` is tolerated and stripped so `"/workload"` and
1085/// `"workload"` behave identically.
1086/// - NUL bytes are rejected — a resolved path with an interior
1087/// NUL would truncate inside any `libc` layer that handles it.
1088/// The downstream cgroupfs write in
1089/// [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1090/// would also reject the bad name, but catching it up-front
1091/// gives a clearer diagnostic than the underlying write error.
1092/// - Any `..` component is rejected to prevent the name from
1093/// escaping the parent cgroup.
1094/// - Empty names (or names that strip to empty) are rejected so a
1095/// typo doesn't silently target the parent cgroup itself.
1096fn resolve_cgroup_path(
1097 ctx: &Ctx<'_>,
1098 name: Option<&str>,
1099 op: &'static str,
1100) -> Result<Option<PathBuf>> {
1101 let Some(name) = name else {
1102 return Ok(None);
1103 };
1104 if name.as_bytes().contains(&0) {
1105 return Err(anyhow!("{op}: cgroup name '{name}' contains a NUL byte"));
1106 }
1107 let trimmed = name.trim_start_matches('/');
1108 if trimmed.is_empty() {
1109 return Err(anyhow!(
1110 "{op}: cgroup name '{name}' is empty or resolves to the parent cgroup"
1111 ));
1112 }
1113 let relative = std::path::Path::new(trimmed);
1114 if relative
1115 .components()
1116 .any(|c| matches!(c, std::path::Component::ParentDir))
1117 {
1118 return Err(anyhow!(
1119 "{op}: cgroup name '{name}' contains '..'; paths must stay within the \
1120 test's cgroup parent"
1121 ));
1122 }
1123 Ok(Some(ctx.cgroups.parent_path().join(relative)))
1124}
1125
1126/// Build a [`std::process::Command`] with args, piped stdout/stderr, a
1127/// `process_group(0)` request when the payload is not
1128/// `uses_parent_pgrp`, and (optionally) a cgroup-placement
1129/// pre_exec hook that BLOCKS the child on a read from a
1130/// caller-owned release pipe until the parent has placed the
1131/// child into the target cgroup via
1132/// [`crate::cgroup::CgroupOps::place_task_during_handshake`].
1133///
1134/// When `cgroup` is `Some((name, path))`, the returned tuple's
1135/// second element is `Some(CgroupSyncHandles)` — a parent-side
1136/// bundle of (a) the write end of the release pipe, (b) the read
1137/// end of the child-side pid-notify pipe, (c) the user-facing
1138/// `cgroup_name` the placement trait method will receive, and
1139/// (d) the absolute `cgroup.procs` path retained for diagnostic
1140/// surfaces. The caller passes it to
1141/// [`spawn_with_cgroup_sync`], which drives the placement
1142/// protocol by reading the child pid, calling
1143/// `cgroup_ops.place_task_during_handshake(cgroup_name, child_pid)`,
1144/// then releasing the child via a single-byte write on the
1145/// release pipe.
1146///
1147/// When `cgroup` is `None`, the returned handle is `None`
1148/// and callers may invoke `Command::spawn()` on the returned
1149/// `Command` directly — no placement protocol is required and
1150/// the child's cgroup is inherited from the parent (the ktstr
1151/// process).
1152///
1153/// Returns `Err` if the pipe(2) pair allocation fails.
1154fn build_command(
1155 binary: &str,
1156 args: &[String],
1157 cgroup: Option<(&str, &std::path::Path)>,
1158 uses_parent_pgrp: bool,
1159) -> Result<(std::process::Command, Option<CgroupSyncHandles>)> {
1160 use std::os::unix::process::CommandExt;
1161 use std::process::{Command, Stdio};
1162
1163 let mut cmd = Command::new(binary);
1164 cmd.args(args).stdout(Stdio::piped()).stderr(Stdio::piped());
1165 if !uses_parent_pgrp {
1166 // `process_group(0)` requests a fresh process group with
1167 // the child as leader (pgid == child's pid). `killpg` on
1168 // the child's pid then reaches every fork descendant in
1169 // one signal — a single `child.kill()` would otherwise
1170 // miss grandchildren of multi-process payloads (stress-ng,
1171 // schbench worker mode, fio with multiple jobs), and
1172 // those orphans keep the stdout/stderr pipes open,
1173 // hanging `wait_and_capture` and discarding the metrics.
1174 //
1175 // Previously a hand-rolled `pre_exec(setpgid(0, 0))` hook
1176 // did the same job, but a `killpg` issued between
1177 // `fork(2)` and the child's `setpgid` completion could
1178 // return `ESRCH` (no such group) while the child and its
1179 // descendants survived. `CommandExt::process_group`
1180 // NARROWS that window: on `posix_spawn`-capable
1181 // platforms (and futures where `process_group` dispatches
1182 // to it) the pgid transition is kernel-sequenced with
1183 // exec and the race is eliminated. When the standard
1184 // library has to fall through to the fork+exec path —
1185 // which it does whenever a cgroup placement `pre_exec`
1186 // hook is also registered below, as `process_group(0)`
1187 // and any `pre_exec` together force the legacy path —
1188 // the remaining window is covered by the direct
1189 // `kill(pid, SIGKILL)` follow-up in
1190 // `kill_payload_process_group`.
1191 //
1192 // The `uses_parent_pgrp == true` branch SKIPS this call
1193 // so the child inherits the parent ktstr process's pgid.
1194 // Opt-in for tty-dependent payloads (shells, `less`,
1195 // anything that reads controlling-terminal foreground-
1196 // pgrp for job-control signalling) — a fresh pgrp reads
1197 // as "no job control" and breaks their signal
1198 // behaviour. The cost is that `killpg(child_pid, ...)`
1199 // no longer reaches descendants (the child isn't a
1200 // pgrp leader), so multi-process tty-dependent payloads
1201 // must react to SIGHUP / pipe close on their own or
1202 // risk orphaning — see the doc on `Payload::uses_parent_pgrp`.
1203 cmd.process_group(0);
1204 }
1205
1206 if let Some((cgroup_name, cgroup_path)) = cgroup {
1207 // Two-pipe cgroup-placement handshake. `notify_*` carries
1208 // the child's pid from its pre_exec hook up to the parent
1209 // so the parent can dispatch the placement call via
1210 // [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1211 // (`Command::spawn()` blocks on the stdlib CLOEXEC status
1212 // pipe until the child execve's, so the pid from
1213 // `Child::id()` is NOT available to the parent in time).
1214 // `release_*` is the reverse channel — the parent writes a
1215 // single byte once the `cgroup.procs` update has been
1216 // committed, and the child's pre_exec blocks on that byte
1217 // so its execve cannot race the placement.
1218 //
1219 // Both pipes are created with O_CLOEXEC so the parent's
1220 // copies never leak to the child (only the fds we
1221 // explicitly hand into the pre_exec closure via raw fd
1222 // numbers are touched by the child, and those are closed
1223 // on execve once pre_exec returns). This matches the
1224 // pre_exec AS-safety contract — only `read(2)` /
1225 // `write(2)` / `close(2)` / `getpid(2)` run between fork
1226 // and execve, all of which are explicitly AS-safe per
1227 // POSIX.1-2017 §2.4.3.
1228 let notify = PipePair::new().context("allocate cgroup sync pid-notify pipe")?;
1229 let release = PipePair::new().context("allocate cgroup sync release pipe")?;
1230 let notify_read_fd = notify.r_fd();
1231 let notify_write_fd = notify.w_fd();
1232 let release_read_fd = release.r_fd();
1233 let release_write_fd = release.w_fd();
1234 // SAFETY: the pre_exec closure runs in the child between
1235 // fork and execve. The body uses only getpid / write /
1236 // read / close, all AS-safe. All four fds are raw numbers
1237 // inherited by the child via the fork; the pre_exec hook
1238 // ALSO closes the child's own inherited copies of the
1239 // ends the parent will hold (`notify_read_fd`,
1240 // `release_write_fd`) BEFORE blocking on read, so the
1241 // parent's drop of the release write end actually reaches
1242 // the child as EOF instead of being masked by the child's
1243 // own inherited writer copy (which would otherwise leave
1244 // `read(release_read_fd)` blocked indefinitely — the
1245 // cross-fork pipe-sync deadlock). On the parent side we
1246 // hold owned copies in `notify` / `release` which we
1247 // close after consuming them in `drive_cgroup_handshake`.
1248 unsafe {
1249 cmd.pre_exec(move || {
1250 cgroup_sync_pre_exec(
1251 notify_read_fd,
1252 notify_write_fd,
1253 release_read_fd,
1254 release_write_fd,
1255 )
1256 });
1257 }
1258 let handles = CgroupSyncHandles {
1259 notify,
1260 release,
1261 cgroup_name: cgroup_name.to_string(),
1262 cgroup_procs_path: cgroup_path.join("cgroup.procs"),
1263 };
1264 return Ok((cmd, Some(handles)));
1265 }
1266 Ok((cmd, None))
1267}
1268
1269/// Owned pipe(2) pair. Tracks both fds as raw numbers so the
1270/// struct stays `Copy`-free and explicit about lifetime (closed
1271/// via `Drop` when no longer needed). The parent keeps one half
1272/// of each direction; the other halves are inherited by the
1273/// child through fork and consumed by `cgroup_sync_pre_exec`.
1274///
1275/// `O_CLOEXEC` is set on both ends at creation via `pipe2(2)` so
1276/// the parent's references do not leak into any subsequent
1277/// `Command::spawn()` that might run from a reader thread while
1278/// the handshake is in flight. The child's copies are closed by
1279/// the kernel on execve.
1280struct PipePair {
1281 read_fd: std::os::fd::OwnedFd,
1282 write_fd: std::os::fd::OwnedFd,
1283}
1284
1285impl PipePair {
1286 fn new() -> std::io::Result<Self> {
1287 use std::os::fd::FromRawFd;
1288 let mut fds = [0i32; 2];
1289 // SAFETY: `pipe2` writes two fds into the provided slot on
1290 // success. O_CLOEXEC ensures the fds are not leaked across
1291 // later execve calls on the parent side.
1292 let rc = unsafe { libc::pipe2(fds.as_mut_ptr(), libc::O_CLOEXEC) };
1293 if rc != 0 {
1294 return Err(std::io::Error::last_os_error());
1295 }
1296 // SAFETY: pipe2 returned success and gave us two fresh fds.
1297 let read_fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fds[0]) };
1298 let write_fd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fds[1]) };
1299 Ok(Self { read_fd, write_fd })
1300 }
1301
1302 fn r_fd(&self) -> i32 {
1303 use std::os::fd::AsRawFd;
1304 self.read_fd.as_raw_fd()
1305 }
1306
1307 fn w_fd(&self) -> i32 {
1308 use std::os::fd::AsRawFd;
1309 self.write_fd.as_raw_fd()
1310 }
1311}
1312
1313/// Parent-side bundle carrying every resource the cgroup-placement
1314/// handshake needs after fork. Owned by the caller of
1315/// [`build_command`] until
1316/// [`spawn_with_cgroup_sync`] consumes it.
1317///
1318/// `notify` — the child writes its pid's bytes to the write end
1319/// as its first pre_exec step; the parent reads from the read end.
1320///
1321/// `release` — the parent writes a single byte to the write end
1322/// once the cgroup-placement update is committed; the child's
1323/// pre_exec blocks on a read of the read end.
1324///
1325/// `cgroup_name` — the user-facing cgroup name the test author
1326/// passed in `Op::RunPayload { cgroup: Some(name), .. }` or
1327/// `PayloadRun::in_cgroup(name)`. Threaded to
1328/// [`crate::cgroup::CgroupOps::place_task_during_handshake`]
1329/// at placement time so the trait implementation derives the
1330/// cgroup.procs path from its own parent-path knowledge, keeping
1331/// the host-side mock observable without touching cgroupfs.
1332///
1333/// `cgroup_procs_path` — the absolute `<cgroup>/cgroup.procs`
1334/// path, retained for diagnostic surfaces (the path appears in
1335/// trait-method `with_context` error messages so a failing
1336/// placement still names the exact filesystem path that didn't
1337/// accept the write).
1338struct CgroupSyncHandles {
1339 notify: PipePair,
1340 release: PipePair,
1341 cgroup_name: String,
1342 cgroup_procs_path: PathBuf,
1343}
1344
1345/// Async-signal-safe body of the cgroup-placement `pre_exec`
1346/// hook. Runs between fork and execve in the child.
1347///
1348/// Protocol:
1349/// 0. Close the child's inherited copies of the parent-owned
1350/// ends — `notify_read_fd` (child never reads notify) and
1351/// `release_write_fd` (child never writes release). This is
1352/// MANDATORY: without it the kernel still sees two writers on
1353/// the release pipe (parent's + child's own inherited copy),
1354/// so the parent's Drop of the release write end does NOT
1355/// deliver EOF to the child's `read(release_read_fd)` — the
1356/// child blocks forever. This is the canonical pipe-sync
1357/// fork-inherited-fd deadlock; closing the inherited copies
1358/// is what makes the sync work.
1359/// 1. Write the child's pid (as an LE i32, 4 bytes) to
1360/// `notify_write_fd` so the parent can begin the `cgroup.procs`
1361/// write. Close `notify_write_fd` immediately after so the
1362/// parent's read sees a fast EOF if the child crashes before
1363/// reaching the release read.
1364/// 2. Read a single release byte from `release_read_fd` to block
1365/// until the parent has committed the cgroup-placement write.
1366/// 3. Close `release_read_fd` (the kernel will also close it via
1367/// O_CLOEXEC on execve, but a prompt close frees the fd before
1368/// any user-provided pre_exec extension could observe it).
1369///
1370/// # Safety
1371///
1372/// This function runs between `fork(2)` and `execve(2)` in the
1373/// child. Only async-signal-safe operations are permitted — no
1374/// `malloc`, no `std::fs`, no `libc::printf`, no locks (including
1375/// the jemalloc arena). Every operation here is `getpid` / `write`
1376/// / `read` / `close`, all of which POSIX.1-2017 §2.4.3 lists as
1377/// AS-safe. In particular there is NO stdlib I/O, NO integer
1378/// formatting, and NO allocation — the pid is sent as 4 raw
1379/// little-endian bytes rather than an ASCII render, so no
1380/// formatting helper is reachable from the child side.
1381///
1382/// Errors from `write(2)` or `read(2)` (short writes, EPIPE from
1383/// a parent that abandoned the handshake) are mapped to
1384/// `io::Error::from_raw_os_error` and returned. The stdlib's
1385/// spawn loop forwards the errno through its CLOEXEC status pipe
1386/// so the parent's `spawn()` returns an actionable error rather
1387/// than silently racing through the placement step. Step 0's
1388/// `close(2)` failures are intentionally IGNORED — EBADF is
1389/// expected if the kernel is unusual about inherited fd numbering,
1390/// and any other errno here cannot be recovered from (the parent's
1391/// handshake still needs to run). The subsequent `write` / `read`
1392/// surfaces any real breakage.
1393fn cgroup_sync_pre_exec(
1394 notify_read_fd: libc::c_int,
1395 notify_write_fd: libc::c_int,
1396 release_read_fd: libc::c_int,
1397 release_write_fd: libc::c_int,
1398) -> std::io::Result<()> {
1399 // Step 0: close the child's inherited copies of the
1400 // parent-owned ends. MANDATORY to avoid deadlocking on the
1401 // subsequent `read(release_read_fd)` — without closing
1402 // `release_write_fd`, the kernel keeps the release pipe's
1403 // writer-count non-zero even when the parent drops its own
1404 // copy, so the child's read never EOFs. Symmetrically,
1405 // closing `notify_read_fd` frees a descriptor slot and keeps
1406 // the parent's notify read end the sole reader (defense in
1407 // depth — the protocol doesn't strictly require it since we
1408 // never EOF the notify pipe, but a tidy close is cheap).
1409 //
1410 // `libc::close` is AS-safe. Return codes are ignored: EBADF
1411 // is theoretically possible if the kernel ever renumbered
1412 // the inherited fd, and any other errno is non-actionable
1413 // between fork and execve. The write/read below surfaces any
1414 // real breakage.
1415 //
1416 // SAFETY: all four fd numbers were valid on the parent side
1417 // at the time of fork and the kernel duplicates them into
1418 // the child's fd table. Closing a fd that the kernel already
1419 // renumbered returns EBADF without effect — no memory
1420 // safety concern.
1421 unsafe {
1422 libc::close(notify_read_fd);
1423 libc::close(release_write_fd);
1424 }
1425
1426 // Step 1: publish pid. getpid(2) is AS-safe; the pid is a
1427 // raw i32, so we send its 4-byte little-endian encoding and
1428 // spare the child any integer-formatting work. A stack
1429 // buffer is the only storage; no allocation.
1430 let pid = unsafe { libc::getpid() };
1431 let pid_bytes = pid.to_le_bytes();
1432 let mut written = 0usize;
1433 while written < pid_bytes.len() {
1434 // SAFETY: writing into a raw fd that the parent owns the
1435 // read end of. `pid_bytes` is a live stack buffer.
1436 let n = unsafe {
1437 libc::write(
1438 notify_write_fd,
1439 pid_bytes.as_ptr().add(written) as *const libc::c_void,
1440 pid_bytes.len() - written,
1441 )
1442 };
1443 if n < 0 {
1444 let err = std::io::Error::last_os_error();
1445 // EINTR: retry. Every other errno (EPIPE from a
1446 // collapsed parent read end, EBADF, ...) is terminal
1447 // — surface it to the parent via the stdlib spawn
1448 // error channel.
1449 if err.raw_os_error() == Some(libc::EINTR) {
1450 continue;
1451 }
1452 return Err(err);
1453 }
1454 if n == 0 {
1455 // Zero-byte write is not defined for pipes; treat as
1456 // EIO rather than loop forever.
1457 return Err(std::io::Error::from_raw_os_error(libc::EIO));
1458 }
1459 written += n as usize;
1460 }
1461 // Close the notify write end so the parent's read gets EOF if
1462 // the child subsequently crashes before the release read.
1463 // SAFETY: notify_write_fd is a valid fd the child inherited
1464 // from the parent; closing it here does not affect the parent's
1465 // read end.
1466 unsafe {
1467 libc::close(notify_write_fd);
1468 }
1469
1470 // Step 2: block on the release byte. One byte is enough — the
1471 // payload is a synchronization token, not data. Loop to handle
1472 // EINTR and short reads (partial-byte reads are impossible on
1473 // a 1-byte read, but the loop keeps the code uniform with the
1474 // write side).
1475 let mut buf = [0u8; 1];
1476 let mut read_total = 0usize;
1477 while read_total < buf.len() {
1478 // SAFETY: reading from a raw fd that the parent owns the
1479 // write end of. `buf` is a live stack buffer.
1480 let n = unsafe {
1481 libc::read(
1482 release_read_fd,
1483 buf.as_mut_ptr().add(read_total) as *mut libc::c_void,
1484 buf.len() - read_total,
1485 )
1486 };
1487 if n < 0 {
1488 let err = std::io::Error::last_os_error();
1489 if err.raw_os_error() == Some(libc::EINTR) {
1490 continue;
1491 }
1492 return Err(err);
1493 }
1494 if n == 0 {
1495 // EOF before the release byte arrived — the parent
1496 // abandoned the handshake (crashed / failed cgroup
1497 // write). Fail the pre_exec so the stdlib spawn path
1498 // surfaces the abort instead of letting the child
1499 // execve into an unplaced cgroup.
1500 return Err(std::io::Error::from_raw_os_error(libc::EPIPE));
1501 }
1502 read_total += n as usize;
1503 }
1504 // Step 3: close the release read end. The kernel would do
1505 // this on execve via O_CLOEXEC anyway, but an explicit close
1506 // frees the fd now.
1507 // SAFETY: release_read_fd is a valid fd the child inherited
1508 // from the parent.
1509 unsafe {
1510 libc::close(release_read_fd);
1511 }
1512 Ok(())
1513}
1514
1515/// Complete the cgroup-placement handshake on a child that was
1516/// spawned with a [`build_command`]-supplied pre_exec hook.
1517///
1518/// The caller MUST run `Command::spawn()` on a dedicated thread
1519/// because the stdlib's `spawn()` blocks on its CLOEXEC status
1520/// pipe until the child has successfully execve'd — and the
1521/// child's pre_exec blocks on the release read until this
1522/// function finishes. Without the thread split the two would
1523/// deadlock.
1524///
1525/// Protocol (parent side, main thread):
1526/// 1. Read the child's pid bytes from the notify read end.
1527/// 2. Dispatch placement via
1528/// [`crate::cgroup::CgroupOps::place_task_during_handshake`],
1529/// threading the user-facing `cgroup_name` and the just-read
1530/// child pid. The trait implementation
1531/// ([`crate::cgroup::CgroupManager::place_task_during_handshake`]
1532/// in production) derives the `cgroup.procs` path from its own
1533/// parent-path knowledge and performs the write under the same
1534/// `write_with_timeout` shape as the other cgroupfs writes;
1535/// `MockCgroupOps` records the call without touching the
1536/// filesystem so handler-level tests can observe placement
1537/// against `Op::RunPayload { cgroup: Some(..), .. }`.
1538/// 3. Write the single release byte to the release write end,
1539/// then close it so any subsequent short-read / EOF on the
1540/// child side is prompt.
1541/// 4. Close the notify read end.
1542///
1543/// The function returns the child pid so callers can cross-check
1544/// it against `Child::id()` once the spawn thread returns.
1545/// Wrapped in `Result<libc::pid_t>` because the notify read or
1546/// the placement trait call can fail; a failure drops the
1547/// handle, which also closes the release write end, giving the
1548/// child's pre_exec a fast EOF-driven bail (the trait contract
1549/// pins this responsibility on the caller — see
1550/// [`crate::cgroup::CgroupOps::place_task_during_handshake`]).
1551fn spawn_with_cgroup_sync(
1552 handles: CgroupSyncHandles,
1553 cgroup_ops: &dyn crate::cgroup::CgroupOps,
1554) -> Result<libc::pid_t> {
1555 use std::io::{Read, Write};
1556 let CgroupSyncHandles {
1557 notify,
1558 release,
1559 cgroup_name,
1560 cgroup_procs_path,
1561 } = handles;
1562 // Step 1: read child pid. Keep the parent-side notify_w
1563 // OPEN during the read — closing it before fork would let
1564 // stdlib's internal `pipe2` for the CLOEXEC status pipe
1565 // recycle our fd number; the child then inherits a state
1566 // where its `notify_write_fd` points at stdlib's status
1567 // pipe, not our notify pipe. `write(notify_write_fd, pid)`
1568 // in the child would corrupt stdlib's protocol and the
1569 // parent's `read_exact` on our notify pipe would see an
1570 // indefinite wait because no data ever arrives on the
1571 // intended pipe. The canonical rule: drop your parent
1572 // copy of the child's write end AFTER the child has
1573 // written (or died), not before. We achieve that here by
1574 // holding `notify_w` alive across the read and dropping
1575 // it only at the end.
1576 //
1577 // Child-died-without-writing detection: if the child
1578 // dies before step 1's write, its inherited `notify_w`
1579 // closes on `_exit`. The pipe then has ONLY the parent's
1580 // `notify_w` as a writer — still non-zero — and our
1581 // `read_exact` would block indefinitely. Guard against
1582 // that with a bounded `poll(2)`: wait up to 5s for data,
1583 // then bail with an actionable error naming the
1584 // probable cause (child pre_exec failed before writing).
1585 // The spawn thread's own error (`cmd.spawn() → Err`)
1586 // surfaces too, and `drive_cgroup_handshake` returns
1587 // whichever the caller sees first.
1588 let PipePair {
1589 read_fd: notify_r,
1590 write_fd: notify_w,
1591 } = notify;
1592 {
1593 let pfd_fd = std::os::fd::AsRawFd::as_raw_fd(¬ify_r);
1594 let mut pfd = libc::pollfd {
1595 fd: pfd_fd,
1596 events: libc::POLLIN,
1597 revents: 0,
1598 };
1599 // 5s ceiling. Any legitimate fork + pre_exec sequence
1600 // completes in low milliseconds; 5s is loose for even
1601 // the most contended CI host and tight enough to
1602 // flag a silent child-death promptly.
1603 let poll_ms: libc::c_int = 5_000;
1604 let ready = unsafe { libc::poll(&mut pfd, 1, poll_ms) };
1605 if ready < 0 {
1606 let e = std::io::Error::last_os_error();
1607 if e.raw_os_error() != Some(libc::EINTR) {
1608 return Err(
1609 anyhow::Error::new(e).context("poll(notify_r) for cgroup-sync pid-notify")
1610 );
1611 }
1612 } else if ready == 0 {
1613 anyhow::bail!(
1614 "cgroup-sync notify pipe: no pid written by child within 5s. \
1615 The child's pre_exec likely failed before Step 1 (possibly \
1616 EBADF on `notify_write_fd` because the fd number was \
1617 recycled by stdlib's internal pipe2). Check the spawn \
1618 thread's error for the underlying cause."
1619 );
1620 }
1621 }
1622 let mut notify_file = std::fs::File::from(notify_r);
1623 let mut pid_bytes = [0u8; 4];
1624 notify_file
1625 .read_exact(&mut pid_bytes)
1626 .context("read child pid from cgroup-sync notify pipe")?;
1627 drop(notify_file);
1628 // Now it is safe to close parent's notify write end:
1629 // the child has either written its pid (success path) or
1630 // the poll bailed (failure path, already returned above).
1631 drop(notify_w);
1632 let child_pid = libc::pid_t::from_le_bytes(pid_bytes);
1633 anyhow::ensure!(
1634 child_pid > 0,
1635 "cgroup-sync notify pipe returned non-positive pid {child_pid}; \
1636 the child's pre_exec hook sent a corrupted pid — fail the \
1637 handshake rather than write a bad value to cgroup.procs"
1638 );
1639
1640 // Step 2: dispatch placement through the CgroupOps trait so
1641 // the production write goes through `CgroupManager` and the
1642 // test path's `MockCgroupOps` records the placement for
1643 // handler-level observability. The trait implementation
1644 // derives the cgroup.procs path from its own parent-path
1645 // knowledge; `cgroup_procs_path` is held alongside
1646 // `cgroup_name` purely so the error chain still names the
1647 // path that didn't accept the write. We are on the parent's
1648 // main thread post-fork — no AS-safety constraint applies,
1649 // so the trait dispatch's heap allocations and anyhow error
1650 // chain are fair game (pre_exec runs on the CHILD side and
1651 // never reaches this branch).
1652 cgroup_ops
1653 .place_task_during_handshake(&cgroup_name, child_pid)
1654 .with_context(|| {
1655 format!(
1656 "place pid {child_pid} into cgroup '{cgroup_name}' (cgroup.procs at {}) for cgroup-sync placement",
1657 cgroup_procs_path.display(),
1658 )
1659 })?;
1660
1661 // Step 3: release the child. One byte is enough; the content
1662 // is ignored by the reader.
1663 let PipePair {
1664 read_fd: release_r,
1665 write_fd: release_w,
1666 } = release;
1667 drop(release_r);
1668 let mut release_file = std::fs::File::from(release_w);
1669 release_file
1670 .write_all(&[1u8])
1671 .context("write release byte to cgroup-sync release pipe")?;
1672 drop(release_file);
1673
1674 Ok(child_pid)
1675}
1676
1677/// Spawn a Command that carries a cgroup-sync pre_exec hook.
1678/// Runs `Command::spawn()` on a dedicated thread (it blocks on
1679/// the stdlib CLOEXEC status pipe until the child execve's,
1680/// which can't happen until the parent's main thread has
1681/// released the pre_exec handshake), drives the
1682/// [`spawn_with_cgroup_sync`] protocol on the main thread, then
1683/// joins the spawn thread to collect the resulting [`std::process::Child`].
1684///
1685/// If either the spawn or the handshake fails, the caller drops
1686/// the remaining pipe handles (via the [`CgroupSyncHandles`]
1687/// consumption in `spawn_with_cgroup_sync`), which causes the
1688/// child's pre_exec read to unblock with EOF and fail with
1689/// EPIPE. The child never reaches execve, the spawn thread
1690/// surfaces the pre_exec error through its stdlib error
1691/// channel, and we propagate the first error the caller sees.
1692fn drive_cgroup_handshake(
1693 cmd: std::process::Command,
1694 handles: CgroupSyncHandles,
1695 binary: &str,
1696 cgroup_ops: &dyn crate::cgroup::CgroupOps,
1697) -> Result<std::process::Child> {
1698 // Move the Command into a thread so its blocking `spawn()`
1699 // doesn't deadlock with the child's pre_exec handshake.
1700 let binary_owned = binary.to_string();
1701 let spawn_thread = std::thread::spawn(move || -> Result<std::process::Child> {
1702 let mut cmd = cmd;
1703 cmd.spawn()
1704 .map_err(|e| spawn_error_context(e, &binary_owned))
1705 });
1706
1707 // Drive the placement protocol on the main thread. If this
1708 // fails we drop the remaining handle bits so the child sees
1709 // EOF on its release read; the spawn thread will then
1710 // surface the pre_exec EPIPE through its stdlib error
1711 // channel.
1712 let sync_result = spawn_with_cgroup_sync(handles, cgroup_ops);
1713
1714 // Join the spawn thread regardless of sync outcome so a
1715 // failing handshake does not leak a background std thread.
1716 // A join error is either a panic in the spawn closure (very
1717 // rare under `panic = "unwind"`) or an explicit poisoning;
1718 // we map it to a generic anyhow error so the caller still
1719 // gets a meaningful chain.
1720 let spawn_result = spawn_thread
1721 .join()
1722 .map_err(|_| anyhow!("cgroup-sync spawn thread panicked"))?;
1723
1724 // Precedence: if the sync failed, that error is the root
1725 // cause (the spawn will have failed TOO because the child
1726 // bailed on EPIPE, but the sync error carries the actionable
1727 // diagnostic — "failed to open cgroup.procs" / "short read
1728 // from notify pipe"). Return the sync error first and
1729 // discard the spawn error.
1730 sync_result?;
1731 spawn_result
1732}
1733
1734/// Actionable error wrapper for Command::spawn/.output failures.
1735/// ENOENT — the binary isn't on PATH inside the guest — gets the
1736/// remediation paths spelled out: `-i`/`--include-files` for CLI
1737/// invocations, pre-install in the initramfs for `#[ktstr_test]`
1738/// entries (which cannot pass `-i`). Other errors keep the minimal
1739/// `"spawn '<binary>'"` context so the underlying io::Error chain
1740/// surfaces unchanged.
1741///
1742/// **Shebang interpreter case.** `execve(2)` ALSO returns ENOENT
1743/// when `binary` is itself present but is a script whose `#!`
1744/// shebang names an interpreter that is missing in the guest
1745/// (e.g. `#!/usr/bin/python3` when python3 is absent from
1746/// initramfs). The kernel surfaces ENOENT with the script's path
1747/// even though the missing file is the interpreter — there is no
1748/// userspace signal that distinguishes "binary missing" from
1749/// "interpreter missing". The wrapped message therefore names
1750/// both the binary and the interpreter as candidate missing
1751/// artifacts and tells the operator to package both with `-i`
1752/// (CLI) or pre-install both in the initramfs
1753/// (`#[ktstr_test]`); the production message body carries this
1754/// guidance verbatim, the test
1755/// `spawn_error_context_enoent_attaches_remediation` pins it.
1756fn spawn_error_context(err: std::io::Error, binary: &str) -> anyhow::Error {
1757 if err.kind() == std::io::ErrorKind::NotFound {
1758 anyhow::Error::new(err).context(format!(
1759 "spawn '{binary}': binary not found on guest PATH. \
1760 Remediation: for CLI invocations (ktstr / cargo-ktstr \
1761 shell, run, …), package the binary with `-i {binary}` \
1762 / `--include-files {binary}` so it lands on the guest \
1763 PATH under `/include-files/`. For `#[ktstr_test]` \
1764 entries, pre-install the binary in the base initramfs \
1765 — the macro surface does not expose `-i`. If `{binary}` \
1766 is a script, execve(2) ALSO returns ENOENT when the \
1767 `#!` shebang names an interpreter missing from the \
1768 guest (the error names the script but the missing \
1769 file is the interpreter); package the interpreter \
1770 the same way — `-i <interpreter>` for CLI, pre-install \
1771 for `#[ktstr_test]`."
1772 ))
1773 } else {
1774 anyhow::Error::new(err).context(format!("spawn '{binary}'"))
1775 }
1776}
1777
1778/// RAII guard that saves the process's `SIGCHLD` disposition, sets
1779/// it to `SIG_DFL` on construction, and restores the saved value on
1780/// `Drop`. Required for [`spawn_and_wait`] and the background
1781/// [`spawn_child`] path because the guest ktstr-init sets
1782/// `SIGCHLD = SIG_IGN` at startup in `src/vmm/rust_init/init.rs`
1783/// ("Ignore SIGCHLD so child processes don't become zombies").
1784/// Under `SIG_IGN` the kernel auto-reaps children, so
1785/// `waitpid(child_pid)` returns `ECHILD` and Rust std's
1786/// `Command::spawn()` / `.output()` / `Child::wait()` internals
1787/// panic with "wait() should either return Ok or panic".
1788///
1789/// The shell-exec mode in `src/vmm/rust_init/modes.rs` already documents
1790/// this exact gotcha and uses the same save/set-`SIG_DFL` /
1791/// restore-on-completion pattern. `PayloadRun::run` /
1792/// `PayloadRun::spawn` are the second dispatch site that needs it.
1793///
1794/// For background spawns, the guard lives on [`PayloadHandle`]
1795/// until `.wait()` / `.kill()` / `Drop` consumes the handle, so
1796/// the child is reap-able via `waitpid` for the entire window
1797/// between spawn and final disposition. Foreground spawns
1798/// (`spawn_and_wait`) scope the guard to the `.output()` call —
1799/// the child is reaped inline, no lingering state.
1800/// Pins the [`ThreadId`] of the first `SigchldScope` constructed in
1801/// this process. Every subsequent construction must come from the
1802/// same thread: `libc::signal` is not thread-safe, and concurrent
1803/// installs from distinct threads would race on the process-wide
1804/// `SIGCHLD` disposition. The unset state of the `OnceLock` means
1805/// "uninitialized" (no `SigchldScope` has been constructed yet in
1806/// this process).
1807///
1808/// `ThreadId` is the std-library opaque thread identifier with
1809/// guaranteed uniqueness for the lifetime of the process and a
1810/// `PartialEq` impl that compares the underlying `NonZero<u64>`
1811/// directly. Storing the actual `ThreadId` (instead of a hash of
1812/// it) eliminates the collision-window risk that any hash-based
1813/// encoding carries, no matter how astronomically unlikely.
1814///
1815/// Multiple concurrent `SigchldScope` instances ARE allowed on
1816/// the same thread — each `PayloadHandle` carries one, and a
1817/// single-threaded caller can hold many handles simultaneously
1818/// without racing the libc::signal install. Drop order must
1819/// remain LIFO for the handler-restore chain to leave the
1820/// original disposition intact; this is the caller's obligation
1821/// (handles dropped in reverse creation order, which is the
1822/// default when locals go out of scope).
1823static SIGCHLD_SCOPE_OWNER_THREAD: OnceLock<ThreadId> = OnceLock::new();
1824
1825struct SigchldScope {
1826 prev: libc::sighandler_t,
1827 /// Marker that makes `SigchldScope` `!Send` AND `!Sync` at the
1828 /// type-system level. `libc::sighandler_t` is `size_t` on Linux
1829 /// (a plain integer that auto-implements both `Send` and `Sync`),
1830 /// so without this marker the struct would be `Send + Sync` and
1831 /// the compiler would silently accept a move across thread
1832 /// boundaries. The `OnceLock`-based runtime pin in `new` and
1833 /// `drop` only catches an actual install/restore on the wrong
1834 /// thread; the `PhantomData<*const ()>` adds a compile-time
1835 /// barrier so a `thread::spawn(move || { let _ = scope; })`
1836 /// fails to type-check instead of relying on the runtime check
1837 /// to catch it.
1838 ///
1839 /// `*const T` carries explicit `!Send` and `!Sync` negative
1840 /// impls in `core::marker` (`impl<T: PointeeSized> !Send for
1841 /// *const T` at marker.rs:100, `impl<T: PointeeSized> !Sync for
1842 /// *const T` at marker.rs:680). `Send` and `Sync` are
1843 /// independent auto traits — neither implies the other — and
1844 /// `PhantomData<T>` (a generic struct with no manual Send/Sync
1845 /// impl) propagates each independently via auto-trait
1846 /// inference. So `PhantomData<*const ()>` is `!Send` because
1847 /// `*const ()` is `!Send`, AND `!Sync` because `*const ()` is
1848 /// `!Sync`. Both come from the marker, not from one implying
1849 /// the other.
1850 _not_send: std::marker::PhantomData<*const ()>,
1851}
1852
1853impl SigchldScope {
1854 /// Save current `SIGCHLD` handler and install `SIG_DFL`.
1855 /// On host builds the init never flips SIGCHLD to SIG_IGN, so
1856 /// `prev` equals `SIG_DFL` and Drop is a no-op mathematically
1857 /// — the extra syscall is cheap and keeps behavior uniform
1858 /// between host and guest.
1859 ///
1860 /// # Panics
1861 ///
1862 /// Panics if called from a thread different from the one that
1863 /// constructed the first `SigchldScope` in this process.
1864 /// `libc::signal` is not thread-safe and cross-thread installs
1865 /// would race on the process-wide SIGCHLD disposition.
1866 fn new() -> Self {
1867 let tid = std::thread::current().id();
1868 // Pin the first thread that ever constructs a SigchldScope
1869 // in this process via `OnceLock::get_or_init`, then enforce
1870 // the pin on every subsequent construction. `get_or_init`
1871 // is internally synchronized: concurrent first-callers
1872 // race only on which one's `init` closure runs, and the
1873 // others observe the winner's value via the same call. The
1874 // returned reference is the canonical pinned ThreadId.
1875 let pinned = SIGCHLD_SCOPE_OWNER_THREAD.get_or_init(|| tid);
1876 if *pinned != tid {
1877 panic!(
1878 "SigchldScope constructed on a different thread than the first \
1879 owner (pinned thread id={pinned:?}, this thread's id={tid:?}). \
1880 libc::signal is not thread-safe; cross-thread installs race on \
1881 the process-wide SIGCHLD disposition."
1882 );
1883 }
1884 // SAFETY: SIGCHLD_SCOPE_OWNER_THREAD pins construction to
1885 // a single thread across the whole process, so no other
1886 // thread is concurrently installing a SIGCHLD handler.
1887 // The `_not_send: PhantomData<*const ()>` field below makes
1888 // the type `!Send` so a move across threads fails to compile
1889 // — Drop is guaranteed to run on the same thread that
1890 // constructed the scope.
1891 let prev = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
1892 SigchldScope {
1893 prev,
1894 _not_send: std::marker::PhantomData,
1895 }
1896 }
1897}
1898
1899impl Drop for SigchldScope {
1900 fn drop(&mut self) {
1901 // Defense-in-depth: the `!Send` marker on the struct
1902 // prevents a compile-time cross-thread move, but a future
1903 // refactor that adds an explicit `unsafe impl Send`
1904 // workaround would silently bypass that guard. Re-check the
1905 // owner-thread pin at drop time so a wrong-thread restore
1906 // panics loudly instead of quietly racing the process-wide
1907 // SIGCHLD disposition.
1908 let pinned = SIGCHLD_SCOPE_OWNER_THREAD
1909 .get()
1910 .expect("SIGCHLD_SCOPE_OWNER_THREAD must be initialized — set by SigchldScope::new");
1911 assert_eq!(
1912 *pinned,
1913 std::thread::current().id(),
1914 "SigchldScope dropped on a different thread than the pinned owner \
1915 (pinned={pinned:?}, this thread={:?}). libc::signal is not \
1916 thread-safe and the construct-side `!Send` marker should have \
1917 made this impossible at compile time — investigate any \
1918 `unsafe impl Send for SigchldScope` that bypassed it.",
1919 std::thread::current().id(),
1920 );
1921 // SAFETY: same rationale as `new` — the owner-thread pin
1922 // guarantees no concurrent installer on another thread.
1923 // Restoring in LIFO order across nested scopes unwinds
1924 // back to the original disposition; drop-order is the
1925 // caller's obligation.
1926 unsafe {
1927 libc::signal(libc::SIGCHLD, self.prev);
1928 }
1929 }
1930}
1931
1932// Compile-time pin: `SigchldScope` must be neither `Send` nor `Sync`.
1933//
1934// `SigchldScope::new` and its `Drop` install/restore the process-wide
1935// `SIGCHLD` disposition via `libc::signal`, which is documented as
1936// async-signal-safe but not thread-safe with respect to concurrent
1937// installs. The `_not_send: PhantomData<*const ()>` field at the
1938// struct definition is what makes the type `!Send` AND `!Sync`.
1939// `Send` and `Sync` are independent auto traits — neither implies
1940// the other. `*const T` carries explicit `!Send` and `!Sync`
1941// negative impls in `core::marker` (`impl<T: PointeeSized> !Send
1942// for *const T` at marker.rs:100, `impl<T: PointeeSized> !Sync for
1943// *const T` at marker.rs:680), and `PhantomData<T>` propagates each
1944// independently via auto-trait inference. So `PhantomData<*const
1945// ()>` is `!Send` because `*const ()` is `!Send`, AND `!Sync`
1946// because `*const ()` is `!Sync` — both from the marker, not from
1947// one implying the other. This block re-asserts that invariant at
1948// compile time so a future refactor that drops the marker, replaces
1949// it with a `Send` type, or adds an explicit `unsafe impl
1950// Send`/`unsafe impl Sync` for `SigchldScope` fails to compile here
1951// instead of silently allowing a cross-thread move that would race
1952// the SIGCHLD install on another thread.
1953//
1954// Mechanism (mirrors `static_assertions::assert_not_impl_any!`): a
1955// blanket `AmbiguousIfImpl<()>` impl applies to every type, while a
1956// specialized `AmbiguousIfImpl<Invalid{Send,Sync}>` impl applies only
1957// to types that `Send` / `Sync` respectively. If `SigchldScope`
1958// implemented either, two impls would match `AmbiguousIfImpl<_>` and
1959// type inference for `_` would be ambiguous, producing a compile
1960// error. With `SigchldScope: !Send + !Sync`, only the blanket impl
1961// matches and the assertion compiles.
1962//
1963// `static_assertions` is a transitive dep (via `compact_str`) but not
1964// a direct dependency; inlining the trick keeps the assertion local
1965// without growing the direct dep graph for one use site.
1966const _: fn() = || {
1967 trait AmbiguousIfImpl<A> {
1968 fn some_item() {}
1969 }
1970 impl<T: ?Sized> AmbiguousIfImpl<()> for T {}
1971
1972 #[allow(dead_code)]
1973 struct InvalidSend;
1974 impl<T: ?Sized + Send> AmbiguousIfImpl<InvalidSend> for T {}
1975
1976 #[allow(dead_code)]
1977 struct InvalidSync;
1978 impl<T: ?Sized + Sync> AmbiguousIfImpl<InvalidSync> for T {}
1979
1980 let _ = <SigchldScope as AmbiguousIfImpl<_>>::some_item;
1981};
1982
1983/// Foreground path: spawn + wait + capture. Used by `.run()`.
1984///
1985/// Wraps the child's lifetime in a [`SigchldScope`] so `waitpid`
1986/// sees `SIG_DFL` and returns the child's real exit status instead
1987/// of `ECHILD` under the guest init's `SIGCHLD = SIG_IGN`.
1988///
1989/// When `timeout` is `Some`, a poll loop bounds the payload's
1990/// runtime. Exceeding the deadline fires
1991/// [`kill_payload_process_group`] (killpg + single-pid SIGKILL)
1992/// so fork descendants die and release the pipes, then
1993/// [`wait_and_capture`] drains whatever output accumulated before
1994/// the kill. The `SpawnOutput` returned on timeout carries the
1995/// partial output and the post-kill exit code; the caller decides
1996/// whether that counts as a test failure.
1997fn spawn_and_wait(
1998 binary: &str,
1999 args: &[String],
2000 cgroup: Option<(&str, &std::path::Path)>,
2001 timeout: Option<Duration>,
2002 uses_parent_pgrp: bool,
2003 cgroup_ops: &dyn crate::cgroup::CgroupOps,
2004) -> Result<SpawnOutput> {
2005 let _sigchld = SigchldScope::new();
2006 let (cmd, sync_handles) = build_command(binary, args, cgroup, uses_parent_pgrp)?;
2007 let mut child = match sync_handles {
2008 Some(handles) => drive_cgroup_handshake(cmd, handles, binary, cgroup_ops)?,
2009 None => {
2010 let mut cmd = cmd;
2011 cmd.spawn().map_err(|e| spawn_error_context(e, binary))?
2012 }
2013 };
2014 match timeout {
2015 Some(deadline) => wait_with_deadline(&mut child, deadline, binary, uses_parent_pgrp),
2016 None => match wait_and_capture(&mut child) {
2017 Ok(out) => Ok(out),
2018 Err(e) => {
2019 kill_payload_process_group(&child, binary, uses_parent_pgrp);
2020 let _ = child.wait();
2021 Err(e)
2022 }
2023 },
2024 }
2025}
2026
2027/// Block in the kernel until the child exits or `timeout` elapses.
2028/// On expiry, kill the whole process group (killpg + single-pid
2029/// SIGKILL) and drain captured output.
2030///
2031/// Implementation uses `pidfd_open(2)` + `epoll_wait` so the waiter
2032/// is kernel-blocked instead of spinning on a 10ms `try_wait` loop.
2033/// The earlier poll burned one wake per 10ms for the entire payload
2034/// runtime (typically multi-second schbench / fio runs), producing a
2035/// small but measurable CPU spike on every timed payload; pidfd
2036/// parks the thread until the kernel signals child exit, so idle
2037/// waiters contribute zero CPU. Minimum kernel: Linux 5.3.
2038///
2039/// Deadline honoring: the `epoll_wait` timeout is re-derived from
2040/// `saturating_duration_since` each iteration so `EINTR` restarts
2041/// narrow the remaining window rather than extending it.
2042fn wait_with_deadline(
2043 child: &mut std::process::Child,
2044 timeout: Duration,
2045 payload_name: &str,
2046 uses_parent_pgrp: bool,
2047) -> Result<SpawnOutput> {
2048 use nix::sys::epoll::{Epoll, EpollCreateFlags, EpollEvent, EpollFlags, EpollTimeout};
2049 use std::os::fd::{AsFd, FromRawFd, OwnedFd};
2050
2051 let deadline = std::time::Instant::now() + timeout;
2052
2053 let pid =
2054 libc::pid_t::try_from(child.id()).expect("child pid fits in pid_t (Linux pid_max <= 2^22)");
2055 // `pidfd_open(pid, 0)`: returns an fd that becomes readable when
2056 // the pid exits. No `PIDFD_NONBLOCK` flag — epoll is the gate.
2057 let pidfd_raw = unsafe { libc::syscall(libc::SYS_pidfd_open, pid, 0i32) };
2058 if pidfd_raw < 0 {
2059 return Err(std::io::Error::last_os_error()).with_context(|| format!("pidfd_open({pid})"));
2060 }
2061 // SAFETY: the syscall succeeded and returned a fresh fd.
2062 let pidfd: OwnedFd = unsafe { OwnedFd::from_raw_fd(pidfd_raw as i32) };
2063
2064 let epoll = Epoll::new(EpollCreateFlags::EPOLL_CLOEXEC)
2065 .with_context(|| "epoll_create1 for pidfd wait")?;
2066 // `data` field is unused — we only ever watch one fd. The add()
2067 // syscall still needs an `EpollEvent` with populated events.
2068 let event = EpollEvent::new(EpollFlags::EPOLLIN, 0);
2069 epoll
2070 .add(pidfd.as_fd(), event)
2071 .with_context(|| "epoll_ctl ADD pidfd")?;
2072
2073 let mut events = [EpollEvent::empty()];
2074 loop {
2075 // Race-safe reap attempt first: if the child exited between
2076 // spawn and pidfd_open, or between iterations while we were
2077 // outside epoll_wait, `try_wait` catches it without a needless
2078 // syscall.
2079 if child
2080 .try_wait()
2081 .with_context(|| "try_wait child")?
2082 .is_some()
2083 {
2084 return match wait_and_capture(child) {
2085 Ok(out) => Ok(out),
2086 Err(e) => {
2087 kill_payload_process_group(child, payload_name, uses_parent_pgrp);
2088 let _ = child.wait();
2089 Err(e)
2090 }
2091 };
2092 }
2093
2094 let remaining = deadline.saturating_duration_since(std::time::Instant::now());
2095 if remaining.is_zero() {
2096 kill_payload_process_group(child, payload_name, uses_parent_pgrp);
2097 return match wait_and_capture(child) {
2098 Ok(out) => Ok(out),
2099 Err(e) => {
2100 let _ = child.wait();
2101 Err(e).with_context(|| format!("drain after timeout of {timeout:?}"))
2102 }
2103 };
2104 }
2105
2106 // `PollTimeout` (aliased as `EpollTimeout`) stores the value
2107 // as `i32`, so `TryFrom<u32>` rejects any input larger than
2108 // `i32::MAX` (~24.8 days of milliseconds). Clamp both casts —
2109 // `u128 → u32` and then `u32 → i32`-range — so a
2110 // `Duration::MAX`-shaped remainder saturates to the max
2111 // accepted value instead of bubbling up a conversion error.
2112 let ms_u32 = u32::try_from(remaining.as_millis()).unwrap_or(u32::MAX);
2113 let ms_u32 = std::cmp::min(ms_u32, i32::MAX as u32);
2114 let timeout_param =
2115 EpollTimeout::try_from(ms_u32).with_context(|| "epoll timeout conversion")?;
2116
2117 match epoll.wait(&mut events, timeout_param) {
2118 Ok(_) => {
2119 // Either the pidfd went readable (child exit) OR the
2120 // timeout fired (ready_count == 0). Loop back: the
2121 // `try_wait` at top handles the exit path, the
2122 // `remaining.is_zero()` branch handles the deadline.
2123 }
2124 Err(nix::errno::Errno::EINTR) => {
2125 // Signal interrupted the wait; loop and re-compute
2126 // the remaining window.
2127 }
2128 Err(e) => {
2129 return Err(anyhow::anyhow!("epoll_wait: {e}"));
2130 }
2131 }
2132 }
2133}
2134
2135/// Background path: spawn without waiting. Returns the live
2136/// [`std::process::Child`] plus a [`SigchldScope`] that must be held for the
2137/// child's lifetime — [`PayloadHandle`] keeps it alive until
2138/// `.wait()` / `.kill()` / `Drop` so `waitpid` during reap sees
2139/// `SIG_DFL` and observes the child's real exit.
2140fn spawn_child(
2141 binary: &str,
2142 args: &[String],
2143 cgroup: Option<(&str, &std::path::Path)>,
2144 uses_parent_pgrp: bool,
2145 cgroup_ops: &dyn crate::cgroup::CgroupOps,
2146) -> Result<(std::process::Child, SigchldScope)> {
2147 let sigchld = SigchldScope::new();
2148 let (cmd, sync_handles) = build_command(binary, args, cgroup, uses_parent_pgrp)?;
2149 let child = match sync_handles {
2150 Some(handles) => drive_cgroup_handshake(cmd, handles, binary, cgroup_ops)?,
2151 None => {
2152 let mut cmd = cmd;
2153 cmd.spawn().map_err(|e| spawn_error_context(e, binary))?
2154 }
2155 };
2156 Ok((child, sigchld))
2157}
2158
2159/// Per-stream cap on captured child output. 16 MiB covers every
2160/// realistic benchmark stdout in the crate (typical schbench /
2161/// stress-ng flows emit kilobytes to low-hundreds-of-KB)
2162/// with multiple orders of magnitude of slack, while cutting off
2163/// OOM pressure from a pathological payload that prints unbounded
2164/// GBs. Output past the cap is truncated, not errored, so downstream
2165/// (metric extraction, sidecar) still sees a prefix — the only loss
2166/// is the tail, which is rarely load-bearing. Each truncation emits
2167/// a paired `eprintln!` + `tracing::warn!` notice naming the stream
2168/// and the cap byte count.
2169pub(crate) const MAX_CAPTURED_STREAM_BYTES: u64 = 16 * 1024 * 1024;
2170
2171/// Reap a (possibly already-killed) [`std::process::Child`]: wait for it to
2172/// exit, drain stdout + stderr, return the captured output.
2173///
2174/// Takes `&mut Child` so callers retain ownership and can
2175/// `kill_payload_process_group` + `wait` to clean up descendants
2176/// when this function returns `Err` (e.g. a reader thread panicked
2177/// or the wait syscall itself failed). An owned-child signature
2178/// would lose the handle inside this function and leave descendants
2179/// running because `std::process::Child`'s `Drop` is a no-op.
2180///
2181/// Sequential stdout-then-stderr reads deadlock when the child
2182/// fills one pipe buffer (typically 64KiB) while the other is
2183/// unread — the child blocks on write, the parent blocks on read
2184/// of the empty pipe. Drain both pipes concurrently via helper
2185/// threads, mirroring what `std::process::Command::output` does
2186/// for the foreground path.
2187///
2188/// Each reader thread wraps its source in
2189/// `Read::take(MAX_CAPTURED_STREAM_BYTES)` — see the constant's
2190/// rationale — so a runaway child cannot OOM the host. The tail
2191/// past the cap is discarded; the metric-extraction pipeline
2192/// always receives a bounded buffer.
2193fn wait_and_capture(child: &mut std::process::Child) -> Result<SpawnOutput> {
2194 let stdout_handle = child.stdout.take().map(|out| {
2195 std::thread::spawn(move || -> std::io::Result<(String, bool)> {
2196 drain_capped(out, "stdout")
2197 })
2198 });
2199 let stderr_handle = child.stderr.take().map(|err| {
2200 std::thread::spawn(move || -> std::io::Result<(String, bool)> {
2201 drain_capped(err, "stderr")
2202 })
2203 });
2204 let status = child.wait().with_context(|| "wait child")?;
2205 // `.join().unwrap()` below is NOT a bug: the workspace builds
2206 // with `panic = "abort"` in release (see Cargo.toml
2207 // `[profile.release]`), so a panicked reader thread aborts the
2208 // whole process and `join()` never returns an
2209 // `Err(Box<dyn Any + Send>)` (`std::thread::Result::Err`). The
2210 // historic `.map_err(|_| anyhow!("...panicked"))` arm could not
2211 // fire and misled readers into expecting a recoverable error.
2212 //
2213 // Under cargo's default `panic = "unwind"` (which the dev and
2214 // test profiles both inherit — only `[profile.release]` flips
2215 // to abort in this crate), a reader-thread panic DOES unwind
2216 // into `thread::Result::Err`. The `.unwrap()` then re-panics on
2217 // the main thread, which is the key test-profile behavior: the
2218 // libtest / nextest harness installs a per-test panic hook that
2219 // catches the re-panic and reports it as a failed test with the
2220 // reader-thread's payload preserved. The alternative —
2221 // `.map_err(|_| anyhow!("..."))` — would erase the reader-
2222 // thread panic payload, surface a generic string through `?`,
2223 // and make the test pass look like "drain step returned Err"
2224 // when the true failure was a panic inside `drain_capped` (an
2225 // indexing-out-of-bounds on a malformed stream, say). The
2226 // panic=abort caller contract holds in release (whole-process
2227 // abort); debug/test callers get a loud re-panic with the
2228 // original panic payload visible. Either way no `Err` reaches
2229 // the `?` below.
2230 let (stdout, _stdout_truncated) = match stdout_handle {
2231 Some(h) => h.join().unwrap().with_context(|| "read child stdout")?,
2232 None => (String::new(), false),
2233 };
2234 let (stderr, _stderr_truncated) = match stderr_handle {
2235 Some(h) => h.join().unwrap().with_context(|| "read child stderr")?,
2236 None => (String::new(), false),
2237 };
2238 Ok(SpawnOutput {
2239 stdout,
2240 stderr,
2241 exit_code: status.code().unwrap_or(-1),
2242 })
2243}
2244
2245/// Read `src` into a `String` with `MAX_CAPTURED_STREAM_BYTES` cap.
2246/// Returns `(buf, truncated)`. Emits a paired `eprintln!` +
2247/// `tracing::warn!` notice with the stream label (e.g. "stdout" /
2248/// "stderr") and cap byte count when the cap is hit.
2249///
2250/// Truncation is performed at the byte level on a `Vec<u8>` so a
2251/// split multi-byte UTF-8 char at the cap boundary cannot panic.
2252/// The final `String::from_utf8_lossy` replaces any invalid UTF-8
2253/// bytes with U+FFFD — including the partial-char split that byte
2254/// truncation can introduce. Non-truncated output preserves the
2255/// original bytes verbatim when it is already valid UTF-8; the
2256/// only behavioral delta vs the pre-cap `read_to_string` path is
2257/// that invalid UTF-8 in the child's full output now produces
2258/// replacement chars instead of an `io::ErrorKind::InvalidData`
2259/// upstream error. That trade is deliberate: past the cap there is
2260/// no way to report "invalid UTF-8" meaningfully since the tail is
2261/// gone, and making the pre-cap path lossy keeps semantics uniform.
2262fn drain_capped(src: impl std::io::Read, label: &'static str) -> std::io::Result<(String, bool)> {
2263 use std::io::Read;
2264 // One extra byte probes whether the source had more to offer —
2265 // `Take` returns EOF at exactly the cap, indistinguishable from
2266 // a child that emitted exactly `cap` bytes. We cap our own buffer
2267 // at MAX + 1 and check the read count.
2268 let mut raw: Vec<u8> = Vec::new();
2269 let n = src
2270 .take(MAX_CAPTURED_STREAM_BYTES + 1)
2271 .read_to_end(&mut raw)?;
2272 let truncated = n as u64 > MAX_CAPTURED_STREAM_BYTES;
2273 if truncated {
2274 raw.truncate(MAX_CAPTURED_STREAM_BYTES as usize);
2275 // Dual-emit: stderr for nextest-direct test runs (no
2276 // tracing subscriber installed in the default test-support
2277 // dispatch path), tracing for cargo-ktstr-wrapped runs and
2278 // structured-log consumers. Same rationale as the prefetch
2279 // notices — a silent-truncation warn that only reaches the
2280 // no-op dispatcher fails the visibility goal of this check.
2281 eprintln!(
2282 "ktstr: payload {label} exceeded {MAX_CAPTURED_STREAM_BYTES} bytes; tail discarded"
2283 );
2284 tracing::warn!(
2285 stream = label,
2286 cap_bytes = MAX_CAPTURED_STREAM_BYTES,
2287 "payload {label} exceeded capture cap; tail discarded",
2288 );
2289 }
2290 Ok((String::from_utf8_lossy(&raw).into_owned(), truncated))
2291}
2292
2293#[cfg(test)]
2294mod tests {
2295 use super::*;
2296 use crate::cgroup::CgroupManager;
2297 use crate::test_support::{MetricStream, OutputFormat, Polarity, Scheduler};
2298 use crate::topology::TestTopology;
2299
2300 // Minimal Ctx builder fixture for tests — no VM boot.
2301 fn make_ctx<'a>(
2302 cgroups: &'a CgroupManager,
2303 topo: &'a TestTopology,
2304 ) -> crate::scenario::Ctx<'a> {
2305 crate::scenario::Ctx::builder(cgroups, topo).build()
2306 }
2307
2308 /// Closure-form helper that owns the CgroupManager + TestTopology
2309 /// pair under the closure's stack frame so a Ctx borrowed from
2310 /// them stays valid for the closure body. Collapses the 3-line
2311 /// `cgroups + topo + make_ctx` setup that every payload_run test
2312 /// repeats. Tests pick the `parent` cgroup path: tests that never
2313 /// resolve against a real FS pass `"/nonexistent"`; tests that
2314 /// assert `resolve_cgroup_path` output pass `"/sys/fs/cgroup/test-parent"`.
2315 fn with_ctx<R>(parent: &str, f: impl FnOnce(&crate::scenario::Ctx<'_>) -> R) -> R {
2316 let cgroups = CgroupManager::new(parent);
2317 let topo = TestTopology::synthetic(4, 1);
2318 let ctx = make_ctx(&cgroups, &topo);
2319 f(&ctx)
2320 }
2321
2322 #[cfg(unix)]
2323 fn parse_proc_stat_state_and_pgrp(
2324 stat: &[u8],
2325 pid: libc::pid_t,
2326 ) -> std::io::Result<(u8, libc::pid_t)> {
2327 let delimiter = stat
2328 .windows(2)
2329 .rposition(|window| window == b") ")
2330 .ok_or_else(|| {
2331 std::io::Error::new(
2332 std::io::ErrorKind::InvalidData,
2333 format!("/proc/{pid}/stat has no command terminator"),
2334 )
2335 })?;
2336 let suffix = std::str::from_utf8(&stat[delimiter + 2..]).map_err(|error| {
2337 std::io::Error::new(
2338 std::io::ErrorKind::InvalidData,
2339 format!("/proc/{pid}/stat is not UTF-8 after its command: {error}"),
2340 )
2341 })?;
2342 let mut fields = suffix.split_ascii_whitespace();
2343 let state = fields
2344 .next()
2345 .and_then(|field| field.as_bytes().first().copied())
2346 .ok_or_else(|| {
2347 std::io::Error::new(
2348 std::io::ErrorKind::InvalidData,
2349 format!("/proc/{pid}/stat has no process state"),
2350 )
2351 })?;
2352 let _ppid = fields.next().ok_or_else(|| {
2353 std::io::Error::new(
2354 std::io::ErrorKind::InvalidData,
2355 format!("/proc/{pid}/stat has no parent pid"),
2356 )
2357 })?;
2358 let pgrp = fields
2359 .next()
2360 .ok_or_else(|| {
2361 std::io::Error::new(
2362 std::io::ErrorKind::InvalidData,
2363 format!("/proc/{pid}/stat has no process group"),
2364 )
2365 })?
2366 .parse()
2367 .map_err(|error| {
2368 std::io::Error::new(
2369 std::io::ErrorKind::InvalidData,
2370 format!("/proc/{pid}/stat has an invalid process group: {error}"),
2371 )
2372 })?;
2373 Ok((state, pgrp))
2374 }
2375
2376 #[cfg(unix)]
2377 fn live_process_group_members(pgid: libc::pid_t) -> std::io::Result<Vec<(libc::pid_t, u8)>> {
2378 let mut live = Vec::new();
2379 for entry in std::fs::read_dir("/proc")? {
2380 let entry = entry?;
2381 let Some(pid) = entry
2382 .file_name()
2383 .to_str()
2384 .and_then(|name| name.parse::<libc::pid_t>().ok())
2385 else {
2386 continue;
2387 };
2388 let stat = match std::fs::read(entry.path().join("stat")) {
2389 Ok(stat) => stat,
2390 Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
2391 Err(error) => return Err(error),
2392 };
2393 let (state, member_pgid) = parse_proc_stat_state_and_pgrp(&stat, pid)?;
2394 if member_pgid == pgid && !matches!(state, b'Z' | b'X' | b'x') {
2395 live.push((pid, state));
2396 }
2397 }
2398 Ok(live)
2399 }
2400
2401 /// Wait until a process group has no live members.
2402 ///
2403 /// `killpg(pgid, 0)` continues succeeding while a killed descendant is a
2404 /// zombie owned by an outer CI subreaper. Such a process is conclusively
2405 /// dead, but this test process cannot call `wait(2)` on it. Inspecting the
2406 /// process state keeps the teardown assertion strict about live members
2407 /// without confusing supervisor-owned zombies for surviving workloads.
2408 #[cfg(unix)]
2409 fn wait_for_process_group_termination(
2410 pgid: libc::pid_t,
2411 timeout: std::time::Duration,
2412 context: &str,
2413 ) {
2414 let deadline = std::time::Instant::now() + timeout;
2415 loop {
2416 // SAFETY: signal zero is an existence/permission probe and does
2417 // not alter any member of the process group.
2418 let probe = unsafe { libc::killpg(pgid, 0) };
2419 if probe != 0 {
2420 let error = std::io::Error::last_os_error();
2421 assert_eq!(
2422 error.raw_os_error(),
2423 Some(libc::ESRCH),
2424 "unexpected errno probing process group {pgid} after {context}: {error}",
2425 );
2426 return;
2427 }
2428
2429 let live = live_process_group_members(pgid)
2430 .unwrap_or_else(|error| panic!("inspect process group {pgid}: {error}"));
2431 if live.is_empty() {
2432 return;
2433 }
2434 if std::time::Instant::now() >= deadline {
2435 panic!("process group {pgid} still has live members after {context}: {live:?}",);
2436 }
2437 std::thread::sleep(std::time::Duration::from_millis(20));
2438 }
2439 }
2440
2441 #[cfg(unix)]
2442 #[test]
2443 fn proc_stat_parser_handles_spaces_and_parentheses_in_comm() {
2444 let stat = b"37 (worker ) with spaces) S 11 29 29 0 -1";
2445 assert_eq!(
2446 parse_proc_stat_state_and_pgrp(stat, 37).expect("parse synthetic stat"),
2447 (b'S', 29),
2448 );
2449 }
2450
2451 const FIO_BINARY: Payload = Payload {
2452 name: "fio",
2453 kind: PayloadKind::Binary("fio"),
2454 output: OutputFormat::Json,
2455 default_args: &["--output-format=json"],
2456 default_checks: &[],
2457 metrics: &[],
2458 include_files: &[],
2459 uses_parent_pgrp: false,
2460 known_flags: None,
2461 };
2462
2463 const EEVDF_SCHED_PAYLOAD: Payload = Payload {
2464 name: "eevdf",
2465 kind: PayloadKind::Scheduler(&Scheduler::EEVDF),
2466 output: OutputFormat::ExitCode,
2467 default_args: &[],
2468 default_checks: &[],
2469 metrics: &[],
2470 include_files: &[],
2471 uses_parent_pgrp: false,
2472 known_flags: None,
2473 };
2474
2475 #[test]
2476 fn builder_inherits_default_args() {
2477 with_ctx("/nonexistent", |ctx| {
2478 let run = PayloadRun::new(ctx, &FIO_BINARY);
2479 assert_eq!(run.args, vec!["--output-format=json"]);
2480 });
2481 }
2482
2483 #[test]
2484 fn arg_appends() {
2485 with_ctx("/nonexistent", |ctx| {
2486 let run = PayloadRun::new(ctx, &FIO_BINARY)
2487 .arg("--runtime=30")
2488 .arg("job.fio");
2489 assert_eq!(
2490 run.args,
2491 vec!["--output-format=json", "--runtime=30", "job.fio"]
2492 );
2493 });
2494 }
2495
2496 #[test]
2497 fn clear_args_wipes_defaults() {
2498 with_ctx("/nonexistent", |ctx| {
2499 let run = PayloadRun::new(ctx, &FIO_BINARY)
2500 .clear_args()
2501 .arg("--custom");
2502 assert_eq!(run.args, vec!["--custom"]);
2503 });
2504 }
2505
2506 #[test]
2507 fn args_method_bulk_appends() {
2508 with_ctx("/nonexistent", |ctx| {
2509 let run = PayloadRun::new(ctx, &FIO_BINARY).args(["--a", "--b", "--c"]);
2510 assert_eq!(run.args, vec!["--output-format=json", "--a", "--b", "--c"]);
2511 });
2512 }
2513
2514 #[test]
2515 fn check_and_clear_checks() {
2516 with_ctx("/nonexistent", |ctx| {
2517 let run = PayloadRun::new(ctx, &FIO_BINARY)
2518 .check(MetricCheck::min("iops", 1000.0))
2519 .check(MetricCheck::max("latency", 500.0));
2520 assert_eq!(run.checks.len(), 2);
2521 let cleared = PayloadRun::new(ctx, &FIO_BINARY)
2522 .clear_checks()
2523 .check(MetricCheck::exit_code_eq(0));
2524 assert_eq!(cleared.checks.len(), 1);
2525 });
2526 }
2527
2528 #[test]
2529 fn in_cgroup_stores_name() {
2530 with_ctx("/nonexistent", |ctx| {
2531 let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("fio_cg");
2532 assert_eq!(run.cgroup.as_deref(), Some("fio_cg"));
2533 });
2534 }
2535
2536 #[test]
2537 fn resolve_cgroup_path_strips_leading_slash_and_joins() {
2538 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2539 // Leading "/" tolerated, joined under parent.
2540 let resolved = resolve_cgroup_path(ctx, Some("/workload"), "test::strips")
2541 .expect("valid cgroup name")
2542 .expect("Some(path)");
2543 assert_eq!(
2544 resolved,
2545 std::path::PathBuf::from("/sys/fs/cgroup/test-parent/workload")
2546 );
2547 // Same name without leading slash produces the same path.
2548 let plain = resolve_cgroup_path(ctx, Some("workload"), "test::strips")
2549 .expect("valid")
2550 .expect("Some");
2551 assert_eq!(resolved, plain);
2552 });
2553 }
2554
2555 #[test]
2556 fn resolve_cgroup_path_rejects_parent_dir() {
2557 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2558 let err = resolve_cgroup_path(ctx, Some("../escape"), "PayloadRun::run")
2559 .expect_err("'..' must be rejected");
2560 let rendered = format!("{err:#}");
2561 assert!(rendered.contains(".."), "err: {rendered}");
2562 assert!(
2563 rendered.contains("PayloadRun::run"),
2564 "op label must appear in error: {rendered}",
2565 );
2566 });
2567 }
2568
2569 #[test]
2570 fn resolve_cgroup_path_rejects_nul_byte() {
2571 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2572 let err = resolve_cgroup_path(ctx, Some("bad\0name"), "PayloadRun::spawn")
2573 .expect_err("NUL must be rejected");
2574 let rendered = format!("{err:#}");
2575 assert!(rendered.contains("NUL"), "err: {rendered}");
2576 assert!(
2577 rendered.contains("PayloadRun::spawn"),
2578 "op label must appear in error: {rendered}",
2579 );
2580 });
2581 }
2582
2583 #[test]
2584 fn resolve_cgroup_path_rejects_empty_after_strip() {
2585 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2586 // "/" strips to empty — reject so we don't silently target
2587 // the parent cgroup itself.
2588 let err = resolve_cgroup_path(ctx, Some("/"), "PayloadRun::run")
2589 .expect_err("slash-only must be rejected");
2590 let rendered = format!("{err:#}");
2591 assert!(rendered.contains("empty"), "err: {rendered}");
2592 assert!(
2593 rendered.contains("PayloadRun::run"),
2594 "op label must appear in error: {rendered}",
2595 );
2596 let err = resolve_cgroup_path(ctx, Some(""), "PayloadRun::run")
2597 .expect_err("empty must be rejected");
2598 let rendered = format!("{err:#}");
2599 assert!(rendered.contains("empty"), "err: {rendered}");
2600 assert!(
2601 rendered.contains("PayloadRun::run"),
2602 "op label must appear in error: {rendered}",
2603 );
2604 });
2605 }
2606
2607 #[test]
2608 fn resolve_cgroup_path_none_passes_through() {
2609 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2610 assert!(
2611 resolve_cgroup_path(ctx, None, "test::none")
2612 .unwrap()
2613 .is_none()
2614 );
2615 });
2616 }
2617
2618 /// Differential pin: the `op` label must flow through to the
2619 /// rendered error verbatim, distinct per caller. Catches the
2620 /// regression where the parameter is accepted but ignored
2621 /// (e.g. a refactor that hardcodes one label in the
2622 /// `anyhow!` message). Without this, per-caller assertions
2623 /// could pass against an implementation that drops the arg.
2624 #[test]
2625 fn resolve_cgroup_path_op_label_differs_per_caller() {
2626 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2627 let err_a = format!(
2628 "{:#}",
2629 resolve_cgroup_path(ctx, Some("../bad"), "caller-a")
2630 .expect_err("'..' must be rejected"),
2631 );
2632 let err_b = format!(
2633 "{:#}",
2634 resolve_cgroup_path(ctx, Some("../bad"), "caller-b")
2635 .expect_err("'..' must be rejected"),
2636 );
2637 assert!(err_a.contains("caller-a"), "err_a: {err_a}");
2638 assert!(
2639 !err_a.contains("caller-b"),
2640 "err_a leaked caller-b: {err_a}"
2641 );
2642 assert!(err_b.contains("caller-b"), "err_b: {err_b}");
2643 assert!(
2644 !err_b.contains("caller-a"),
2645 "err_b leaked caller-a: {err_b}"
2646 );
2647 });
2648 }
2649
2650 /// Production-caller pin: the public `.run()` entry point must
2651 /// actually pass `"PayloadRun::run"` (and not, e.g.,
2652 /// `"PayloadRun::spawn"` via a copy-paste typo) when calling
2653 /// resolve_cgroup_path. The helper-level differential test above
2654 /// only proves the parameter isn't dropped — this test exercises
2655 /// the production call site inside `PayloadRun::run()` end-to-end.
2656 #[test]
2657 fn payload_run_run_threads_canonical_op_label() {
2658 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2659 let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("../escape");
2660 let err = run.run().unwrap_err();
2661 let rendered = format!("{err:#}");
2662 assert!(rendered.contains(".."), "err: {rendered}");
2663 assert!(
2664 rendered.contains("PayloadRun::run"),
2665 "production run() must pass PayloadRun::run as op label: {rendered}",
2666 );
2667 });
2668 }
2669
2670 /// Sibling of `payload_run_run_threads_canonical_op_label` for
2671 /// the `PayloadRun::spawn()` entry point. Uses a NUL-byte
2672 /// cgroup name (different validation branch from the run()
2673 /// test's `..`) to guard against a hypothetical refactor that
2674 /// hardcodes one op label across all anyhow! sites in
2675 /// resolve_cgroup_path.
2676 #[test]
2677 fn payload_run_spawn_threads_canonical_op_label() {
2678 with_ctx("/sys/fs/cgroup/test-parent", |ctx| {
2679 let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("bad\0name");
2680 let err = run.spawn().unwrap_err();
2681 let rendered = format!("{err:#}");
2682 assert!(rendered.contains("NUL"), "err: {rendered}");
2683 assert!(
2684 rendered.contains("PayloadRun::spawn"),
2685 "production spawn() must pass PayloadRun::spawn as op label: {rendered}",
2686 );
2687 });
2688 }
2689
2690 #[test]
2691 fn run_rejects_scheduler_kind() {
2692 with_ctx("/nonexistent", |ctx| {
2693 let run = PayloadRun::new(ctx, &EEVDF_SCHED_PAYLOAD);
2694 let err = run.run().unwrap_err();
2695 assert!(
2696 format!("{err:#}").contains("scheduler-kind"),
2697 "err: {err:#}"
2698 );
2699 });
2700 }
2701
2702 #[test]
2703 fn evaluate_checks_passes_when_no_checks() {
2704 let pm = PayloadMetrics {
2705 payload_index: 0,
2706 metrics: vec![],
2707 exit_code: 0,
2708 };
2709 let r = evaluate_checks(&[], &pm, "");
2710 assert!(r.is_pass());
2711 }
2712
2713 #[test]
2714 fn evaluate_checks_exit_code_mismatch_fails_fast() {
2715 let pm = PayloadMetrics {
2716 payload_index: 0,
2717 metrics: vec![],
2718 exit_code: 42,
2719 };
2720 let checks = [
2721 MetricCheck::exit_code_eq(0),
2722 MetricCheck::min("iops", 100.0),
2723 ];
2724 let r = evaluate_checks(&checks, &pm, "");
2725 assert!(r.is_fail());
2726 // exit-code failure short-circuits — only one detail, not
2727 // a "missing metric" detail from the min check.
2728 assert_eq!(r.outcomes.len(), 1);
2729 assert!(
2730 r.failure_details()
2731 .next()
2732 .unwrap()
2733 .message
2734 .contains("exited with code 42"),
2735 "details: {:?}",
2736 r.outcomes
2737 );
2738 }
2739
2740 #[test]
2741 fn evaluate_checks_exit_code_mismatch_surfaces_stderr() {
2742 let pm = PayloadMetrics {
2743 payload_index: 0,
2744 metrics: vec![],
2745 exit_code: 1,
2746 };
2747 let r = evaluate_checks(
2748 &[MetricCheck::exit_code_eq(0)],
2749 &pm,
2750 "fatal: config missing\n",
2751 );
2752 assert!(r.is_fail());
2753 assert!(
2754 r.failure_details()
2755 .next()
2756 .unwrap()
2757 .message
2758 .contains("fatal: config missing"),
2759 "stderr tail must appear in detail: {:?}",
2760 r.outcomes,
2761 );
2762 assert!(
2763 r.failure_details()
2764 .next()
2765 .unwrap()
2766 .message
2767 .contains("stderr:"),
2768 "detail must label the stderr block: {:?}",
2769 r.outcomes,
2770 );
2771 }
2772
2773 #[test]
2774 fn evaluate_checks_exit_code_mismatch_without_stderr_stays_terse() {
2775 let pm = PayloadMetrics {
2776 payload_index: 0,
2777 metrics: vec![],
2778 exit_code: 1,
2779 };
2780 let r = evaluate_checks(&[MetricCheck::exit_code_eq(0)], &pm, "");
2781 assert!(r.is_fail());
2782 // Empty stderr → no "stderr:" prefix in the detail.
2783 assert!(
2784 !r.failure_details()
2785 .next()
2786 .unwrap()
2787 .message
2788 .contains("stderr:"),
2789 "empty stderr must not produce a stderr: block: {:?}",
2790 r.outcomes,
2791 );
2792 }
2793
2794 /// Signal-terminated payloads report `exit_code = -1` because
2795 /// `std::process::ExitStatus::code()` returns `None` on
2796 /// signal death and the spawn layer maps that to `-1` (see
2797 /// `spawn_and_wait`). A user who expects the signal-death
2798 /// case can assert `MetricCheck::exit_code_eq(-1)`, and the pre-pass
2799 /// comparison must pass under exact `i32` equality.
2800 #[test]
2801 fn evaluate_checks_exit_code_eq_negative_one_matches_signal_death() {
2802 let pm = PayloadMetrics {
2803 payload_index: 0,
2804 metrics: vec![],
2805 exit_code: -1,
2806 };
2807 let r = evaluate_checks(&[MetricCheck::exit_code_eq(-1)], &pm, "");
2808 assert!(
2809 r.is_pass(),
2810 "exit_code_eq(-1) must pass when exit_code == -1: {:?}",
2811 r.outcomes,
2812 );
2813 }
2814
2815 /// Symmetric negative case: `MetricCheck::exit_code_eq(-1)` against a
2816 /// CLEAN exit (`exit_code == 0`) must fail and surface the
2817 /// mismatch with both integers printed so the user sees what
2818 /// they asked for vs what happened.
2819 #[test]
2820 fn evaluate_checks_exit_code_eq_negative_one_fails_on_clean_exit() {
2821 let pm = PayloadMetrics {
2822 payload_index: 0,
2823 metrics: vec![],
2824 exit_code: 0,
2825 };
2826 let r = evaluate_checks(&[MetricCheck::exit_code_eq(-1)], &pm, "");
2827 assert!(r.is_fail());
2828 let msg = &*r.failure_details().next().unwrap().message;
2829 assert!(
2830 msg.contains("exited with code 0"),
2831 "mismatch detail must cite the actual exit code, got: {msg}"
2832 );
2833 assert!(
2834 msg.contains("-1"),
2835 "mismatch detail must cite the expected exit code, got: {msg}"
2836 );
2837 }
2838
2839 /// Reversed bounds (`lo > hi`) cannot reach the evaluator —
2840 /// `MetricCheck::range` panics at construction (see
2841 /// `check_range_reversed_bounds_panics_at_construction` in
2842 /// `test_support::payload`). Pin the constructor-side panic
2843 /// here so a future relaxation that lets reversed ranges flow
2844 /// into the evaluator (and silently fail every metric) trips
2845 /// this guard instead of slipping past CI.
2846 #[test]
2847 #[should_panic(expected = "lo must be <= hi")]
2848 fn evaluate_checks_range_reversed_bounds_panics_at_construction() {
2849 let _ = MetricCheck::range("iops", 100.0, 50.0);
2850 }
2851
2852 #[test]
2853 fn stderr_tail_truncates_long_input() {
2854 // Build >STDERR_TAIL_BYTES of ASCII so char-boundary logic
2855 // is a no-op and the tail size is deterministic.
2856 let long: String = "A".repeat(STDERR_TAIL_BYTES + 500);
2857 let tail = stderr_tail(&long, STDERR_TAIL_BYTES);
2858 assert!(tail.starts_with("..."));
2859 // Leading "..." + exactly STDERR_TAIL_BYTES of suffix.
2860 assert_eq!(tail.len(), STDERR_TAIL_BYTES + 3);
2861 }
2862
2863 #[test]
2864 fn stderr_tail_preserves_short_input() {
2865 let tail = stderr_tail("short error", STDERR_TAIL_BYTES);
2866 assert_eq!(tail, "short error");
2867 }
2868
2869 /// When `s.len() - max_bytes` lands inside a multi-byte UTF-8
2870 /// code unit, `stderr_tail` snaps the start index forward to the
2871 /// next char boundary so the slice operation never panics. This
2872 /// test uses a 2-byte UTF-8 character ("é") placed at the exact
2873 /// boundary so a naive `&s[start..]` would slice mid-codepoint.
2874 #[test]
2875 fn stderr_tail_snaps_forward_across_multibyte_char_boundary() {
2876 // "A"*10 + "é" + "B"*10 → 22 bytes total, len 22, "é" = 2 bytes.
2877 // With max_bytes = 11, start = 22 - 11 = 11. The byte at 11 is
2878 // the second byte of "é" (non-boundary). The snap-forward
2879 // advances start to 12, yielding the trailing "B"*10 + preamble.
2880 let mut s = String::from("A").repeat(10);
2881 s.push('é');
2882 s.push_str(&"B".repeat(10));
2883 let tail = stderr_tail(&s, 11);
2884 assert!(tail.starts_with("..."));
2885 // The multi-byte char must have been skipped (advanced off its
2886 // interior), so the tail begins with ASCII "B"s.
2887 assert!(
2888 tail[3..].starts_with('B'),
2889 "expected snap-forward past 'é', got: {tail:?}"
2890 );
2891 }
2892
2893 /// When the whole multi-byte character sits at the snap-forward
2894 /// boundary (start lands exactly on its first byte), the
2895 /// character is preserved intact — no off-by-one that drops its
2896 /// first byte.
2897 #[test]
2898 fn stderr_tail_preserves_multibyte_char_at_exact_boundary() {
2899 // Build a string so the multi-byte char starts exactly at the
2900 // snap-forward position. ASCII x10 + "é" (2B) + ASCII x10
2901 // = 22B. max_bytes = 12 → start = 22-12 = 10, which IS "é"'s
2902 // first byte (a boundary). No snap happens; "é" is included.
2903 let mut s = String::from("A").repeat(10);
2904 s.push('é');
2905 s.push_str(&"B".repeat(10));
2906 let tail = stderr_tail(&s, 12);
2907 assert!(tail.starts_with("..."));
2908 assert!(
2909 tail.contains('é'),
2910 "boundary-aligned multibyte char must survive the tail, got: {tail:?}"
2911 );
2912 }
2913
2914 /// For every `max_bytes` offset across a string with an interior
2915 /// multi-byte char, `stderr_tail`'s output is a faithful suffix of
2916 /// the input — not just valid UTF-8 (which `String` guarantees for
2917 /// free). The body after any leading `...` marker must be a suffix
2918 /// of `s`, and the truncation must never lengthen the content.
2919 /// Pins the slice CONTENT across every byte offset, catching a
2920 /// snap-direction or off-by-one regression that the prior
2921 /// discard-the-result loop could not see.
2922 #[test]
2923 fn stderr_tail_output_is_suffix_of_input_at_every_offset() {
2924 // Chinese "好" = 3 bytes (E5 A5 BD); pin it mid-string.
2925 let s = "xxxxxxxxxx好yyyyyyyyyy"; // 10 + 3 + 10 = 23 bytes
2926 for max in 1..=s.len() {
2927 let tail = stderr_tail(s, max);
2928 if s.len() <= max {
2929 // No truncation: returns the input verbatim, no marker.
2930 assert_eq!(tail, s, "max={max}: short input must round-trip");
2931 assert!(
2932 !tail.starts_with("..."),
2933 "max={max}: no marker when untruncated"
2934 );
2935 } else {
2936 // Truncated: leading "..." marker, then a suffix of s.
2937 let body = tail.strip_prefix("...").unwrap_or_else(|| {
2938 panic!("max={max}: truncated output must carry the marker, got {tail:?}")
2939 });
2940 assert!(
2941 s.ends_with(body),
2942 "max={max}: body {body:?} must be a suffix of the input {s:?}",
2943 );
2944 // Snap-forward only ever drops bytes from the front, so
2945 // the retained suffix is at most `max` bytes and never
2946 // longer than the input.
2947 assert!(
2948 body.len() <= max,
2949 "max={max}: retained suffix {} bytes exceeds the {max}-byte budget",
2950 body.len(),
2951 );
2952 // The boundary snap must keep the suffix a valid char
2953 // boundary of s (no mid-codepoint split) — equivalent
2954 // to: stripping `body` off the end of s leaves a valid
2955 // str whose remainder + body reconstructs s exactly.
2956 let head_len = s.len() - body.len();
2957 assert!(
2958 s.is_char_boundary(head_len),
2959 "max={max}: suffix start {head_len} must be a char boundary of {s:?}",
2960 );
2961 }
2962 }
2963 }
2964
2965 /// Production-scale counterpart to the boundary tests above. The
2966 /// existing small-string cases use ~20 bytes, well below the
2967 /// production [`STDERR_TAIL_BYTES`] threshold of 1024. This test
2968 /// lands a multi-byte character's interior byte on the truncation
2969 /// offset of a >1 KiB string, matching the actual shape of an
2970 /// overflowing stderr from a real payload. The snap-forward must
2971 /// advance past the interior byte so `stderr_tail` does not panic
2972 /// on mid-codepoint slicing.
2973 #[test]
2974 fn stderr_tail_snaps_forward_at_production_threshold() {
2975 // Layout: "A"*100 + "é" (2B) + "B"*1023 = 1125 bytes.
2976 // start = 1125 - 1024 = 101 — the interior byte of "é"
2977 // (whose boundary bytes are at 100 and 102). The snap-forward
2978 // advances start to 102, so the tail begins with the "B"
2979 // suffix rather than a corrupt split "é".
2980 let mut s = "A".repeat(100);
2981 s.push('é');
2982 s.push_str(&"B".repeat(1023));
2983 assert!(
2984 s.len() > STDERR_TAIL_BYTES,
2985 "fixture must exceed STDERR_TAIL_BYTES to exercise the truncation path",
2986 );
2987 let tail = stderr_tail(&s, STDERR_TAIL_BYTES);
2988 assert!(tail.starts_with("..."));
2989 assert!(
2990 tail[3..].starts_with('B'),
2991 "expected snap-forward past 'é' interior byte at >1 KiB, got prefix: {:?}",
2992 &tail[..20.min(tail.len())],
2993 );
2994 }
2995
2996 /// Production-scale complement: when the truncation offset lands
2997 /// exactly on a multi-byte character's first byte (a boundary),
2998 /// the character survives — no off-by-one that would drop it.
2999 /// Covers the is_char_boundary-true branch of the snap-forward
3000 /// loop at the real [`STDERR_TAIL_BYTES`] size.
3001 #[test]
3002 fn stderr_tail_preserves_multibyte_at_production_boundary() {
3003 // Layout: "A"*100 + "é" (2B) + "B"*1022 = 1124 bytes.
3004 // start = 1124 - 1024 = 100 — the first byte of "é" (which
3005 // IS a char boundary). No snap runs; "é" is included whole.
3006 let mut s = "A".repeat(100);
3007 s.push('é');
3008 s.push_str(&"B".repeat(1022));
3009 assert!(
3010 s.len() > STDERR_TAIL_BYTES,
3011 "fixture must exceed STDERR_TAIL_BYTES to exercise the truncation path",
3012 );
3013 let tail = stderr_tail(&s, STDERR_TAIL_BYTES);
3014 assert!(tail.starts_with("..."));
3015 assert!(
3016 tail.contains('é'),
3017 "boundary-aligned 'é' at the >1 KiB truncation offset must survive, got prefix: {:?}",
3018 &tail[..40.min(tail.len())],
3019 );
3020 }
3021
3022 #[test]
3023 fn evaluate_checks_missing_metric_fails_loudly() {
3024 let pm = PayloadMetrics {
3025 payload_index: 0,
3026 metrics: vec![],
3027 exit_code: 0,
3028 };
3029 let checks = [MetricCheck::min("iops", 100.0)];
3030 let r = evaluate_checks(&checks, &pm, "");
3031 assert!(r.is_fail());
3032 assert!(
3033 r.failure_details()
3034 .next()
3035 .unwrap()
3036 .message
3037 .contains("not found"),
3038 "details: {:?}",
3039 r.outcomes
3040 );
3041 }
3042
3043 #[test]
3044 fn evaluate_checks_min_below_threshold_fails() {
3045 let pm = PayloadMetrics {
3046 payload_index: 0,
3047 metrics: vec![Metric {
3048 name: "iops".to_string(),
3049 value: 50.0,
3050 polarity: Polarity::HigherBetter,
3051 unit: String::new(),
3052 stream: MetricStream::Stdout,
3053 }],
3054 exit_code: 0,
3055 };
3056 let r = evaluate_checks(&[MetricCheck::min("iops", 100.0)], &pm, "");
3057 assert!(r.is_fail());
3058 assert!(
3059 r.failure_details()
3060 .next()
3061 .unwrap()
3062 .message
3063 .contains("below minimum")
3064 );
3065 }
3066
3067 #[test]
3068 fn evaluate_checks_max_above_threshold_fails() {
3069 let pm = PayloadMetrics {
3070 payload_index: 0,
3071 metrics: vec![Metric {
3072 name: "lat".to_string(),
3073 value: 1000.0,
3074 polarity: Polarity::LowerBetter,
3075 unit: String::new(),
3076 stream: MetricStream::Stdout,
3077 }],
3078 exit_code: 0,
3079 };
3080 let r = evaluate_checks(&[MetricCheck::max("lat", 500.0)], &pm, "");
3081 assert!(r.is_fail());
3082 assert!(
3083 r.failure_details()
3084 .next()
3085 .unwrap()
3086 .message
3087 .contains("exceeds maximum")
3088 );
3089 }
3090
3091 #[test]
3092 fn evaluate_checks_range_out_of_bounds_fails() {
3093 let pm = PayloadMetrics {
3094 payload_index: 0,
3095 metrics: vec![Metric {
3096 name: "cpu".to_string(),
3097 value: 150.0,
3098 polarity: Polarity::Unknown,
3099 unit: String::new(),
3100 stream: MetricStream::Stdout,
3101 }],
3102 exit_code: 0,
3103 };
3104 let r = evaluate_checks(&[MetricCheck::range("cpu", 0.0, 100.0)], &pm, "");
3105 assert!(r.is_fail());
3106 assert!(
3107 r.failure_details()
3108 .next()
3109 .unwrap()
3110 .message
3111 .contains("outside")
3112 );
3113 }
3114
3115 /// IEEE 754 makes every comparison against NaN evaluate to
3116 /// false, so a naive `actual < min` would silently pass a
3117 /// `Min` check on a NaN-valued metric — exactly the case
3118 /// operators most need to flag, since NaN almost always means
3119 /// the metric extraction itself is broken (divide-by-zero,
3120 /// unparsed token, typed-measurement error). The fix routes
3121 /// NaN through `nan_metric` BEFORE the bound comparison, so
3122 /// the failure reads "metric '...' value is NaN" rather than
3123 /// silently green-lighting an unmeasurable value.
3124 #[test]
3125 fn evaluate_checks_min_nan_fails_with_nan_message() {
3126 let pm = PayloadMetrics {
3127 payload_index: 0,
3128 metrics: vec![Metric {
3129 name: "iops".to_string(),
3130 value: f64::NAN,
3131 polarity: Polarity::HigherBetter,
3132 unit: String::new(),
3133 stream: MetricStream::Stdout,
3134 }],
3135 exit_code: 0,
3136 };
3137 let r = evaluate_checks(&[MetricCheck::min("iops", 100.0)], &pm, "");
3138 assert!(!r.is_pass(), "NaN value must fail Min check");
3139 assert!(
3140 r.failure_details()
3141 .next()
3142 .unwrap()
3143 .message
3144 .contains("value is NaN"),
3145 "NaN failure must surface the dedicated message: {:?}",
3146 r.outcomes
3147 );
3148 }
3149
3150 /// Sibling of [`evaluate_checks_min_nan_fails_with_nan_message`]
3151 /// for the upper-bound path — `actual > max` is also false for
3152 /// NaN.
3153 #[test]
3154 fn evaluate_checks_max_nan_fails_with_nan_message() {
3155 let pm = PayloadMetrics {
3156 payload_index: 0,
3157 metrics: vec![Metric {
3158 name: "lat".to_string(),
3159 value: f64::NAN,
3160 polarity: Polarity::LowerBetter,
3161 unit: String::new(),
3162 stream: MetricStream::Stdout,
3163 }],
3164 exit_code: 0,
3165 };
3166 let r = evaluate_checks(&[MetricCheck::max("lat", 500.0)], &pm, "");
3167 assert!(!r.is_pass(), "NaN value must fail Max check");
3168 assert!(
3169 r.failure_details()
3170 .next()
3171 .unwrap()
3172 .message
3173 .contains("value is NaN"),
3174 "NaN failure must surface the dedicated message: {:?}",
3175 r.outcomes
3176 );
3177 }
3178
3179 /// Range gate sees NaN through both `actual < lo` and
3180 /// `actual > hi` — both false, so the legacy code accepted
3181 /// NaN as in-range. The fix routes NaN through `nan_metric`
3182 /// before the range comparison.
3183 #[test]
3184 fn evaluate_checks_range_nan_fails_with_nan_message() {
3185 let pm = PayloadMetrics {
3186 payload_index: 0,
3187 metrics: vec![Metric {
3188 name: "cpu".to_string(),
3189 value: f64::NAN,
3190 polarity: Polarity::Unknown,
3191 unit: String::new(),
3192 stream: MetricStream::Stdout,
3193 }],
3194 exit_code: 0,
3195 };
3196 let r = evaluate_checks(&[MetricCheck::range("cpu", 0.0, 100.0)], &pm, "");
3197 assert!(!r.is_pass(), "NaN value must fail Range check");
3198 assert!(
3199 r.failure_details()
3200 .next()
3201 .unwrap()
3202 .message
3203 .contains("value is NaN"),
3204 "NaN failure must surface the dedicated message: {:?}",
3205 r.outcomes
3206 );
3207 }
3208
3209 #[test]
3210 fn evaluate_checks_exists_missing_fails() {
3211 let pm = PayloadMetrics {
3212 payload_index: 0,
3213 metrics: vec![],
3214 exit_code: 0,
3215 };
3216 let r = evaluate_checks(&[MetricCheck::exists("thing")], &pm, "");
3217 assert!(r.is_fail());
3218 }
3219
3220 #[test]
3221 fn evaluate_checks_all_pass_returns_pass() {
3222 let pm = PayloadMetrics {
3223 payload_index: 0,
3224 metrics: vec![Metric {
3225 name: "iops".to_string(),
3226 value: 5000.0,
3227 polarity: Polarity::HigherBetter,
3228 unit: String::new(),
3229 stream: MetricStream::Stdout,
3230 }],
3231 exit_code: 0,
3232 };
3233 let r = evaluate_checks(
3234 &[
3235 MetricCheck::exit_code_eq(0),
3236 MetricCheck::min("iops", 1000.0),
3237 MetricCheck::exists("iops"),
3238 ],
3239 &pm,
3240 "",
3241 );
3242 assert!(r.is_pass());
3243 }
3244
3245 /// Multiple checks on the same metric all fire — the evaluator
3246 /// does not dedup by metric name. Two `Min`s on the same path
3247 /// either both pass (value >= max threshold) or both fail
3248 /// (value < one of the thresholds, depending on which is more
3249 /// restrictive). This test uses a pair where the metric value
3250 /// (100) is below the second threshold (200) but above the
3251 /// first (50). The second failure must appear in the details
3252 /// list — the evaluator must not short-circuit after the first
3253 /// matching metric check.
3254 #[test]
3255 fn evaluate_checks_duplicate_min_on_same_metric_both_evaluated() {
3256 let pm = PayloadMetrics {
3257 payload_index: 0,
3258 metrics: vec![Metric {
3259 name: "iops".to_string(),
3260 value: 100.0,
3261 polarity: Polarity::HigherBetter,
3262 unit: String::new(),
3263 stream: MetricStream::Stdout,
3264 }],
3265 exit_code: 0,
3266 };
3267 let r = evaluate_checks(
3268 &[
3269 MetricCheck::min("iops", 50.0),
3270 MetricCheck::min("iops", 200.0),
3271 ],
3272 &pm,
3273 "",
3274 );
3275 assert!(!r.is_pass(), "second min must fail");
3276 assert_eq!(r.outcomes.len(), 1, "only the failing check emits a detail");
3277 // The passing check produces no detail; only the failing one
3278 // shows up. The message must reference the 200 threshold.
3279 assert!(
3280 r.failure_details()
3281 .next()
3282 .unwrap()
3283 .message
3284 .contains("below minimum 200"),
3285 "failing check must cite its threshold: {:?}",
3286 r.outcomes,
3287 );
3288 }
3289
3290 /// Two conflicting checks on the same metric (Min 100 and Max 50)
3291 /// produce TWO failures in the details list — not one collapsed
3292 /// failure. Pins the "each check evaluated independently"
3293 /// invariant so a future optimization doesn't accidentally merge
3294 /// / dedup.
3295 #[test]
3296 fn evaluate_checks_conflicting_checks_on_same_metric_both_report() {
3297 let pm = PayloadMetrics {
3298 payload_index: 0,
3299 metrics: vec![Metric {
3300 name: "iops".to_string(),
3301 value: 75.0,
3302 polarity: Polarity::HigherBetter,
3303 unit: String::new(),
3304 stream: MetricStream::Stdout,
3305 }],
3306 exit_code: 0,
3307 };
3308 let r = evaluate_checks(
3309 &[
3310 MetricCheck::min("iops", 100.0), // 75 < 100: fail
3311 MetricCheck::max("iops", 50.0), // 75 > 50: fail
3312 ],
3313 &pm,
3314 "",
3315 );
3316 assert!(r.is_fail());
3317 assert_eq!(
3318 r.outcomes.len(),
3319 2,
3320 "both conflicting checks must each emit a detail: {:?}",
3321 r.outcomes,
3322 );
3323 }
3324
3325 /// `MetricCheck::Exists` with a zero-value metric passes. The check is
3326 /// presence-only — a metric of 0.0 is still present in the
3327 /// PayloadMetrics map and `pm.get(name).is_some()` returns true.
3328 /// A naive `pm.get(name).filter(|v| *v != 0.0)` would spuriously
3329 /// fail here; pin the "exists is sign-agnostic and zero-
3330 /// friendly" invariant.
3331 #[test]
3332 fn evaluate_checks_exists_passes_for_zero_value_metric() {
3333 let pm = PayloadMetrics {
3334 payload_index: 0,
3335 metrics: vec![Metric {
3336 name: "errors".to_string(),
3337 value: 0.0,
3338 polarity: Polarity::LowerBetter,
3339 unit: String::new(),
3340 stream: MetricStream::Stdout,
3341 }],
3342 exit_code: 0,
3343 };
3344 let r = evaluate_checks(&[MetricCheck::exists("errors")], &pm, "");
3345 assert!(
3346 r.is_pass(),
3347 "exists('errors') must pass when metric is 0.0: {:?}",
3348 r.outcomes,
3349 );
3350 }
3351
3352 /// Negative zero (`-0.0`) also counts as present for
3353 /// `MetricCheck::Exists`. Paranoid pin because f64 `-0.0` surprises
3354 /// some pattern-matching code (`0.0 == -0.0` but they differ
3355 /// under `f64::to_bits`).
3356 #[test]
3357 fn evaluate_checks_exists_passes_for_negative_zero() {
3358 let pm = PayloadMetrics {
3359 payload_index: 0,
3360 metrics: vec![Metric {
3361 name: "drift".to_string(),
3362 value: -0.0,
3363 polarity: Polarity::Unknown,
3364 unit: String::new(),
3365 stream: MetricStream::Stdout,
3366 }],
3367 exit_code: 0,
3368 };
3369 let r = evaluate_checks(&[MetricCheck::exists("drift")], &pm, "");
3370 assert!(r.is_pass());
3371 }
3372
3373 /// `PayloadRun`'s custom `Debug` impl renders the stable
3374 /// identity fields — payload name, args/checks lengths, and
3375 /// cgroup placement — without dumping the `Ctx` pointer. Pins
3376 /// the output shape so a future rename can't silently drop a
3377 /// field that debug-printing consumers rely on.
3378 #[test]
3379 fn payload_run_debug_renders_identity_fields() {
3380 with_ctx("/nonexistent", |ctx| {
3381 let run = PayloadRun::new(ctx, &TRUE_BIN)
3382 .arg("--foo")
3383 .arg("--bar")
3384 .check(MetricCheck::exit_code_eq(0))
3385 .in_cgroup("workers");
3386 let s = format!("{run:?}");
3387 assert!(s.contains("PayloadRun"), "prefix: {s}");
3388 assert!(s.contains("payload:"), "payload field: {s}");
3389 assert!(s.contains("true_bin"), "payload name: {s}");
3390 assert!(s.contains("args_len"), "args_len field: {s}");
3391 assert!(s.contains("checks_len"), "checks_len field: {s}");
3392 assert!(s.contains("cgroup:"), "cgroup field: {s}");
3393 // Values: 2 args added (on top of 0 default) + 1 check.
3394 assert!(s.contains("args_len: 2"), "computed args_len: {s}");
3395 assert!(s.contains("checks_len: 1"), "computed checks_len: {s}");
3396 // cgroup is Some("workers"); the debug form of Cow<str>
3397 // renders as "workers" inside Some(..).
3398 assert!(s.contains("workers"), "cgroup value: {s}");
3399 // Must NOT leak the Ctx pointer (no raw-address tokens).
3400 assert!(
3401 !s.contains("Ctx {"),
3402 "Ctx should not appear in PayloadRun Debug: {s}"
3403 );
3404 });
3405 }
3406
3407 /// Default `PayloadRun` (no args, no checks, no cgroup)
3408 /// renders sensible zeroes.
3409 #[test]
3410 fn payload_run_debug_renders_defaults() {
3411 with_ctx("/nonexistent", |ctx| {
3412 let run = PayloadRun::new(ctx, &TRUE_BIN);
3413 let s = format!("{run:?}");
3414 assert!(s.contains("args_len: 0"), "default args_len: {s}");
3415 assert!(s.contains("checks_len: 0"), "default checks_len: {s}");
3416 assert!(s.contains("cgroup: None"), "default cgroup: {s}");
3417 });
3418 }
3419
3420 #[test]
3421 fn resolve_polarities_applies_hints() {
3422 let mut metrics = vec![Metric {
3423 name: "iops".to_string(),
3424 value: 100.0,
3425 polarity: Polarity::Unknown,
3426 unit: String::new(),
3427 stream: MetricStream::Stdout,
3428 }];
3429 const HINTED: Payload = Payload {
3430 name: "p",
3431 kind: PayloadKind::Binary("p"),
3432 output: OutputFormat::Json,
3433 default_args: &[],
3434 default_checks: &[],
3435 metrics: &[crate::test_support::MetricHint {
3436 name: "iops",
3437 polarity: Polarity::HigherBetter,
3438 unit: "iops",
3439 }],
3440 include_files: &[],
3441 uses_parent_pgrp: false,
3442 known_flags: None,
3443 };
3444 resolve_polarities(&mut metrics, &HINTED);
3445 assert_eq!(metrics[0].polarity, Polarity::HigherBetter);
3446 assert_eq!(metrics[0].unit, "iops");
3447 }
3448
3449 // -- PayloadHandle + .spawn() tests --
3450
3451 const TRUE_BIN: Payload = Payload::binary("true_bin", "/bin/true");
3452 const FALSE_BIN: Payload = Payload::binary("false_bin", "/bin/false");
3453
3454 #[test]
3455 fn spawn_rejects_scheduler_kind() {
3456 with_ctx("/nonexistent", |ctx| {
3457 let run = PayloadRun::new(ctx, &EEVDF_SCHED_PAYLOAD);
3458 let err = run.spawn().unwrap_err();
3459 assert!(
3460 format!("{err:#}").contains("scheduler-kind"),
3461 "err: {err:#}"
3462 );
3463 });
3464 }
3465
3466 #[test]
3467 fn spawn_then_wait_returns_result_and_metrics() {
3468 with_ctx("/nonexistent", |ctx| {
3469 let handle = PayloadRun::new(ctx, &TRUE_BIN)
3470 .spawn()
3471 .expect("spawn /bin/true");
3472 let (result, metrics) = handle.wait().expect("wait");
3473 assert!(result.is_pass());
3474 assert_eq!(metrics.exit_code, 0);
3475 });
3476 }
3477
3478 #[test]
3479 fn spawn_then_kill_returns_collected_output() {
3480 with_ctx("/nonexistent", |ctx| {
3481 // /bin/sleep runs for a while; .kill() terminates it.
3482 const SLEEPER: Payload = Payload {
3483 name: "sleeper",
3484 kind: PayloadKind::Binary("/bin/sleep"),
3485 output: crate::test_support::OutputFormat::ExitCode,
3486 default_args: &["60"],
3487 default_checks: &[],
3488 metrics: &[],
3489 include_files: &[],
3490 uses_parent_pgrp: false,
3491 known_flags: None,
3492 };
3493 let handle = PayloadRun::new(ctx, &SLEEPER).spawn().expect("spawn sleep");
3494 let (_result, metrics) = handle.kill().expect("kill+collect");
3495 // Killed process produces a non-zero exit (SIGKILL -> None
3496 // status code, wait_and_capture maps to -1).
3497 assert_ne!(metrics.exit_code, 0);
3498 });
3499 }
3500
3501 #[test]
3502 fn spawn_try_wait_returns_none_while_running() {
3503 with_ctx("/nonexistent", |ctx| {
3504 const SLEEPER: Payload = Payload {
3505 name: "sleeper3",
3506 kind: PayloadKind::Binary("/bin/sleep"),
3507 output: crate::test_support::OutputFormat::ExitCode,
3508 default_args: &["60"],
3509 default_checks: &[],
3510 metrics: &[],
3511 include_files: &[],
3512 uses_parent_pgrp: false,
3513 known_flags: None,
3514 };
3515 let mut handle = PayloadRun::new(ctx, &SLEEPER).spawn().expect("spawn sleep");
3516 // Not yet exited.
3517 assert!(handle.try_wait().expect("try_wait").is_none());
3518 // Cleanup — kill so Drop warning doesn't fire.
3519 let _ = handle.kill();
3520 });
3521 }
3522
3523 #[test]
3524 fn spawn_try_wait_returns_some_after_exit() {
3525 with_ctx("/nonexistent", |ctx| {
3526 let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
3527 .spawn()
3528 .expect("spawn /bin/true");
3529 // /bin/true exits quickly. Poll a few times.
3530 let mut result = None;
3531 for _ in 0..100 {
3532 if let Some(r) = handle.try_wait().expect("try_wait") {
3533 result = Some(r);
3534 break;
3535 }
3536 std::thread::sleep(std::time::Duration::from_millis(10));
3537 }
3538 let (r, metrics) = result.expect("try_wait eventually returns Some");
3539 assert!(r.is_pass());
3540 assert_eq!(metrics.exit_code, 0);
3541 });
3542 }
3543
3544 #[test]
3545 fn spawn_false_binary_produces_failing_exit_code() {
3546 with_ctx("/nonexistent", |ctx| {
3547 let handle = PayloadRun::new(ctx, &FALSE_BIN)
3548 .spawn()
3549 .expect("spawn /bin/false");
3550 let (_result, metrics) = handle.wait().expect("wait");
3551 assert_ne!(metrics.exit_code, 0);
3552 });
3553 }
3554
3555 #[test]
3556 fn resolve_polarities_leaves_unhinted_alone() {
3557 let mut metrics = vec![Metric {
3558 name: "no_hint".to_string(),
3559 value: 1.0,
3560 polarity: Polarity::Unknown,
3561 unit: String::new(),
3562 stream: MetricStream::Stdout,
3563 }];
3564 resolve_polarities(&mut metrics, &FIO_BINARY);
3565 assert_eq!(metrics[0].polarity, Polarity::Unknown);
3566 assert_eq!(metrics[0].unit, "");
3567 }
3568
3569 // -- Builder-composition + evaluator-coverage regression tests --
3570
3571 #[test]
3572 fn evaluate_checks_three_failing_checks_produce_three_details() {
3573 // Exit-code check passes (0 == 0), so pre-pass does not
3574 // short-circuit; all three metric checks fail and each must
3575 // contribute its own AssertDetail — regression guard
3576 // against detail dedup/overwrite bugs.
3577 let pm = PayloadMetrics {
3578 payload_index: 0,
3579 metrics: vec![
3580 Metric {
3581 name: "iops".to_string(),
3582 value: 10.0,
3583 polarity: Polarity::HigherBetter,
3584 unit: String::new(),
3585 stream: MetricStream::Stdout,
3586 },
3587 Metric {
3588 name: "lat".to_string(),
3589 value: 900.0,
3590 polarity: Polarity::LowerBetter,
3591 unit: String::new(),
3592 stream: MetricStream::Stdout,
3593 },
3594 Metric {
3595 name: "cpu".to_string(),
3596 value: 200.0,
3597 polarity: Polarity::Unknown,
3598 unit: String::new(),
3599 stream: MetricStream::Stdout,
3600 },
3601 ],
3602 exit_code: 0,
3603 };
3604 let checks = [
3605 MetricCheck::exit_code_eq(0),
3606 MetricCheck::min("iops", 1000.0),
3607 MetricCheck::max("lat", 100.0),
3608 MetricCheck::range("cpu", 0.0, 100.0),
3609 ];
3610 let r = evaluate_checks(&checks, &pm, "");
3611 assert!(r.is_fail());
3612 assert_eq!(
3613 r.outcomes.len(),
3614 3,
3615 "expected one detail per failed metric check, got: {:?}",
3616 r.outcomes,
3617 );
3618 // Each check's message must surface — not an aggregate or
3619 // a deduped first-only line.
3620 assert!(r.failure_details().any(|d| d.message.contains("iops")));
3621 assert!(r.failure_details().any(|d| d.message.contains("lat")));
3622 assert!(r.failure_details().any(|d| d.message.contains("cpu")));
3623 }
3624
3625 #[test]
3626 fn arg_then_clear_args_then_arg_yields_only_the_final_arg() {
3627 // clear_args() wipes EVERYTHING — the default_args AND any
3628 // previously-appended .arg(...) — and subsequent .arg(...)
3629 // calls start from empty. Regression guard for the
3630 // "clear_args truncates, arg appends" contract.
3631 with_ctx("/nonexistent", |ctx| {
3632 let run = PayloadRun::new(ctx, &FIO_BINARY)
3633 .arg("--x")
3634 .clear_args()
3635 .arg("--y");
3636 assert_eq!(run.args, vec!["--y"]);
3637 });
3638 }
3639
3640 #[test]
3641 fn default_checks_are_inherited_by_new_builder() {
3642 // Payload.default_checks are the starting check list: they
3643 // MUST be present on a fresh PayloadRun before any runtime
3644 // .check() calls. `.check` appends on top, `.clear_checks`
3645 // wipes them.
3646 const CHECKED: Payload = Payload {
3647 name: "checked",
3648 kind: PayloadKind::Binary("checked"),
3649 output: OutputFormat::ExitCode,
3650 default_args: &[],
3651 default_checks: &[
3652 MetricCheck::exit_code_eq(0),
3653 MetricCheck::min("iops", 500.0),
3654 ],
3655 metrics: &[],
3656 include_files: &[],
3657 uses_parent_pgrp: false,
3658 known_flags: None,
3659 };
3660 with_ctx("/nonexistent", |ctx| {
3661 // Fresh builder inherits both default checks in order.
3662 let fresh = PayloadRun::new(ctx, &CHECKED);
3663 assert_eq!(fresh.checks.len(), 2);
3664 assert!(matches!(fresh.checks[0], MetricCheck::ExitCodeEq(0)));
3665 assert!(matches!(
3666 fresh.checks[1],
3667 MetricCheck::Min { value, .. } if value == 500.0,
3668 ));
3669
3670 // Appending preserves defaults and adds on top.
3671 let appended = PayloadRun::new(ctx, &CHECKED).check(MetricCheck::exists("latency"));
3672 assert_eq!(appended.checks.len(), 3);
3673
3674 // Clearing wipes defaults too.
3675 let cleared = PayloadRun::new(ctx, &CHECKED).clear_checks();
3676 assert!(cleared.checks.is_empty());
3677 });
3678 }
3679
3680 #[test]
3681 fn in_cgroup_accepts_static_str_zero_alloc() {
3682 // Static &'static str goes in as Cow::Borrowed; no heap
3683 // allocation happens for the common case of a const cgroup
3684 // name. Regression guard for the Cow<'static, str> API shape.
3685 with_ctx("/nonexistent", |ctx| {
3686 let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup("workload");
3687 match &run.cgroup {
3688 Some(Cow::Borrowed(s)) => assert_eq!(*s, "workload"),
3689 other => panic!("expected Cow::Borrowed for &'static str input, got {other:?}"),
3690 }
3691 });
3692 }
3693
3694 #[test]
3695 fn in_cgroup_accepts_owned_string() {
3696 // Owned String goes in as Cow::Owned; the builder must not
3697 // require the caller to convert themselves.
3698 with_ctx("/nonexistent", |ctx| {
3699 let name = String::from("dynamic");
3700 let run = PayloadRun::new(ctx, &FIO_BINARY).in_cgroup(name);
3701 match &run.cgroup {
3702 Some(Cow::Owned(s)) => assert_eq!(s, "dynamic"),
3703 other => panic!("expected Cow::Owned for String input, got {other:?}"),
3704 }
3705 });
3706 }
3707
3708 /// Host-side decode of a guest-emitted [`crate::test_support::PayloadMetrics`] JSON
3709 /// body must round-trip exactly — the SHM transport only carries
3710 /// bytes, and a schema drift between emit-side (serde_json on a
3711 /// `PayloadMetrics`) and drain-side (serde_json::from_slice) would
3712 /// silently drop metrics from the sidecar.
3713 #[test]
3714 fn payload_metrics_shm_payload_json_round_trip() {
3715 let emit = PayloadMetrics {
3716 payload_index: 0,
3717 metrics: vec![
3718 Metric {
3719 name: "jobs.0.read.iops".to_string(),
3720 value: 12345.0,
3721 polarity: Polarity::HigherBetter,
3722 unit: "iops".to_string(),
3723 stream: MetricStream::Stdout,
3724 },
3725 Metric {
3726 name: "lat_ns".to_string(),
3727 value: 500.0,
3728 polarity: Polarity::LowerBetter,
3729 unit: "ns".to_string(),
3730 stream: MetricStream::Stdout,
3731 },
3732 ],
3733 exit_code: 0,
3734 };
3735 let bytes = serde_json::to_vec(&emit).expect("serialize PayloadMetrics");
3736 let decoded: PayloadMetrics =
3737 serde_json::from_slice(&bytes).expect("decode PayloadMetrics from JSON bytes");
3738 assert_eq!(decoded.exit_code, emit.exit_code);
3739 assert_eq!(decoded.metrics.len(), emit.metrics.len());
3740 for (a, b) in decoded.metrics.iter().zip(emit.metrics.iter()) {
3741 assert_eq!(a.name, b.name);
3742 assert_eq!(a.value, b.value);
3743 assert_eq!(a.polarity, b.polarity);
3744 assert_eq!(a.unit, b.unit);
3745 }
3746 }
3747
3748 /// Hinted metrics pick up polarity + unit from the payload's
3749 /// declared MetricHints regardless of declaration order. Also
3750 /// pins that resolve_polarities leaves unhinted metrics at
3751 /// Polarity::Unknown / empty unit — the non-over-applying
3752 /// invariant the prior linear scan had.
3753 #[test]
3754 fn resolve_polarities_applies_hints_by_name_lookup() {
3755 use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3756 static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3757 name: "hinted",
3758 kind: crate::test_support::PayloadKind::Binary("x"),
3759 output: crate::test_support::OutputFormat::Json,
3760 default_args: &[],
3761 default_checks: &[],
3762 // Out-of-order with the metric slice below so a naive
3763 // position-based lookup would miss.
3764 metrics: &[
3765 MetricHint {
3766 name: "lat_ns",
3767 polarity: Polarity::LowerBetter,
3768 unit: "ns",
3769 },
3770 MetricHint {
3771 name: "iops",
3772 polarity: Polarity::HigherBetter,
3773 unit: "iops",
3774 },
3775 ],
3776 include_files: &[],
3777 uses_parent_pgrp: false,
3778 known_flags: None,
3779 };
3780 let mut ms = vec![
3781 Metric {
3782 name: "iops".into(),
3783 value: 1.0,
3784 polarity: Polarity::Unknown,
3785 unit: String::new(),
3786 stream: MetricStream::Stdout,
3787 },
3788 Metric {
3789 name: "unhinted".into(),
3790 value: 2.0,
3791 polarity: Polarity::Unknown,
3792 unit: String::new(),
3793 stream: MetricStream::Stdout,
3794 },
3795 Metric {
3796 name: "lat_ns".into(),
3797 value: 3.0,
3798 polarity: Polarity::Unknown,
3799 unit: String::new(),
3800 stream: MetricStream::Stdout,
3801 },
3802 ];
3803 resolve_polarities(&mut ms, &PAYLOAD);
3804 // iops hinted → HigherBetter / "iops".
3805 assert_eq!(ms[0].polarity, Polarity::HigherBetter);
3806 assert_eq!(ms[0].unit, "iops");
3807 // unhinted stays Unknown + empty.
3808 assert_eq!(ms[1].polarity, Polarity::Unknown);
3809 assert_eq!(ms[1].unit, "");
3810 // lat_ns hinted → LowerBetter / "ns".
3811 assert_eq!(ms[2].polarity, Polarity::LowerBetter);
3812 assert_eq!(ms[2].unit, "ns");
3813 }
3814
3815 /// Empty hints or empty metrics are a fast-path — the HashMap
3816 /// build is skipped entirely. Pins the no-op invariant so a
3817 /// regression can't accidentally materialize an empty map for
3818 /// zero metrics on every hot-path call.
3819 /// When the payload declares two MetricHints with the same
3820 /// name, the HashMap build keeps the LAST insertion. The test
3821 /// pins that behavior so a future switch to a multimap or to
3822 /// first-wins semantics surfaces here. First-wins would be
3823 /// surprising: users who copy-paste a hint to tweak it expect
3824 /// the new value.
3825 #[test]
3826 fn resolve_polarities_duplicate_hint_names_last_wins() {
3827 use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3828 static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3829 name: "dup_hints",
3830 kind: crate::test_support::PayloadKind::Binary("x"),
3831 output: crate::test_support::OutputFormat::Json,
3832 default_args: &[],
3833 default_checks: &[],
3834 metrics: &[
3835 MetricHint {
3836 name: "iops",
3837 polarity: Polarity::HigherBetter,
3838 unit: "iops",
3839 },
3840 MetricHint {
3841 name: "iops",
3842 polarity: Polarity::LowerBetter,
3843 unit: "overridden",
3844 },
3845 ],
3846 include_files: &[],
3847 uses_parent_pgrp: false,
3848 known_flags: None,
3849 };
3850 let mut ms = vec![Metric {
3851 name: "iops".into(),
3852 value: 1.0,
3853 polarity: Polarity::Unknown,
3854 unit: String::new(),
3855 stream: MetricStream::Stdout,
3856 }];
3857 resolve_polarities(&mut ms, &PAYLOAD);
3858 // Second declaration wins (HashMap last-insertion semantics).
3859 assert_eq!(ms[0].polarity, Polarity::LowerBetter);
3860 assert_eq!(ms[0].unit, "overridden");
3861 }
3862
3863 /// When the metric slice has duplicate names (e.g. a payload
3864 /// emitting the same dotted path twice in one run), the hint
3865 /// is applied to each occurrence. Each is a distinct Metric
3866 /// value in the sidecar; both must carry the hinted polarity +
3867 /// unit so downstream regression reports are consistent.
3868 #[test]
3869 fn resolve_polarities_duplicate_metric_names_each_gets_hint() {
3870 use crate::test_support::{Metric, MetricHint, MetricStream, Polarity};
3871 static PAYLOAD: crate::test_support::Payload = crate::test_support::Payload {
3872 name: "dup_metrics",
3873 kind: crate::test_support::PayloadKind::Binary("x"),
3874 output: crate::test_support::OutputFormat::Json,
3875 default_args: &[],
3876 default_checks: &[],
3877 metrics: &[MetricHint {
3878 name: "iops",
3879 polarity: Polarity::HigherBetter,
3880 unit: "iops",
3881 }],
3882 include_files: &[],
3883 uses_parent_pgrp: false,
3884 known_flags: None,
3885 };
3886 let mut ms = vec![
3887 Metric {
3888 name: "iops".into(),
3889 value: 1.0,
3890 polarity: Polarity::Unknown,
3891 unit: String::new(),
3892 stream: MetricStream::Stdout,
3893 },
3894 Metric {
3895 name: "iops".into(),
3896 value: 2.0,
3897 polarity: Polarity::Unknown,
3898 unit: String::new(),
3899 stream: MetricStream::Stdout,
3900 },
3901 ];
3902 resolve_polarities(&mut ms, &PAYLOAD);
3903 for m in &ms {
3904 assert_eq!(m.polarity, Polarity::HigherBetter);
3905 assert_eq!(m.unit, "iops");
3906 }
3907 }
3908
3909 #[test]
3910 fn resolve_polarities_empty_inputs_are_noop() {
3911 use crate::test_support::{Metric, MetricStream, Polarity};
3912 static NO_HINTS: crate::test_support::Payload = crate::test_support::Payload {
3913 name: "no_hints",
3914 kind: crate::test_support::PayloadKind::Binary("x"),
3915 output: crate::test_support::OutputFormat::Json,
3916 default_args: &[],
3917 default_checks: &[],
3918 metrics: &[],
3919 include_files: &[],
3920 uses_parent_pgrp: false,
3921 known_flags: None,
3922 };
3923 let mut ms = vec![Metric {
3924 name: "anything".into(),
3925 value: 1.0,
3926 polarity: Polarity::Unknown,
3927 unit: String::new(),
3928 stream: MetricStream::Stdout,
3929 }];
3930 resolve_polarities(&mut ms, &NO_HINTS);
3931 assert_eq!(ms[0].polarity, Polarity::Unknown);
3932 assert_eq!(ms[0].unit, "");
3933
3934 // Empty metrics list — also a fast-path no-op, just pin it
3935 // doesn't panic / over-allocate.
3936 let mut empty: Vec<Metric> = vec![];
3937 resolve_polarities(&mut empty, &NO_HINTS);
3938 assert!(empty.is_empty());
3939 }
3940
3941 /// In host (test) context the bulk port is not open and
3942 /// `is_guest()` is false, so the emit must NOT write — it returns
3943 /// `false` via the `write_msg` -> `assert_guest_context`
3944 /// early-return. Asserting the `false` return pins the
3945 /// observable no-op (no frame written) rather than merely that
3946 /// the call did not panic.
3947 #[test]
3948 fn emit_payload_metrics_returns_false_in_host_context() {
3949 let pm = PayloadMetrics {
3950 payload_index: 0,
3951 metrics: Vec::new(),
3952 exit_code: 0,
3953 };
3954 assert!(
3955 !emit_payload_metrics(&pm),
3956 "host-context emit must report no write (false) — the \
3957 bulk port is closed and assert_guest_context bails"
3958 );
3959 }
3960
3961 // -- PayloadHandle double-consume returns Err, not panic --
3962
3963 /// After `try_wait()` returns `Ok(Some(..))` (terminal branch
3964 /// that takes the child), a subsequent `try_wait()` on the same
3965 /// handle must return `Err` instead of panicking. Previously
3966 /// the implementation unwrapped `self.child.as_mut()` with a
3967 /// panicking `.expect(...)`.
3968 #[test]
3969 fn try_wait_after_terminal_returns_err() {
3970 with_ctx("/nonexistent", |ctx| {
3971 let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
3972 .spawn()
3973 .expect("spawn /bin/true");
3974 // First terminal: /bin/true exits immediately; spin until
3975 // try_wait returns Some.
3976 for _ in 0..100 {
3977 if handle.try_wait().expect("try_wait").is_some() {
3978 break;
3979 }
3980 std::thread::sleep(std::time::Duration::from_millis(10));
3981 }
3982 // Second call must not panic — expect Err describing the
3983 // consumed state.
3984 let err = handle
3985 .try_wait()
3986 .expect_err("second try_wait on consumed handle must be Err");
3987 let msg = format!("{err:#}");
3988 assert!(
3989 msg.contains("already consumed") && msg.contains("true_bin"),
3990 "error must name the handle + misuse, got: {msg}"
3991 );
3992 });
3993 }
3994
3995 /// Calling `wait()` after `try_wait()` has consumed the child
3996 /// must Err rather than panic. Test pairs with
3997 /// `try_wait_after_terminal_returns_err`: same state, different
3998 /// terminal method.
3999 #[test]
4000 fn wait_after_try_wait_consumed_returns_err() {
4001 with_ctx("/nonexistent", |ctx| {
4002 let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
4003 .spawn()
4004 .expect("spawn /bin/true");
4005 for _ in 0..100 {
4006 if handle.try_wait().expect("try_wait").is_some() {
4007 break;
4008 }
4009 std::thread::sleep(std::time::Duration::from_millis(10));
4010 }
4011 // Child is now taken; wait() must return Err, not panic.
4012 let err = handle
4013 .wait()
4014 .expect_err("wait() on consumed handle must return Err");
4015 let msg = format!("{err:#}");
4016 assert!(
4017 msg.contains("already consumed") && msg.contains("true_bin"),
4018 "error must name the handle + misuse, got: {msg}"
4019 );
4020 });
4021 }
4022
4023 /// Calling `kill()` after `try_wait()` has consumed the child
4024 /// must Err rather than panic.
4025 #[test]
4026 fn kill_after_try_wait_consumed_returns_err() {
4027 with_ctx("/nonexistent", |ctx| {
4028 let mut handle = PayloadRun::new(ctx, &TRUE_BIN)
4029 .spawn()
4030 .expect("spawn /bin/true");
4031 for _ in 0..100 {
4032 if handle.try_wait().expect("try_wait").is_some() {
4033 break;
4034 }
4035 std::thread::sleep(std::time::Duration::from_millis(10));
4036 }
4037 let err = handle
4038 .kill()
4039 .expect_err("kill() on consumed handle must return Err");
4040 let msg = format!("{err:#}");
4041 assert!(
4042 msg.contains("already consumed") && msg.contains("true_bin"),
4043 "error must name the handle + misuse, got: {msg}"
4044 );
4045 });
4046 }
4047
4048 // -- stdout-primary / stderr-fallback evaluation --
4049
4050 const JSON_PAYLOAD: Payload = Payload {
4051 name: "json_payload",
4052 kind: PayloadKind::Binary("json_payload"),
4053 output: OutputFormat::Json,
4054 default_args: &[],
4055 default_checks: &[],
4056 metrics: &[],
4057 include_files: &[],
4058 uses_parent_pgrp: false,
4059 known_flags: None,
4060 };
4061
4062 /// Well-behaved case: stdout carries the JSON document; stderr
4063 /// carries banner noise the extractor must NOT see. Merging the
4064 /// streams would pull the banner into the metric blob; the
4065 /// fallback contract keeps stdout canonical.
4066 #[test]
4067 fn evaluate_prefers_stdout_when_stdout_yields_metrics() {
4068 let output = SpawnOutput {
4069 stdout: r#"{"iops": 500}"#.to_string(),
4070 stderr: "unrelated banner: open fd error (ignore)".to_string(),
4071 exit_code: 0,
4072 };
4073 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4074 assert_eq!(pm.metrics.len(), 1, "stdout JSON must win");
4075 assert_eq!(pm.metrics[0].name, "iops");
4076 assert_eq!(pm.metrics[0].value, 500.0);
4077 }
4078
4079 /// schbench-style: the payload emits JSON percentiles on stderr,
4080 /// leaves stdout empty. Stdout-primary extraction returns an
4081 /// empty Vec, then the stderr fallback runs and produces the
4082 /// real metrics.
4083 #[test]
4084 fn evaluate_falls_back_to_stderr_when_stdout_empty() {
4085 let output = SpawnOutput {
4086 stdout: String::new(),
4087 stderr: r#"{"latency_ns": 1234}"#.to_string(),
4088 exit_code: 0,
4089 };
4090 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4091 assert_eq!(pm.metrics.len(), 1, "stderr fallback must fire");
4092 assert_eq!(pm.metrics[0].name, "latency_ns");
4093 assert_eq!(pm.metrics[0].value, 1234.0);
4094 }
4095
4096 /// End-to-end stream-attribution pin for the stderr-fallback
4097 /// branch. When stdout carries no extractable metrics and the
4098 /// fallback pulls the real document from stderr, every emitted
4099 /// metric's `stream` field must tag `MetricStream::Stderr` —
4100 /// NOT `Stdout`. The attribution is what lets downstream review
4101 /// tools filter stderr-sourced metrics (well-behaved payloads
4102 /// keep stdout canonical; an all-stderr metric set is a review
4103 /// hint that the payload may be violating the channel
4104 /// convention). A regression that stamped `Stdout` on every
4105 /// Metric regardless of which stream it came from would silence that review
4106 /// signal without changing the metric values themselves — this
4107 /// test pins the attribution end-to-end so the regression
4108 /// cannot slip past the existing value-only asserts on the
4109 /// sibling fallback tests.
4110 ///
4111 /// Pairs three fallback shapes in one test: empty stdout, prose
4112 /// stdout, and valid-JSON-no-numeric-leaves stdout. The three
4113 /// share one fallback decision (`metrics.is_empty()` after
4114 /// stdout attempt), so their attribution invariant is identical;
4115 /// one test exercises all three to close the fallback-shape
4116 /// coverage gap for the stream field specifically.
4117 /// Positive control for the stream-attribution pin: when
4118 /// stdout carries valid JSON that extracts cleanly, every
4119 /// emitted metric's `stream` must tag `MetricStream::Stdout`
4120 /// — NOT `Stderr`. The sibling
4121 /// `stderr_fallback_tags_metrics_with_metric_stream_stderr`
4122 /// covers the fallback (negative) side; this test closes the
4123 /// symmetry gap. A regression that unconditionally stamped
4124 /// `Stderr` on every Metric (or swapped the two
4125 /// unconditionally) would trip the fallback test's value-
4126 /// agnostic `== Stderr` assertion OR this test's inverse
4127 /// `== Stdout` assertion — at least one of the two paths
4128 /// has to change its stream tag direction to hide the bug.
4129 ///
4130 /// Exercises the happy path with both a minimal JSON object
4131 /// and a multi-key JSON object, proving the attribution is
4132 /// per-metric rather than per-document. A regression that
4133 /// attributed based on document-level shape (e.g. "stream =
4134 /// Stderr if multi-key") would fail on the second fixture.
4135 #[test]
4136 fn stdout_primary_tags_metrics_with_metric_stream_stdout() {
4137 use crate::test_support::MetricStream;
4138
4139 for (label, stdout) in [
4140 ("single-key", r#"{"iops": 4242}"#.to_string()),
4141 (
4142 "multi-key",
4143 r#"{"iops": 1000, "latency_us": 42, "runs": 3}"#.to_string(),
4144 ),
4145 ] {
4146 let output = SpawnOutput {
4147 stdout,
4148 // stderr carries a distinct value so a regression
4149 // that merged the streams (or used stderr despite
4150 // stdout winning) would surface a wrong-valued
4151 // metric here alongside the wrong stream tag.
4152 stderr: r#"{"iops": 9999999}"#.to_string(),
4153 exit_code: 0,
4154 };
4155 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4156 assert!(
4157 !pm.metrics.is_empty(),
4158 "[{label}] stdout-primary must produce metrics",
4159 );
4160 for m in &pm.metrics {
4161 assert_eq!(
4162 m.stream,
4163 MetricStream::Stdout,
4164 "[{label}] stdout-extracted metric `{name}` must \
4165 carry MetricStream::Stdout; got stream={stream:?}. \
4166 A regression that mis-tagged stdout-sourced \
4167 metrics as Stderr (or merged the streams) would \
4168 trip here — the stderr-fallback sibling test \
4169 covers the inverse direction.",
4170 name = m.name,
4171 stream = m.stream,
4172 );
4173 }
4174 // Stream-independence: the `iops` value MUST come from
4175 // stdout (4242 / 1000), not stderr (9999999). A
4176 // regression that pulled from the wrong stream would
4177 // both mis-tag AND mis-value, but the value check is
4178 // the ground-truth that the stream tag then describes.
4179 let iops = pm
4180 .metrics
4181 .iter()
4182 .find(|m| m.name == "iops")
4183 .expect("iops metric must be present");
4184 assert!(
4185 iops.value < 9_000_000.0,
4186 "[{label}] iops value {val} must come from stdout \
4187 (< 9M) not stderr (9999999); a value from stderr \
4188 would prove the test's stream tag is accidentally \
4189 correct because the merge went the wrong way",
4190 val = iops.value,
4191 );
4192 }
4193 }
4194
4195 #[test]
4196 fn stderr_fallback_tags_metrics_with_metric_stream_stderr() {
4197 use crate::test_support::MetricStream;
4198
4199 for (label, stdout) in [
4200 ("empty-stdout", String::new()),
4201 (
4202 "prose-stdout",
4203 "no json here, just prose from a banner line\n".to_string(),
4204 ),
4205 (
4206 "valid-json-no-numeric-leaves-stdout",
4207 r#"{"status": "ok", "ready": true, "note": null}"#.to_string(),
4208 ),
4209 ] {
4210 let output = SpawnOutput {
4211 stdout,
4212 stderr: r#"{"iops": 4242}"#.to_string(),
4213 exit_code: 0,
4214 };
4215 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4216 assert_eq!(
4217 pm.metrics.len(),
4218 1,
4219 "[{label}] stderr fallback must produce exactly one metric",
4220 );
4221 assert_eq!(
4222 pm.metrics[0].stream,
4223 MetricStream::Stderr,
4224 "[{label}] fallback-extracted metric must carry MetricStream::Stderr \
4225 so downstream review tooling can distinguish stream origin; \
4226 got stream={:?}",
4227 pm.metrics[0].stream,
4228 );
4229 }
4230 }
4231
4232 /// Stdout present but unparseable (not-JSON prose); stderr
4233 /// carries the real document. `extract_metrics` returns `Vec`
4234 /// empty for malformed stdout, so the fallback runs against
4235 /// stderr and recovers the metrics. Pins that "non-empty stdout
4236 /// that yields no metrics" still triggers the retry — the
4237 /// stdout-primary contract gates on the result, not on emptiness.
4238 #[test]
4239 fn evaluate_falls_back_to_stderr_when_stdout_yields_no_metrics() {
4240 let output = SpawnOutput {
4241 stdout: "no json here, just prose from a banner line\n".to_string(),
4242 stderr: r#"{"throughput": 42}"#.to_string(),
4243 exit_code: 0,
4244 };
4245 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4246 assert_eq!(
4247 pm.metrics.len(),
4248 1,
4249 "stderr fallback must fire on empty result"
4250 );
4251 assert_eq!(pm.metrics[0].name, "throughput");
4252 assert_eq!(pm.metrics[0].value, 42.0);
4253 }
4254
4255 /// Stdout is valid JSON but contains only non-numeric leaves
4256 /// (strings, bools, nulls). `walk_json_leaves` at
4257 /// src/test_support/metrics.rs skips non-numeric leaves, so
4258 /// `extract_metrics` returns `Ok(vec![])` — a SUCCESSFUL parse
4259 /// with zero metrics. This is distinct from the
4260 /// "unparseable prose" case (`evaluate_falls_back_to_stderr_when_stdout_yields_no_metrics`
4261 /// above): that path fails to find any JSON document at all.
4262 /// The fallback condition (`evaluate`'s
4263 /// `if metrics.is_empty() && !output.stderr.is_empty()` gate)
4264 /// gates on `metrics.is_empty()`, not on parse success, so both
4265 /// paths must fall back to stderr. This test pins that: the
4266 /// fallback must not surface the empty stdout set as the
4267 /// result, and the string/bool/null leaves from stdout must
4268 /// not leak into the returned metrics (they can't — the walker
4269 /// never emitted them — but a future refactor that concatenated
4270 /// streams or merged results could regress this).
4271 #[test]
4272 fn evaluate_falls_back_when_stdout_json_has_no_numeric_leaves() {
4273 let output = SpawnOutput {
4274 stdout: r#"{"status": "ok", "ready": true, "note": null}"#.to_string(),
4275 stderr: r#"{"iops": 9001}"#.to_string(),
4276 exit_code: 0,
4277 };
4278 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4279 assert_eq!(
4280 pm.metrics.len(),
4281 1,
4282 "stderr fallback must fire when stdout parses but has \
4283 no numeric leaves; got metrics: {:?}",
4284 pm.metrics,
4285 );
4286 assert_eq!(pm.metrics[0].name, "iops");
4287 assert_eq!(pm.metrics[0].value, 9001.0);
4288 // No stray string/bool/null names leaked in from stdout.
4289 for m in &pm.metrics {
4290 assert!(
4291 !matches!(m.name.as_str(), "status" | "ready" | "note"),
4292 "non-numeric stdout leaf {:?} leaked into metrics",
4293 m.name,
4294 );
4295 }
4296 }
4297
4298 /// Inverse of the above: both streams parse to JSON with no
4299 /// numeric leaves. Stdout extracts to `Ok(vec![])`, fallback
4300 /// fires, stderr also extracts to `Ok(vec![])`. Final metric
4301 /// set must be empty — not a synthetic pseudo-metric, not a
4302 /// silent merge of the two empty results with added string
4303 /// keys. Guards against a fallback refactor that might
4304 /// misinterpret "both empty" as "degenerate, emit a sentinel".
4305 #[test]
4306 fn evaluate_returns_empty_when_both_streams_have_no_numeric_leaves() {
4307 let output = SpawnOutput {
4308 stdout: r#"{"phase": "warmup"}"#.to_string(),
4309 stderr: r#"{"phase": "shutdown"}"#.to_string(),
4310 exit_code: 0,
4311 };
4312 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4313 assert!(
4314 pm.metrics.is_empty(),
4315 "both-streams-non-numeric must produce no metrics; \
4316 got: {:?}",
4317 pm.metrics,
4318 );
4319 }
4320
4321 /// Both streams empty ⇒ no metrics; the fallback guard
4322 /// (`!output.stderr.is_empty()`) skips the second call and the
4323 /// extractor is invoked exactly once against empty stdout.
4324 #[test]
4325 fn evaluate_returns_empty_metrics_on_empty_stdout_and_stderr() {
4326 let output = SpawnOutput {
4327 stdout: String::new(),
4328 stderr: String::new(),
4329 exit_code: 0,
4330 };
4331 let (_, pm) = evaluate(&JSON_PAYLOAD, &[], output);
4332 assert!(pm.metrics.is_empty(), "both-empty must produce no metrics");
4333 assert_eq!(pm.exit_code, 0);
4334 }
4335
4336 /// Multi-process payloads (schbench worker mode, stress-ng, fio)
4337 /// fork descendants that keep stdout/stderr open past the head
4338 /// process. Without a process-group kill, `wait_and_capture`
4339 /// would block on a pipe that never EOFs and the test would
4340 /// either hang or time out without metrics.
4341 ///
4342 /// The payload `/bin/sh -c 'sleep 60 & exec sleep 60'` uses the
4343 /// shell's head process to exec into `sleep 60` (pid == pgid)
4344 /// while a background `sleep 60` descendant inherits the pgid.
4345 /// A single-process SIGKILL would leave the background sleeper
4346 /// alive; `killpg` must reach it.
4347 ///
4348 /// SIGKILL delivery may lag the caller. The bounded live-member
4349 /// check accepts a dead zombie that is awaiting an outer
4350 /// subreaper, but still fails if any member can execute.
4351 #[cfg(unix)]
4352 #[test]
4353 fn kill_reaps_fork_descendants_via_process_group() {
4354 with_ctx("/nonexistent", |ctx| {
4355 const MULTI_SLEEPER: Payload = Payload {
4356 name: "multi_sleeper",
4357 kind: PayloadKind::Binary("/bin/sh"),
4358 output: crate::test_support::OutputFormat::ExitCode,
4359 default_args: &["-c", "sleep 60 & exec sleep 60"],
4360 default_checks: &[],
4361 metrics: &[],
4362 include_files: &[],
4363 uses_parent_pgrp: false,
4364 known_flags: None,
4365 };
4366 let handle = PayloadRun::new(ctx, &MULTI_SLEEPER)
4367 .spawn()
4368 .expect("spawn multi-sleeper");
4369 // The pgid equals the head child's pid. Capture it via the
4370 // public `pid()` accessor so the test does not reach into the
4371 // private `child` field.
4372 let pgid = libc::pid_t::try_from(handle.pid().expect("child still present"))
4373 .expect("child pid fits in pid_t");
4374 let (_, _) = handle.kill().expect("kill+reap");
4375 wait_for_process_group_termination(
4376 pgid,
4377 std::time::Duration::from_secs(30),
4378 "explicit kill+reap",
4379 );
4380 });
4381 }
4382
4383 /// Drop path of [`PayloadHandle`]: a handle that falls out of
4384 /// scope WITHOUT any consuming call (no `wait`, no `kill`, no
4385 /// `try_wait`) must still SIGKILL the whole process group via
4386 /// `kill_payload_process_group`. Without the Drop sweep,
4387 /// multi-process payloads whose head exits while descendants
4388 /// linger would leak their leader pid and keep descendants
4389 /// alive on init, polluting later tests with stray children
4390 /// holding file descriptors.
4391 ///
4392 /// Mirrors `kill_reaps_fork_descendants_via_process_group`
4393 /// (the explicit-`kill()` counterpart) but drops the handle
4394 /// instead of calling kill — pins the Drop implementation's
4395 /// killpg route against the same backgrounded-sleeper shape.
4396 #[cfg(unix)]
4397 #[test]
4398 fn drop_kills_fork_descendants_via_process_group() {
4399 with_ctx("/nonexistent", |ctx| {
4400 const MULTI_SLEEPER: Payload = Payload {
4401 name: "multi_sleeper_drop",
4402 kind: PayloadKind::Binary("/bin/sh"),
4403 output: crate::test_support::OutputFormat::ExitCode,
4404 default_args: &["-c", "sleep 60 & exec sleep 60"],
4405 default_checks: &[],
4406 metrics: &[],
4407 include_files: &[],
4408 uses_parent_pgrp: false,
4409 known_flags: None,
4410 };
4411 let handle = PayloadRun::new(ctx, &MULTI_SLEEPER)
4412 .spawn()
4413 .expect("spawn multi-sleeper");
4414 // Capture the pgid via the public `pid()` accessor before
4415 // dropping, so we can probe the group after the handle
4416 // goes out of scope.
4417 let pgid = libc::pid_t::try_from(handle.pid().expect("child still present"))
4418 .expect("child pid fits in pid_t");
4419 // Drop (no wait/kill/try_wait). The Drop impl at
4420 // src/scenario/payload_run.rs routes through
4421 // `kill_payload_process_group` + `child.wait()`.
4422 drop(handle);
4423 wait_for_process_group_termination(
4424 pgid,
4425 std::time::Duration::from_secs(30),
4426 "PayloadHandle drop",
4427 );
4428 });
4429 }
4430
4431 /// `uses_parent_pgrp = true` SKIPS the `process_group(0)` call
4432 /// in `build_command`, so the child inherits the test
4433 /// process's pgid instead of becoming its own pgrp leader.
4434 /// Spawn a sleeping binary via a Payload with the flag set,
4435 /// `getpgid` the child's pid, and assert it equals the
4436 /// parent's pgid — that pairs the "opt-out" directive with
4437 /// the observable behaviour.
4438 #[cfg(unix)]
4439 #[test]
4440 fn payload_uses_parent_pgrp_opts_out_of_process_group() {
4441 with_ctx("/nonexistent", |ctx| {
4442 const PARENT_PGRP_SLEEPER: Payload = Payload {
4443 name: "parent_pgrp_sleeper",
4444 kind: PayloadKind::Binary("/bin/sleep"),
4445 output: crate::test_support::OutputFormat::ExitCode,
4446 default_args: &["60"],
4447 default_checks: &[],
4448 metrics: &[],
4449 include_files: &[],
4450 uses_parent_pgrp: true,
4451 known_flags: None,
4452 };
4453 let handle = PayloadRun::new(ctx, &PARENT_PGRP_SLEEPER)
4454 .spawn()
4455 .expect("spawn opt-out sleeper");
4456 let child_pid = libc::pid_t::try_from(handle.pid().expect("child alive"))
4457 .expect("child pid fits in pid_t");
4458 // SAFETY: getpgid(pid) is a pure lookup with no side
4459 // effects beyond returning the queried pid's pgid (or -1
4460 // + errno on failure).
4461 let child_pgid = unsafe { libc::getpgid(child_pid) };
4462 // SAFETY: getpgid(0) returns the CURRENT process's pgid
4463 // and cannot fail.
4464 let parent_pgid = unsafe { libc::getpgid(0) };
4465 assert!(child_pgid > 0, "getpgid(child) failed: {child_pgid}");
4466 assert_eq!(
4467 child_pgid, parent_pgid,
4468 "uses_parent_pgrp=true payload must inherit the \
4469 parent's pgid (child_pgid={child_pgid}, \
4470 parent_pgid={parent_pgid}); a mismatch means \
4471 `build_command` still called `process_group(0)` \
4472 despite the opt-out",
4473 );
4474 // kill() on a handle whose child is not a pgrp leader
4475 // still reaps normally — kill_payload_process_group
4476 // falls back to single-pid SIGKILL. Consume the handle
4477 // so the sleeper doesn't outlive the test; a silent
4478 // failure here would mask the test's own regression
4479 // (e.g. a broken kill path that leaks sleepers).
4480 let _ = handle.kill().expect("kill opt-out sleeper");
4481 });
4482 }
4483
4484 /// `wait_with_deadline` timeout kills the whole process group
4485 /// via killpg + single-pid SIGKILL. Spawn a multi-process
4486 /// shell, drive `wait_with_deadline` with a 500 ms budget
4487 /// (so the whole test fits inside the 30s-slack nextest
4488 /// budget without standing up a whole scenario) and probes the
4489 /// pgid after the deadline fires and proves no live member remains.
4490 #[cfg(unix)]
4491 #[test]
4492 fn wait_with_deadline_timeout_kills_process_group() {
4493 use std::os::unix::process::CommandExt;
4494 let mut child = std::process::Command::new("/bin/sh")
4495 .args(["-c", "sleep 60 & exec sleep 60"])
4496 .stdout(std::process::Stdio::piped())
4497 .stderr(std::process::Stdio::piped())
4498 .process_group(0)
4499 .spawn()
4500 .expect("spawn multi-sleeper");
4501 let pgid = libc::pid_t::try_from(child.id()).expect("child pid fits in pid_t");
4502 let start = std::time::Instant::now();
4503 let out = wait_with_deadline(
4504 &mut child,
4505 std::time::Duration::from_millis(500),
4506 "multi_sleeper_timeout",
4507 false,
4508 )
4509 .expect("wait_with_deadline returns Ok on timeout");
4510 let elapsed = start.elapsed();
4511 // Timeout must actually have elapsed — if the function
4512 // returns almost instantly, the pidfd/epoll loop is
4513 // short-circuiting on an unrelated signal rather than
4514 // waiting for the 500 ms deadline.
4515 assert!(
4516 elapsed >= std::time::Duration::from_millis(400),
4517 "wait_with_deadline returned after only {elapsed:?}; \
4518 deadline was 500 ms — check the epoll loop is honoring \
4519 the timeout rather than unblocking on an unrelated event",
4520 );
4521 // The drain result must be captured even on timeout.
4522 // After SIGKILL the child's std::process::ExitStatus has
4523 // no numeric code (killed by signal, `status.code()`
4524 // returns None), so `wait_and_capture` defaults to -1 at
4525 // src/scenario/payload_run.rs per the `unwrap_or(-1)`
4526 // fallback in its status-code read. Pin that contract —
4527 // a future refactor that surfaces the signal number as
4528 // the exit_code would regress this.
4529 assert_eq!(out.exit_code, -1);
4530 wait_for_process_group_termination(
4531 pgid,
4532 std::time::Duration::from_secs(30),
4533 "wait_with_deadline timeout",
4534 );
4535 }
4536
4537 /// [`spawn_error_context`] is the sole place the spawn-error
4538 /// surface is shaped. An `ErrorKind::NotFound` must grow the full
4539 /// remediation chain (include-files for CLI invocations,
4540 /// pre-install for `#[ktstr_test]` entries); every other errno
4541 /// MUST keep the minimal `"spawn '<binary>'"` context so the
4542 /// underlying `io::Error` chain surfaces unchanged. Pin both
4543 /// directions so a regression that (a) swallows the NotFound
4544 /// remediation or (b) sprays the remediation across unrelated
4545 /// errno paths surfaces here.
4546 #[test]
4547 fn spawn_error_context_enoent_attaches_remediation() {
4548 let err = std::io::Error::from_raw_os_error(libc::ENOENT);
4549 assert_eq!(err.kind(), std::io::ErrorKind::NotFound);
4550 let wrapped = super::spawn_error_context(err, "fio");
4551 let rendered = format!("{wrapped:#}");
4552 // Binary name still appears so `grep fio` still finds the error.
4553 assert!(rendered.contains("spawn 'fio'"), "got: {rendered}");
4554 // Remediation text must surface both mitigation paths.
4555 assert!(
4556 rendered.contains("not found on guest PATH"),
4557 "ENOENT branch must name the PATH miss: {rendered}"
4558 );
4559 assert!(
4560 rendered.contains("-i fio") || rendered.contains("--include-files fio"),
4561 "ENOENT branch must name the `-i <binary>` remediation: {rendered}"
4562 );
4563 assert!(
4564 rendered.contains("#[ktstr_test]"),
4565 "ENOENT branch must name the ktstr_test pre-install remediation: {rendered}"
4566 );
4567 }
4568
4569 #[test]
4570 fn spawn_error_context_non_enoent_keeps_minimal_context() {
4571 // EACCES is a representative non-NotFound errno. Any
4572 // remediation text leaking onto this path would mislead
4573 // users who e.g. hit a permission problem — the remediation
4574 // paths above (include-files, pre-install) are orthogonal
4575 // to the failure mode. Pin the absence.
4576 let err = std::io::Error::from_raw_os_error(libc::EACCES);
4577 assert_ne!(err.kind(), std::io::ErrorKind::NotFound);
4578 let wrapped = super::spawn_error_context(err, "fio");
4579 let rendered = format!("{wrapped:#}");
4580 assert!(rendered.contains("spawn 'fio'"), "got: {rendered}");
4581 assert!(
4582 !rendered.contains("-i fio"),
4583 "non-ENOENT must not leak the `-i` remediation: {rendered}"
4584 );
4585 assert!(
4586 !rendered.contains("--include-files"),
4587 "non-ENOENT must not leak the --include-files remediation: {rendered}"
4588 );
4589 assert!(
4590 !rendered.contains("#[ktstr_test]"),
4591 "non-ENOENT must not leak the ktstr_test remediation: {rendered}"
4592 );
4593 assert!(
4594 !rendered.contains("not found on guest PATH"),
4595 "non-ENOENT must not claim 'not found on PATH': {rendered}"
4596 );
4597 }
4598
4599 // -- cgroup-sync placement protocol --
4600
4601 /// When `cgroup_path` is `None`, `build_command` must return a
4602 /// Command with NO cgroup-sync handles. Regression guard
4603 /// against accidentally wiring the sync for inherited-cgroup
4604 /// placements, where the handshake would produce spurious
4605 /// pipe allocations and a spawn-thread round-trip for every
4606 /// payload run.
4607 #[test]
4608 fn build_command_without_cgroup_returns_no_sync_handles() {
4609 let (_cmd, handles) = super::build_command("/bin/true", &[], None, false).unwrap();
4610 assert!(
4611 handles.is_none(),
4612 "no cgroup_path ⇒ no sync handles — got Some(_)",
4613 );
4614 }
4615
4616 /// When `cgroup` is `Some(_)`, `build_command` must
4617 /// allocate both pipes and populate the cgroup.procs path
4618 /// plus the cgroup_name passed through. The target directory
4619 /// does NOT need to exist at build time — the placement is
4620 /// deferred to `spawn_with_cgroup_sync`, where a failure
4621 /// surfaces through the [`crate::cgroup::CgroupOps`] trait
4622 /// implementation's error context.
4623 #[test]
4624 fn build_command_with_cgroup_returns_sync_handles() {
4625 let fake_cg = std::path::PathBuf::from("/nonexistent/fake-cgroup");
4626 let (_cmd, handles) = super::build_command(
4627 "/bin/true",
4628 &[],
4629 Some(("fake-cg", fake_cg.as_path())),
4630 false,
4631 )
4632 .expect("build_command must defer cgroup-path validation to sync");
4633 let handles = handles.expect("cgroup path ⇒ handles");
4634 assert_eq!(
4635 handles.cgroup_procs_path,
4636 fake_cg.join("cgroup.procs"),
4637 "handles must carry <cg>/cgroup.procs verbatim",
4638 );
4639 assert_eq!(
4640 handles.cgroup_name, "fake-cg",
4641 "handles must carry the user-facing cgroup name verbatim",
4642 );
4643 // Both pipes must have valid fds on both ends (pipe2
4644 // succeeded).
4645 assert!(handles.notify.r_fd() >= 0);
4646 assert!(handles.notify.w_fd() >= 0);
4647 assert!(handles.release.r_fd() >= 0);
4648 assert!(handles.release.w_fd() >= 0);
4649 }
4650
4651 /// `PipePair::new` allocates a fresh pipe on every call;
4652 /// pins the Drop path closes both fds so repeated calls
4653 /// don't leak fd-table entries under test iteration.
4654 #[test]
4655 fn pipe_pair_allocates_fresh_pipe_on_each_call() {
4656 use std::io::{Read, Write};
4657 use std::os::fd::{AsRawFd, FromRawFd};
4658 let a = super::PipePair::new().unwrap();
4659 let b = super::PipePair::new().unwrap();
4660 // Distinct fd pairs.
4661 assert_ne!(a.r_fd(), b.r_fd());
4662 assert_ne!(a.w_fd(), b.w_fd());
4663 // Each pipe is a plumbed byte channel: write one byte
4664 // into A's write end, read it from A's read end.
4665 //
4666 // Drive the roundtrip via std::fs::File so we don't hit
4667 // libc directly in the test.
4668 {
4669 let mut w = unsafe { std::fs::File::from_raw_fd(a.w_fd()) };
4670 w.write_all(&[42u8]).unwrap();
4671 // Detach — the File closes the fd when dropped, but
4672 // we want the OwnedFd on the PipePair to handle it.
4673 std::mem::forget(w);
4674 }
4675 let mut buf = [0u8; 1];
4676 let mut r = unsafe { std::fs::File::from_raw_fd(a.read_fd.as_raw_fd()) };
4677 r.read_exact(&mut buf).unwrap();
4678 assert_eq!(buf[0], 42);
4679 std::mem::forget(r);
4680 // Drop the second pipe explicitly to exercise the Drop path.
4681 drop(b.read_fd);
4682 drop(b.write_fd);
4683 }
4684
4685 /// End-to-end: `drive_cgroup_handshake` reads a pid sent via the
4686 /// notify pipe, writes it to a temp "cgroup.procs" file, and
4687 /// releases the "child" via the release pipe. Exercises the
4688 /// real protocol without requiring a real cgroup — the temp
4689 /// file stands in for `/sys/fs/cgroup/<cg>/cgroup.procs`,
4690 /// whose acceptable write format is `<pid>\n`.
4691 ///
4692 /// Uses a synthetic Command that can't actually reach spawn
4693 /// (`/nonexistent`), but the test only drives the
4694 /// handshake half via a fake `CgroupSyncHandles`; the spawn
4695 /// side is stubbed by running the handshake directly, not
4696 /// through `drive_cgroup_handshake`'s thread wrapper.
4697 #[test]
4698 fn spawn_with_cgroup_sync_writes_pid_and_releases_child() {
4699 use std::io::Read;
4700 use std::os::fd::FromRawFd;
4701
4702 // Stand-in for cgroup.procs in a temp dir. The CgroupManager
4703 // points at `parent_dir`; the cgroup_name is `cg_leaf`, so
4704 // the trait derives `parent_dir/cg_leaf/cgroup.procs` =
4705 // `procs_path` — matches the real production resolution.
4706 let parent_dir = std::env::temp_dir().join(format!("ktstr-cgroup-sync-test-{}", unsafe {
4707 libc::getpid()
4708 }));
4709 std::fs::create_dir_all(&parent_dir).unwrap();
4710 let leaf_dir = parent_dir.join("cg_leaf");
4711 std::fs::create_dir_all(&leaf_dir).unwrap();
4712 let procs_path = leaf_dir.join("cgroup.procs");
4713 std::fs::write(&procs_path, b"").unwrap();
4714
4715 // Allocate two pipe pairs — one notify, one release.
4716 let notify = super::PipePair::new().unwrap();
4717 let release = super::PipePair::new().unwrap();
4718
4719 // Simulate child pre_exec: write pid into notify,
4720 // block on release. Run on a thread so the main test
4721 // thread can drive the handshake without a deadlock.
4722 let child_pid: libc::pid_t = 99999;
4723 let notify_w_fd = notify.w_fd();
4724 let release_r_fd = release.r_fd();
4725 let child_thread = std::thread::spawn(move || {
4726 use std::io::Write;
4727 // Write pid as LE bytes, matching the real pre_exec.
4728 let mut w = unsafe { std::fs::File::from_raw_fd(notify_w_fd) };
4729 w.write_all(&child_pid.to_le_bytes()).unwrap();
4730 drop(w);
4731 // Block on release.
4732 let mut r = unsafe { std::fs::File::from_raw_fd(release_r_fd) };
4733 let mut buf = [0u8; 1];
4734 r.read_exact(&mut buf).unwrap();
4735 assert_eq!(buf[0], 1, "release byte must be 1");
4736 drop(r);
4737 });
4738
4739 // Prevent PipePair's Drop from closing the fds we
4740 // handed to the thread — the thread owns them now.
4741 std::mem::forget(notify.write_fd);
4742 std::mem::forget(release.read_fd);
4743
4744 // Reassemble the handles into the bundle
4745 // `spawn_with_cgroup_sync` consumes. We MUST rebuild the
4746 // PipePair with the remaining fds so its Drop closes
4747 // them on exit.
4748 let notify_r = notify.read_fd;
4749 let release_w = release.write_fd;
4750 let handles = super::CgroupSyncHandles {
4751 notify: super::PipePair {
4752 read_fd: notify_r,
4753 // Dummy fd the drop will close — we need
4754 // something valid. /dev/null satisfies that.
4755 write_fd: unsafe {
4756 std::os::fd::OwnedFd::from_raw_fd(libc::open(
4757 c"/dev/null".as_ptr(),
4758 libc::O_WRONLY,
4759 ))
4760 },
4761 },
4762 release: super::PipePair {
4763 read_fd: unsafe {
4764 std::os::fd::OwnedFd::from_raw_fd(libc::open(
4765 c"/dev/null".as_ptr(),
4766 libc::O_RDONLY,
4767 ))
4768 },
4769 write_fd: release_w,
4770 },
4771 cgroup_name: "cg_leaf".to_string(),
4772 cgroup_procs_path: procs_path.clone(),
4773 };
4774
4775 // CgroupManager.parent_path = parent_dir, so
4776 // place_task_during_handshake("cg_leaf", pid) targets
4777 // parent_dir/cg_leaf/cgroup.procs = procs_path.
4778 let mgr = crate::cgroup::CgroupManager::new(parent_dir.to_str().unwrap());
4779
4780 // Drive the handshake on the main thread.
4781 let returned_pid = super::spawn_with_cgroup_sync(handles, &mgr).unwrap();
4782 assert_eq!(
4783 returned_pid, child_pid,
4784 "spawn_with_cgroup_sync must return the pid it read \
4785 from the notify pipe",
4786 );
4787
4788 // The child thread must complete after the release byte
4789 // arrives — join here and capture any panic propagation.
4790 child_thread
4791 .join()
4792 .expect("child thread completes after release");
4793
4794 // The temp cgroup.procs file must now contain the pid
4795 // followed by a newline (`CgroupManager::place_task_during_handshake`
4796 // writes the same `<pid>\n` shape the bare-stdlib path used).
4797 let written = std::fs::read_to_string(&procs_path).unwrap();
4798 assert_eq!(
4799 written,
4800 format!("{child_pid}\n"),
4801 "spawn_with_cgroup_sync must write <pid>\\n to cgroup.procs; \
4802 got {written:?}",
4803 );
4804
4805 // Cleanup.
4806 let _ = std::fs::remove_file(&procs_path);
4807 let _ = std::fs::remove_dir(&leaf_dir);
4808 let _ = std::fs::remove_dir(&parent_dir);
4809 }
4810
4811 /// Failure shape: if the placement trait call cannot reach the
4812 /// target cgroup (parent dir missing), the handshake surfaces
4813 /// an error that names both the cgroup_name the trait received
4814 /// AND the absolute cgroup.procs path the implementation
4815 /// derived. The child thread must NOT hang — it receives EOF
4816 /// on its release read because the handles (carrying the
4817 /// release write end) are dropped on the error path.
4818 #[test]
4819 fn spawn_with_cgroup_sync_errors_on_missing_cgroup_procs_path() {
4820 use std::os::fd::FromRawFd;
4821 let missing_parent = std::path::PathBuf::from("/nonexistent/dir/that/does/not/exist");
4822 let missing_path = missing_parent.join("missing-cg").join("cgroup.procs");
4823
4824 let notify = super::PipePair::new().unwrap();
4825 let release = super::PipePair::new().unwrap();
4826
4827 let child_pid: libc::pid_t = 12345;
4828 let notify_w_fd = notify.w_fd();
4829 let release_r_fd = release.r_fd();
4830 let child_thread = std::thread::spawn(move || -> std::io::Error {
4831 use std::io::{Read, Write};
4832 let mut w = unsafe { std::fs::File::from_raw_fd(notify_w_fd) };
4833 let _ = w.write_all(&child_pid.to_le_bytes());
4834 drop(w);
4835 // Block on release. Expect EOF (read_exact → Err
4836 // when the parent drops its write end on the error
4837 // path).
4838 let mut r = unsafe { std::fs::File::from_raw_fd(release_r_fd) };
4839 let mut buf = [0u8; 1];
4840 let err = r.read_exact(&mut buf).unwrap_err();
4841 drop(r);
4842 err
4843 });
4844
4845 std::mem::forget(notify.write_fd);
4846 std::mem::forget(release.read_fd);
4847
4848 let notify_r = notify.read_fd;
4849 let release_w = release.write_fd;
4850 let handles = super::CgroupSyncHandles {
4851 notify: super::PipePair {
4852 read_fd: notify_r,
4853 write_fd: unsafe {
4854 std::os::fd::OwnedFd::from_raw_fd(libc::open(
4855 c"/dev/null".as_ptr(),
4856 libc::O_WRONLY,
4857 ))
4858 },
4859 },
4860 release: super::PipePair {
4861 read_fd: unsafe {
4862 std::os::fd::OwnedFd::from_raw_fd(libc::open(
4863 c"/dev/null".as_ptr(),
4864 libc::O_RDONLY,
4865 ))
4866 },
4867 write_fd: release_w,
4868 },
4869 cgroup_name: "missing-cg".to_string(),
4870 cgroup_procs_path: missing_path.clone(),
4871 };
4872
4873 let mgr = crate::cgroup::CgroupManager::new(missing_parent.to_str().unwrap());
4874 let err = super::spawn_with_cgroup_sync(handles, &mgr).unwrap_err();
4875 let rendered = format!("{err:#}");
4876 assert!(
4877 rendered.contains("missing-cg"),
4878 "error must name the user-facing cgroup name: {rendered}",
4879 );
4880 assert!(
4881 rendered.contains("/nonexistent/dir/that/does/not/exist"),
4882 "error must name the failing path: {rendered}",
4883 );
4884
4885 // Child thread sees EOF because the release write end
4886 // was dropped on the error path.
4887 let child_err = child_thread.join().expect("child thread returns");
4888 assert_eq!(
4889 child_err.kind(),
4890 std::io::ErrorKind::UnexpectedEof,
4891 "child's release read must hit EOF when parent abandons sync; got {child_err}",
4892 );
4893 }
4894
4895 /// **Regression guard for the cross-fork inherited-fd
4896 /// deadlock.** Exercises the REAL fork path: builds a
4897 /// cgroup-sync Command targeting `/bin/true` against a
4898 /// nonexistent cgroup path, then calls
4899 /// [`drive_cgroup_handshake`] (which runs `Command::spawn()`
4900 /// on a thread and drives the parent-side protocol on the
4901 /// main thread).
4902 ///
4903 /// On the error path the parent drops its owned
4904 /// `release.write_fd` when `drive_cgroup_handshake` bails
4905 /// on the missing cgroup.procs. **Without `cgroup_sync_pre_exec`
4906 /// closing the CHILD's inherited copy of `release_write_fd`
4907 /// (Step 0 of the pre_exec protocol)**, the kernel still
4908 /// sees the child's inherited writer alive — the pipe never
4909 /// EOFs — the child's `read(release_read_fd)` blocks forever
4910 /// — `drive_cgroup_handshake` returns the error but the
4911 /// spawn thread's `join()` blocks indefinitely.
4912 ///
4913 /// With the Step 0 close in place, the child's pre_exec
4914 /// read hits EOF (→ EPIPE), the stdlib spawn path writes
4915 /// the errno to its CLOEXEC error channel and tears down
4916 /// the child, the spawn thread's `cmd.spawn()` returns
4917 /// `Err`, and our `join()` completes within the test
4918 /// deadline. A 10s timeout wraps the whole handshake —
4919 /// a regression that re-introduces the inherited-fd leak
4920 /// surfaces as a timeout panic, not a hang.
4921 #[test]
4922 fn drive_cgroup_handshake_does_not_deadlock_on_failing_cgroup_write() {
4923 use std::sync::mpsc;
4924
4925 // Pick a path that cannot possibly open — including a
4926 // guaranteed-missing parent dir so the placement step
4927 // fails hard in `drive_cgroup_handshake`.
4928 let missing_parent =
4929 std::path::PathBuf::from("/nonexistent/ktstr-cgroup-sync-deadlock-parent");
4930 let missing_cgroup = missing_parent.join("deadlock-guard");
4931
4932 // Run the whole exercise in a worker thread so the test
4933 // driver can time-box it: if the child's release read
4934 // ever blocks past the 10s budget we PANIC the timer
4935 // thread rather than hang the test harness.
4936 let (tx, rx) = mpsc::channel::<anyhow::Result<()>>();
4937 let worker = std::thread::spawn(move || {
4938 let (cmd, handles) = super::build_command(
4939 "/bin/true",
4940 &[],
4941 Some(("deadlock-guard", missing_cgroup.as_path())),
4942 false,
4943 )
4944 .expect("build_command");
4945 let handles = handles.expect("handles present when cgroup is Some");
4946 // CgroupManager whose `parent` does not exist, so
4947 // `place_task_during_handshake` will fail on the
4948 // bare `<missing>/<cg>/cgroup.procs` write — the
4949 // same failure shape the deadlock guard targets.
4950 let mgr = crate::cgroup::CgroupManager::new(missing_parent.to_str().unwrap());
4951 let result = super::drive_cgroup_handshake(cmd, handles, "/bin/true", &mgr);
4952 // drive_cgroup_handshake must surface an error
4953 // (the placement write failed) — if it succeeds
4954 // that's also a correctness violation because the
4955 // target directory does not exist.
4956 let err = result.expect_err("handshake against nonexistent cgroup.procs must Err");
4957 let rendered = format!("{err:#}");
4958 assert!(
4959 rendered.contains("cgroup.procs") || rendered.contains("deadlock-guard"),
4960 "handshake error must name the failing step: {rendered}",
4961 );
4962 let _ = tx.send(Ok(()));
4963 });
4964
4965 // 10s deadline — well beyond any legitimate stdlib spawn
4966 // + fork + pre_exec + error-channel latency on a loaded
4967 // CI host, tight enough to flag a real deadlock quickly.
4968 let deadline = std::time::Duration::from_secs(10);
4969 match rx.recv_timeout(deadline) {
4970 Ok(Ok(())) => {
4971 // Worker thread finished cleanly within budget.
4972 worker
4973 .join()
4974 .expect("worker thread completes without panic");
4975 }
4976 Ok(Err(e)) => panic!("worker thread reported error: {e:#}"),
4977 Err(mpsc::RecvTimeoutError::Timeout) => panic!(
4978 "drive_cgroup_handshake did not return within \
4979 {deadline:?} — cross-fork inherited-fd deadlock \
4980 has regressed. The child's pre_exec is almost \
4981 certainly blocking on `read(release_read_fd)` \
4982 because it still holds its own inherited copy of \
4983 `release_write_fd` open; Step 0 of \
4984 `cgroup_sync_pre_exec` must `close()` both \
4985 `notify_read_fd` and `release_write_fd` BEFORE \
4986 the release-read block, otherwise the kernel \
4987 never delivers EOF when the parent drops its \
4988 write end.",
4989 ),
4990 Err(mpsc::RecvTimeoutError::Disconnected) => {
4991 panic!("worker thread disconnected without reporting",)
4992 }
4993 }
4994 }
4995
4996 /// LIFO-drop pin for [`SigchldScope`]'s save-and-restore chain.
4997 ///
4998 /// `SigchldScope::new()` installs `SIG_DFL` and captures the
4999 /// PREVIOUS disposition into `prev`. When two scopes are
5000 /// constructed back-to-back on the same thread, the second
5001 /// scope's `prev` is the FIRST scope's `SIG_DFL` install (not
5002 /// the original disposition). The original disposition lives in
5003 /// the FIRST scope's `prev`.
5004 ///
5005 /// Drop order therefore matters: LIFO (drop second-constructed
5006 /// first) unwinds correctly — second drop restores `SIG_DFL`,
5007 /// first drop restores the original. NON-LIFO (drop
5008 /// first-constructed first) corrupts the disposition: first
5009 /// drop restores the original, second drop overwrites it with
5010 /// `SIG_DFL`, and the rest of the process runs with the wrong
5011 /// SIGCHLD handler.
5012 ///
5013 /// `PayloadHandle` keeps `_sigchld` as the LAST struct field so
5014 /// per-handle drop is always LIFO with respect to the child it
5015 /// guards — the field-order rule documented at the
5016 /// `PayloadHandle` definition. This test pins that LIFO drop of
5017 /// nested scopes preserves the initial disposition by capturing
5018 /// the disposition before, during, and after the scope chain
5019 /// unwinds, then asserting only the LIFO ordering produces the
5020 /// "after == initial" outcome.
5021 ///
5022 /// Implementation note: `libc::signal` returns the previous
5023 /// handler on every call. We use that as the read mechanism —
5024 /// install `SIG_DFL` to read the current handler, then
5025 /// immediately restore it. The read itself is destructive, so
5026 /// the helper has to put the original back before returning.
5027 ///
5028 /// The thread-pin in `SigchldScope::new` requires every
5029 /// construction in the process to come from the SAME thread.
5030 /// Nextest runs each test in its own process (per
5031 /// `.config/nextest.toml`), so this test's thread-of-call wins
5032 /// the pin and other tests' threads are isolated.
5033 #[test]
5034 fn sigchld_scope_lifo_drop_restores_initial_disposition() {
5035 // Read the current SIGCHLD disposition non-destructively by
5036 // saving the value `signal()` returns, then immediately
5037 // re-installing it. SAFETY: same as SigchldScope::new — the
5038 // thread-pin guarantees no other thread is racing the
5039 // process-wide disposition install.
5040 fn read_sigchld() -> libc::sighandler_t {
5041 // Pin the construction thread BEFORE we install — the
5042 // SigchldScope thread-pin is initialized on its first
5043 // `new()` call, but this helper runs before any scope
5044 // is constructed. Without a separate pin step, the
5045 // first scope below would be the one that pins. That
5046 // is fine in practice; the helper just has to use the
5047 // same thread the scopes do, which is the test thread.
5048 let handler = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
5049 // Restore immediately so we don't leak the read-side
5050 // SIG_DFL into the rest of the test. Note: this is
5051 // observably equivalent to "do nothing" if the
5052 // disposition WAS already SIG_DFL, which is the common
5053 // case on the host (the guest init's SIG_IGN flip is
5054 // not active in the unit-test process).
5055 unsafe {
5056 libc::signal(libc::SIGCHLD, handler);
5057 }
5058 handler
5059 }
5060
5061 let initial = read_sigchld();
5062 // Construct nested scopes:
5063 // - outer.prev = initial; outer's new() installs SIG_DFL.
5064 // - inner.prev = SIG_DFL; inner's new() installs SIG_DFL
5065 // (a no-op since outer already did).
5066 // After both new() calls, the live disposition is SIG_DFL.
5067 let outer = SigchldScope::new();
5068 let inner = SigchldScope::new();
5069 // LIFO drop: inner (constructed second) first.
5070 // - inner.drop() re-installs inner.prev (= SIG_DFL).
5071 // Live disposition: SIG_DFL.
5072 // - Read confirms SIG_DFL.
5073 // - outer.drop() re-installs outer.prev (= initial).
5074 // Live disposition: initial.
5075 // - Read confirms initial.
5076 //
5077 // Non-LIFO drop (drop outer first, then inner) would
5078 // produce: outer.drop() restores initial, inner.drop()
5079 // overwrites with SIG_DFL. The final read would see
5080 // SIG_DFL != initial. This test pins LIFO by structuring
5081 // the drops in LIFO order and asserting initial is
5082 // restored at the end. A future refactor that reordered
5083 // struct fields or shuffled drops would trip the final
5084 // assert.
5085 drop(inner);
5086 assert_eq!(
5087 read_sigchld(),
5088 libc::SIG_DFL,
5089 "after inner drop, live disposition must be SIG_DFL — \
5090 inner.prev was outer's SIG_DFL install, not initial",
5091 );
5092 drop(outer);
5093 assert_eq!(
5094 read_sigchld(),
5095 initial,
5096 "after outer drop, live disposition must equal initial \
5097 ({initial:#x}); a non-LIFO drop would leave SIG_DFL \
5098 ({:#x}) leaking into the process",
5099 libc::SIG_DFL,
5100 );
5101 }
5102
5103 /// Drop-side pin for [`PayloadHandle`]: dropping a real handle
5104 /// restores the SIGCHLD disposition.
5105 ///
5106 /// Rust drops struct fields in declaration order. The
5107 /// `PayloadHandle` definition (see the `DROP-ORDER-CRITICAL`
5108 /// comment block above the struct) requires `_sigchld` to drop
5109 /// AFTER `child`: while the child is being reaped on the drop
5110 /// path (via `kill_payload_process_group` + `child.wait()` in
5111 /// `Drop for PayloadHandle`), the SIGCHLD disposition must still
5112 /// be `SIG_DFL` so `waitpid` returns the real exit status instead
5113 /// of failing with `ECHILD` under the guest init's `SIGCHLD =
5114 /// SIG_IGN`. If `_sigchld` were dropped before `child`, its
5115 /// `Drop` would re-install the original (potentially `SIG_IGN`)
5116 /// disposition while `child.wait()` was still in flight and the
5117 /// reap could fail.
5118 ///
5119 /// `PayloadHandle::child` is `Option<std::process::Child>`; the
5120 /// `Drop for PayloadHandle` body gates its kill-and-reap path on
5121 /// `if let Some(mut child) = self.child.take()`, so `child:
5122 /// None` is a valid in-test construction whose handle Drop
5123 /// path is a no-op for the child branch but still drops every
5124 /// field in declaration order. This test constructs a real
5125 /// `PayloadHandle` (not a mirror) with `child: None`, a static
5126 /// `Payload`, an empty `checks` vec, and a real `SigchldScope`
5127 /// and asserts that the SIGCHLD disposition is restored to its
5128 /// initial value after the handle drops. Building the real
5129 /// struct exercises the actual field declaration order — a
5130 /// future refactor that drops `_sigchld` from the field list,
5131 /// renames it, or replaces its type compiles ONLY if this test
5132 /// is updated in lock-step.
5133 ///
5134 /// The thread-pin in `SigchldScope::new` requires every
5135 /// construction in the process to come from the SAME thread.
5136 /// Nextest runs each test in its own process (per
5137 /// `.config/nextest.toml`), so this test's thread-of-call wins
5138 /// the pin and other tests' threads are isolated.
5139 #[test]
5140 fn payload_handle_drop_restores_sigchld_disposition() {
5141 // Read the current SIGCHLD disposition non-destructively by
5142 // saving the value `signal()` returns, then immediately
5143 // re-installing it. SAFETY: same as SigchldScope::new — the
5144 // thread-pin guarantees no other thread is racing the
5145 // process-wide disposition install.
5146 fn read_sigchld() -> libc::sighandler_t {
5147 let handler = unsafe { libc::signal(libc::SIGCHLD, libc::SIG_DFL) };
5148 unsafe {
5149 libc::signal(libc::SIGCHLD, handler);
5150 }
5151 handler
5152 }
5153
5154 let initial = read_sigchld();
5155
5156 // Build a real PayloadHandle. `child: None` means the
5157 // `Drop for PayloadHandle` body's `if let Some(...)` arm is
5158 // not taken, so no kill/reap runs — but every field still
5159 // drops in declaration order, so `_sigchld` (declared last)
5160 // restores the SIGCHLD disposition. TRUE_BIN is a `&'static
5161 // Payload` from this test module.
5162 let handle = PayloadHandle {
5163 child: None,
5164 payload: &TRUE_BIN,
5165 checks: Vec::new(),
5166 _sigchld: SigchldScope::new(),
5167 };
5168
5169 // After SigchldScope::new(), live disposition is SIG_DFL.
5170 assert_eq!(
5171 read_sigchld(),
5172 libc::SIG_DFL,
5173 "SigchldScope::new should have installed SIG_DFL while \
5174 the handle is alive",
5175 );
5176
5177 drop(handle);
5178
5179 // After Drop for PayloadHandle runs, every field has been
5180 // dropped — including _sigchld, whose Drop re-installs the
5181 // captured `prev` (= initial). If a future refactor removed
5182 // _sigchld from the struct (or changed its type to one
5183 // whose Drop does not restore the signal), this assertion
5184 // fails because the live disposition would still be
5185 // SIG_DFL, not initial.
5186 assert_eq!(
5187 read_sigchld(),
5188 initial,
5189 "after dropping a real PayloadHandle, live SIGCHLD \
5190 disposition must equal initial ({initial:#x}); if the \
5191 handle's `_sigchld` field was removed, renamed, or \
5192 retyped, the disposition stays at SIG_DFL ({:#x})",
5193 libc::SIG_DFL,
5194 );
5195 }
5196}