hermit/error.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
9use serde::Deserialize;
10use serde::Serialize;
11
12pub type Error = anyhow::Error;
13
14pub use anyhow::Context;
15
16/// A serializable error. This is useful for sending an error to the parent
17/// process. This works by converting an error into a string via its `Display`
18/// implementation. Although we lose type information in the process of
19/// converting to a string, this preserves the error message and its error chain.
20#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, Eq, PartialEq)]
21pub enum FailureKind {
22 /// The child reported a failure it decided to report.
23 #[default]
24 Error,
25 /// The child PANICKED and the panic was caught and reported.
26 ///
27 /// ⚠️ THIS IS THE ONE BIT THAT PROSE CANNOT CARRY. A caught panic and a
28 /// reported error arrive at the parent as the same shape -- a message and a
29 /// chain of causes -- so without a discriminant the parent must either
30 /// match on English or call them the same thing. It called them the same
31 /// thing, which is why a tracer panic and a bad flag were indistinguishable.
32 Panic,
33 /// The child stopped because a FAIL-CLOSED POLICY refused the run.
34 ///
35 /// ⚠️ A REFUSAL AND A REPORTED ERROR ARE THE SAME SHAPE HERE TOO, which is
36 /// the identical argument that justified `Panic`. Record mode sets
37 /// `exit_on_unsupported_syscall` and `shutdown_on_unsupported_syscall:
38 /// false`, so it returns a typed `UnsupportedSyscallError` through Reverie
39 /// instead of calling `unrecoverable_shutdown`. That path never produces an
40 /// exit status of its own, so the status channel -- which is what carries
41 /// `HERMIT_POLICY_REFUSAL_EXIT` on the run path -- has nothing to say, and
42 /// the refusal arrived indistinguishable from "hermit broke": exit 125,
43 /// `class=container-child-exit`. Two configurations of one policy reported
44 /// opposite things about the same decision.
45 PolicyRefusal,
46 /// A ptrace PMU timer interrupt arrived after its target. The count is
47 /// carried across the container boundary so the parent can publish the
48 /// named infrastructure error instead of leaving the pending no-result.
49 SkidOvershoot { count: u64 },
50 /// The child stopped because HERMIT'S OWN `--timeout` BOUND was reached.
51 ///
52 /// ⚠️ THE SAME ARGUMENT A THIRD TIME, and it is not hypothetical: measured
53 /// on 2026-08-26, `hermit run --timeout 3 -- ./spin` fired at exactly 3s
54 /// with no residue and still reported `exit 125` /
55 /// `class=cli-error` -- "hermit broke" -- because `GuestTimedOut` is
56 /// produced INSIDE the container child and every type is a string by the
57 /// time the parent sees it. Unlike the refusal path there is no status
58 /// channel to fall back on either: the timeout unwinds and RETURNS rather
59 /// than calling `unrecoverable_shutdown`, precisely because the unwind is
60 /// the point.
61 RunTimeout,
62 /// The backend failed while running the guest ([`crate::BackendRunFailure`]).
63 /// Carried so the parent can record the verification run as failed by its
64 /// backend instead of leaving the pending no-result stamp.
65 BackendRunFailure,
66}
67
68/// ⚠️ THE `kind` FIELD IS THE THIRD AND LAST OF ONE CHAIN OF FLATTENINGS.
69/// The same property -- the failure's CLASS -- was destroyed at three different
70/// boundaries, in series on one path:
71///
72/// 1. `main`'s `unwrap_or_else` mapped EVERY error to one exit code;
73/// 2. `with_container` flattened reverie's typed `RunError::ExitStatus` into
74/// opaque prose with `.context(..)?`;
75/// 3. THIS type crosses a process boundary carrying only strings.
76///
77/// They are three distinct boundaries with three mechanisms, but they answer one
78/// question, so one discriminant serves all three. Preserving it here is what
79/// lets the parent classify without parsing English.
80///
81/// Extending a serialized type is safe HERE specifically because the writer and
82/// the reader are the SAME BINARY IMAGE -- hermit's container child and its own
83/// parent, over a fork-local pipe -- so there is no cross-version compatibility
84/// surface.
85///
86/// ⚠️ `serde(default)` BELOW IS NOT A COMPATIBILITY GUARANTEE, and must not be
87/// read as one. reverie serializes this with `bincode::config::legacy()`
88/// (`reverie-process/src/container.rs:861`), which is NOT self-describing: a
89/// record written by an older binary with two fields would fail to decode
90/// outright rather than defaulting the third. The attribute is harmless and
91/// keeps the field optional at the Rust level; the property that actually makes
92/// this safe is the same-image one above.
93#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq)]
94pub struct SerializableError {
95 /// The main error.
96 error: String,
97 /// The chain of causes. This is empty if there are no associated causes.
98 context: Vec<String>,
99 /// What CLASS of failure this was. See [`FailureKind`].
100 #[serde(default)]
101 kind: FailureKind,
102 /// An unresolved owner is separate from the primary failure class. This
103 /// same-image container field is not a cross-version wire compatibility promise.
104 cleanup_stage: Option<crate::HermitCleanupStage>,
105}
106
107impl SerializableError {
108 /// The class this failure was reported as.
109 pub fn kind(&self) -> FailureKind {
110 self.kind
111 }
112
113 /// The unresolved owner phase, if cleanup has not actually completed.
114 pub fn cleanup_stage(&self) -> Option<crate::HermitCleanupStage> {
115 self.cleanup_stage
116 }
117
118 /// Re-tag an error as a caught panic. Called at the catch site, which is the
119 /// only place that still knows a panic is what happened.
120 pub fn into_panic(mut self) -> Self {
121 self.kind = FailureKind::Panic;
122 self
123 }
124}
125
126/// Is this error a fail-closed POLICY REFUSAL rather than something that broke?
127///
128/// ⚠️ THE CHAIN WALK ALONE DOES NOT FIND IT, AND I SHIPPED A FIX THAT ONLY DID THAT.
129/// `reverie::Error::Tool` is declared `#[error(transparent)]`, which forwards
130/// `source()` to the inner `anyhow::Error`'s source -- PAST that error's own value.
131/// `UnsupportedSyscallError` IS that value, so it never appears in
132/// `err.chain()` and `.is::<_>()` is false at every link. Reproduced in isolation:
133/// a one-entry chain whose Display is right and whose `is::<T>()` is false.
134///
135/// The consequence was that record mode still reported exit 125
136/// `class=cli-error` -- measured against `tests/c/dbt_unsupported_syscall.c`, the
137/// path this whole change exists to fix, unchanged. The in-process test passed
138/// because it constructs the error directly and never crosses the wrapper.
139/// agent(hermit-001)'s codex lane asked for the end-to-end cell that would have
140/// caught it; the cell was absent because the fix did not work.
141///
142/// ⚠️ IT IS STILL A TYPE TEST, NOT A STRING MATCH. Matching the Display text would
143/// be the thing `kind` exists to avoid, and it would break the moment the message
144/// is reworded. This reaches through the one wrapper that hides the type.
145fn is_policy_refusal(err: &Error) -> bool {
146 // Detcore's refusal of an unsupported syscall, and reverie-ptrace's end of
147 // a run in which the guest made a syscall through Reverie's untraced
148 // private-page stub, which no tool saw
149 // (https://github.com/rrnewton/reverie/issues/1064).
150 fn refuses(cause: &(dyn std::error::Error + 'static)) -> bool {
151 cause.is::<detcore::UnsupportedSyscallError>()
152 || cause.is::<reverie_ptrace::UntracedStubSyscall>()
153 }
154 if err.chain().any(refuses) {
155 return true;
156 }
157 // The wrapper case: reverie hands the tool's error back inside `Tool`, whose
158 // transparent forwarding hides the value from the chain above.
159 err.chain().any(|cause| {
160 cause
161 .downcast_ref::<reverie::Error>()
162 .is_some_and(|reverie_error| match reverie_error {
163 reverie::Error::Tool(inner) => inner.chain().any(refuses),
164 _ => false,
165 })
166 })
167}
168
169/// Classify only the backend's primary cause. Its secondary errors and failed
170/// cleanup observations are deliberately unreachable from this function.
171pub(crate) fn classify_ptrace_primary(error: &reverie::Error) -> FailureKind {
172 match error {
173 reverie::Error::Tool(inner) => classify_unwrapped(inner),
174 _ => FailureKind::Error,
175 }
176}
177
178fn classify_unwrapped(error: &Error) -> FailureKind {
179 if let Some(error) = error.downcast_ref::<crate::SkidOvershootError>() {
180 FailureKind::SkidOvershoot {
181 count: error.count(),
182 }
183 } else if is_policy_refusal(error)
184 || error
185 .downcast_ref::<crate::LiteinstInGuestRefusal>()
186 .is_some()
187 || error
188 .chain()
189 .any(|cause| cause.is::<crate::cpu_profile_admission::CpuProfileRefusal>())
190 || error
191 .chain()
192 .any(|cause| cause.is::<crate::preemption_admission::UnsupportedPreemption>())
193 {
194 FailureKind::PolicyRefusal
195 } else if error.downcast_ref::<crate::GuestTimedOut>().is_some() {
196 FailureKind::RunTimeout
197 } else if error.downcast_ref::<crate::BackendRunFailure>().is_some() {
198 FailureKind::BackendRunFailure
199 } else {
200 FailureKind::Error
201 }
202}
203
204impl From<Error> for SerializableError {
205 fn from(err: Error) -> Self {
206 let error = err.to_string();
207 let context = err.chain().skip(1).map(ToString::to_string).collect();
208 // ⚠️ CLASSIFIED HERE BECAUSE THIS IS THE LAST PLACE THE TYPE EXISTS.
209 // Everything below this line is strings: `From<SerializableError> for
210 // Error` rebuilds the chain with `Error::msg`, so a downcast on the far
211 // side can only ever fail. Detecting the refusal after the boundary
212 // would mean matching on English, which is the thing `kind` exists to
213 // avoid.
214 let (kind, cleanup_stage) =
215 if let Some(error) = err.downcast_ref::<crate::HermitCleanupUnconfirmed>() {
216 (error.primary_kind(), Some(error.stage()))
217 } else if let Some(error) = err.downcast_ref::<crate::HermitPtraceFailure>() {
218 (error.kind(), None)
219 } else {
220 (classify_unwrapped(&err), None)
221 };
222 Self {
223 error,
224 context,
225 kind,
226 cleanup_stage,
227 }
228 }
229}
230
231impl From<SerializableError> for Error {
232 fn from(mut err: SerializableError) -> Self {
233 if let Some(root_cause) = err.context.pop() {
234 let mut error = Self::msg(root_cause);
235
236 while let Some(context) = err.context.pop() {
237 error = error.context(context);
238 }
239
240 error.context(err.error)
241 } else {
242 Self::msg(err.error)
243 }
244 }
245}
246
247#[cfg(test)]
248mod tests {
249 use super::*;
250
251 #[test]
252 fn unsupported_preemption_keeps_its_policy_class_across_the_container_boundary() {
253 let refusal = crate::preemption_admission::refuse_unsupported_preemption(
254 &detcore::Config::default(),
255 crate::Backend::Dbt,
256 true,
257 false,
258 )
259 .unwrap_err();
260 let serialized = SerializableError::from(Error::new(refusal).context("launch refused"));
261 assert_eq!(serialized.kind(), FailureKind::PolicyRefusal);
262 assert!(serialized.context.iter().any(|message| {
263 message.contains("unsupported_preemption") && message.contains("--backend=dbt")
264 }));
265 }
266
267 #[test]
268 fn into_serializable_error() {
269 let error = Error::msg("root cause")
270 .context("a")
271 .context("b")
272 .context("c");
273
274 assert_eq!(
275 SerializableError::from(error),
276 SerializableError {
277 error: "c".into(),
278 context: vec!["b".into(), "a".into(), "root cause".into(),],
279 kind: FailureKind::Error,
280 cleanup_stage: None,
281 }
282 );
283 }
284
285 #[test]
286 fn from_serializable_error() {
287 let error = Error::from(SerializableError {
288 error: "c".into(),
289 context: vec!["b".into(), "a".into(), "root cause".into()],
290 kind: FailureKind::Error,
291 cleanup_stage: None,
292 });
293
294 assert_eq!(
295 error
296 .chain()
297 .map(ToString::to_string)
298 .collect::<Vec<String>>(),
299 ["c", "b", "a", "root cause"]
300 .iter()
301 .map(ToString::to_string)
302 .collect::<Vec<String>>(),
303 )
304 }
305
306 #[test]
307 fn skid_overshoot_is_serialized_as_a_policy_refusal() {
308 let refusal = SerializableError::from(Error::new(crate::SkidOvershootError::new(2)));
309 assert_eq!(refusal.kind(), FailureKind::SkidOvershoot { count: 2 });
310 assert!(refusal.error.contains("observed 2 HERMIT_SKID_OVERSHOOT"));
311
312 let contextual = SerializableError::from(
313 Error::msg("guest execution also failed").context(crate::SkidOvershootError::new(1)),
314 );
315 assert_eq!(contextual.kind(), FailureKind::SkidOvershoot { count: 1 });
316 assert!(
317 contextual
318 .error
319 .contains("observed 1 HERMIT_SKID_OVERSHOOT")
320 );
321
322 let ordinary = SerializableError::from(Error::msg("ordinary failure"));
323 assert_eq!(ordinary.kind(), FailureKind::Error);
324 }
325
326 /// The library's in-guest LiteInst refusals run inside the container, so
327 /// they reach the CLI only as this serialized form.
328 #[test]
329 fn in_guest_liteinst_refusal_is_serialized_as_a_policy_refusal() {
330 let refusal = SerializableError::from(Error::new(crate::LiteinstInGuestRefusal::new(
331 "guest program /static is statically linked",
332 )));
333 assert_eq!(refusal.kind(), FailureKind::PolicyRefusal);
334 assert_eq!(
335 refusal.error,
336 "--backend=liteinst (in-guest LiteInst) refuses this run: guest program /static is \
337 statically linked"
338 );
339 }
340
341 /// reverie-ptrace ends a run whose guest made a syscall through Reverie's
342 /// untraced private-page stub; that is a policy refusal (exit 122), not
343 /// an internal failure, both as the backend's primary cause and wrapped
344 /// (https://github.com/rrnewton/reverie/issues/1064).
345 #[test]
346 fn an_untraced_stub_syscall_is_a_policy_refusal() {
347 let refusal = || reverie_ptrace::UntracedStubSyscall {
348 tid: 7,
349 address: 0x7100_0002,
350 };
351 let primary = reverie::Error::Tool(Error::new(refusal()));
352 assert_eq!(
353 classify_ptrace_primary(&primary),
354 FailureKind::PolicyRefusal
355 );
356 let wrapped = Error::new(reverie::Error::Tool(Error::new(refusal())))
357 .context("the ptrace backend failed");
358 assert_eq!(classify_unwrapped(&wrapped), FailureKind::PolicyRefusal);
359 let serialized = SerializableError::from(Error::new(refusal()));
360 assert_eq!(serialized.kind(), FailureKind::PolicyRefusal);
361 assert!(
362 serialized.error.contains("0x71000002"),
363 "{}",
364 serialized.error
365 );
366 }
367
368 /// An in-guest-trap refusal names that backend and keeps the same class.
369 #[test]
370 fn in_guest_trap_refusal_is_serialized_as_a_policy_refusal() {
371 let refusal =
372 SerializableError::from(Error::new(crate::LiteinstInGuestRefusal::for_backend(
373 crate::Backend::InGuestTrap,
374 "guest program /static is statically linked",
375 )));
376 assert_eq!(refusal.kind(), FailureKind::PolicyRefusal);
377 assert_eq!(
378 refusal.error,
379 "--backend=in-guest-trap (in-guest LiteInst, site patching off) refuses this run: \
380 guest program /static is statically linked"
381 );
382 }
383}