Skip to main content

detcore_model/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! Widely-shared type definitions.
10
11pub mod backend_engagement;
12pub mod build_info;
13pub mod bundled_signal_facts;
14pub mod canonical_test_epoch;
15pub mod cpu_profile;
16pub mod host_capability;
17
18/// Exit status for a run HERMIT DELIBERATELY REFUSED, as distinct from one
19/// where hermit itself broke.
20///
21/// ⚠️ "REFUSED" AND "BROKE" DEMAND OPPOSITE RESPONSES, AND THEY WERE THE SAME
22/// NUMBER. A fail-closed policy stopping a run is hermit working correctly: the
23/// operator must read the refusal and change their program or their flags.
24/// `HERMIT_INTERNAL_FAILURE_EXIT` (125) says hermit is broken and the operator
25/// must file a bug. Reporting the first as the second sends a reader looking
26/// for a defect in a shutdown path that behaved exactly as designed.
27///
28/// ⚠️ WHY IT IS NOT 1, WHICH IS WHAT THIS PATH USED TO EXIT.
29/// `unrecoverable_shutdown` called `std::process::exit(1)`, so the container
30/// child exited 1 and the parent's classifier — whose arm is documented "the
31/// child died with a status it did not pick" — turned a status hermit HAD
32/// picked into `class=container-child-exit` and 125. Restoring 1 would fix the
33/// misclassification and reintroduce a worse one: 1 is the commonest guest exit
34/// status, so it cannot distinguish "hermit refused" from "your program
35/// returned 1".
36///
37/// ⚠️ WHY 122. It sits immediately below the reserved band (123 log byte cap --
38/// hermit's `--max-log-bytes`, and the value reserved for `bin/safehermit`'s
39/// log-cap kill, which still exits 125 -- then 124 deadline, 125 hermit broke,
40/// 126/127 GNU exec-level), keeping the reserved codes contiguous, and it is
41/// the cheapest possible narrowing of the guest range. See the full allocation
42/// above the constants in `hermit-cli/src/lib.rs`.
43///
44/// ⚠️ IT LIVES IN `detcore-model` BECAUSE BOTH SIDES NEED IT. `detcore` emits it
45/// and `hermit-cli` recognises it; `detcore-model` is the only crate both
46/// depend on. A copy on each side is exactly the defect that left eight cli
47/// tests asserting a stale exit status for a day after the product moved.
48pub const HERMIT_POLICY_REFUSAL_EXIT: i32 = 122;
49
50// ⚠️ THE VALUE IS PINNED, NOT ONLY NAMED. `tests/cli.rs` and the allocation
51// table both assert 122; a one-character edit here would move every consumer
52// with it and nothing would fail. 0 is called out separately because it is the
53// dangerous drift: at 0 a refusal would report SUCCESS.
54const _: () = assert!(
55    HERMIT_POLICY_REFUSAL_EXIT == 122,
56    "122 keeps the reserved band contiguous below 123/124/125/126/127"
57);
58const _: () = assert!(
59    HERMIT_POLICY_REFUSAL_EXIT != 0,
60    "a refusal exiting 0 would report success"
61);
62
63/// The shell's base for "killed by signal N": a process killed by signal `N` is
64/// conventionally reported as `128 + N`.
65pub const SIGNAL_EXIT_BASE: i32 = 128;
66
67/// The status a signal-terminated run reports, `128 + signo`.
68///
69/// ⚠️ A SIGNAL DEATH IS NOT A POLICY REFUSAL, AND FOR ONE RELEASE IT WAS SPELLED
70/// AS ONE. `sigint_instakill` is one of four `unrecoverable_shutdown` callers.
71/// The other three are fail-closed policy decisions where
72/// `HERMIT_POLICY_REFUSAL_EXIT` is right: hermit examined the run and refused it.
73/// This one is an OPERATOR INTERRUPT — hermit refused nothing, somebody pressed
74/// Ctrl-C — so reporting it as a refusal tells the reader hermit made a decision
75/// it did not make. hermit#2659 moved all four off `exit(1)` together, which was
76/// an improvement for all four (they had been reported as `125`, "hermit broke")
77/// and correct for only three.
78///
79/// ⚠️ IT ALSO PUT TWO MEANINGS ON 122, WHICH IS THE DEFECT THIS REMOVES. With the
80/// SIGINT path exiting `HERMIT_POLICY_REFUSAL_EXIT`, 122 meant both "a fail-closed
81/// policy stopped the run" and "the operator killed it" — a legible number with
82/// two conditions behind it, which is the exact family `125` was split up to end.
83///
84/// ⚠️ WHY THIS IS NOT A GENUINE `WIFSIGNALED` STATUS. The faithful way to honour a
85/// signal is restore `SIG_DFL`, unblock, re-raise — and it is measurably
86/// unavailable here for the same reason it is unavailable to
87/// `on_container_init_stop_signal`: a self-sent signal does not come from an
88/// ancestor namespace, so a namespace init discards it exactly like the original
89/// and survives. `128 + signo` is the closest honest approximation, and it is the
90/// spelling that function already uses — this shares its convention rather than
91/// inventing a second one.
92pub const fn signal_exit_status(signo: i32) -> i32 {
93    SIGNAL_EXIT_BASE + signo
94}
95
96/// `128 + SIGINT`. Spelled from the shared helper so it cannot drift from the
97/// band, and pinned below so it cannot drift from 130.
98pub const HERMIT_SIGINT_DEATH_EXIT: i32 = signal_exit_status(2);
99
100/// The highest signal number this recognises, `SIGRTMAX` on Linux.
101const MAX_SIGNO: i32 = 64;
102
103/// Recover the signal from a `128 + signo` status, or `None` if it is not in the
104/// band.
105///
106/// ⚠️ THE PARENT NEEDS THIS BECAUSE THE CHILD CANNOT SEND A REAL SIGNAL STATUS.
107/// Without it the classifier's catch-all treats every non-refusal child exit as
108/// unaccounted and reports `125`, so making the SIGINT path exit `130` on its own
109/// would have moved Ctrl-C from "hermit refused" to "hermit broke" — worse than
110/// what it replaced. Emitting the code and recognising the code are one change.
111///
112/// ⚠️ IT IS DELIBERATELY A BAND AND NOT A SINGLE VALUE. `sigint_instakill` is not
113/// the only producer: `on_container_init_stop_signal` already exits
114/// `128 + signo` for SIGTERM, SIGINT and SIGHUP (143, 130, 129), so keying on 130
115/// alone would leave the other two misreported as internal failures.
116///
117/// The upper bound is `SIGRTMAX`; above it, a status is a guest's own number and
118/// not a signal this can honestly name.
119pub const fn signal_from_exit_status(status: i32) -> Option<i32> {
120    if status > SIGNAL_EXIT_BASE && status <= SIGNAL_EXIT_BASE + MAX_SIGNO {
121        Some(status - SIGNAL_EXIT_BASE)
122    } else {
123        None
124    }
125}
126
127// ⚠️ THE ROUND TRIP IS PINNED, INCLUDING THE EDGES. 128 is excluded (there is no
128// signal 0) and the refusal code must not be readable as a signal, or the two
129// classifier arms would both match and the order would silently decide meaning.
130const _: () = assert!(matches!(signal_from_exit_status(130), Some(2)));
131const _: () = assert!(matches!(signal_from_exit_status(143), Some(15)));
132const _: () = assert!(signal_from_exit_status(SIGNAL_EXIT_BASE).is_none());
133// ⚠️ THE UPPER EDGE, WHICH WAS UNPINNED WHILE THIS COMMENT CLAIMED IT WAS NOT.
134// agent(hermit-005)'s codex lane proved it vacuous: `MAX_SIGNO` 64 -> 15 left
135// every test green, so nothing held the top of the band. 192 is `128 + SIGRTMAX`
136// and is the last status that IS a signal; 193 is the first that is not and
137// belongs to the guest. A band needs both edges or it has one.
138const _: () = assert!(
139    matches!(
140        signal_from_exit_status(SIGNAL_EXIT_BASE + MAX_SIGNO),
141        Some(MAX_SIGNO)
142    ),
143    "128 + SIGRTMAX is the last status in the band"
144);
145const _: () = assert!(
146    signal_from_exit_status(SIGNAL_EXIT_BASE + MAX_SIGNO + 1).is_none(),
147    "above SIGRTMAX a status is the guest's own number, not a signal"
148);
149const _: () = assert!(
150    signal_from_exit_status(HERMIT_POLICY_REFUSAL_EXIT).is_none(),
151    "a policy refusal must not also parse as a signal death"
152);
153
154// ⚠️ PINNED AGAINST BOTH FAILURE DIRECTIONS. The first pin catches the band
155// moving; the second catches the far worse edit, because the whole point of the
156// change is that these two values are DIFFERENT. If a refactor ever collapsed
157// them the build fails here rather than silently restoring the ambiguity.
158const _: () = assert!(
159    HERMIT_SIGINT_DEATH_EXIT == 130,
160    "128 + SIGINT(2); the shell convention every other tool reports"
161);
162const _: () = assert!(
163    HERMIT_SIGINT_DEATH_EXIT != HERMIT_POLICY_REFUSAL_EXIT,
164    "a signal death and a policy refusal must not share a code -- that collision is the defect"
165);
166
167pub mod collections;
168pub mod config;
169pub mod container_mounts;
170pub mod fd;
171pub mod futex;
172pub mod happens_before;
173pub mod host_input;
174pub mod liteinst_initial_image;
175/// Bounded sealed native target catalog data, without admission authority.
176#[cfg(feature = "native-exec")]
177pub mod liteinst_native_exec_catalog;
178pub mod liteinst_native_exec_input;
179/// Exact versioned neutral cut envelope outside opaque Tool state.
180pub mod liteinst_native_exec_state;
181pub mod logdiff_policy;
182pub mod network_engine;
183pub mod network_trace;
184pub mod pedigree;
185pub mod pid;
186pub mod procfs;
187pub mod schedule;
188pub mod summary;
189pub mod time;
190
191/// Exact native runtime/dispatch-sequence envelope, separate from admission.
192pub mod liteinst_native_exec_runtime;
193
194#[cfg(feature = "native-exec")]
195pub mod liteinst_native_exec_sources;