Skip to main content

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}