Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
//! Typed errors for the binding.
//!
//! Every error that reaches JavaScript carries a stable `code` string, never just a message.
//! This file holds no JavaScript types, so the rules here are covered by plain `cargo test`.

use std::any::Any;
use std::panic::{AssertUnwindSafe, catch_unwind};
use std::sync::atomic::{AtomicU64, Ordering};

/// The caller asked for the task to stop and it did.
pub const CANCELLED: &str = "cancelled";
/// A Rust panic or an unexpected failure inside the engine. The process keeps running.
pub const INTERNAL_ERROR: &str = "internal_error";
/// The pool is shutting down or closed and takes no new work.
pub const ENGINE_SHUTDOWN: &str = "engine_shutdown";

/// Extra data an error can carry next to its code, readable as a property in JavaScript.
#[derive(Debug, Clone, PartialEq)]
pub enum Detail {
    Count(u32),
    Flag(bool),
    Text(String),
}

#[derive(Debug, Clone, PartialEq)]
pub struct TaskError {
    pub code: &'static str,
    pub message: String,
    pub details: Vec<(&'static str, Detail)>,
}

static DIAGNOSTIC: AtomicU64 = AtomicU64::new(1);

impl TaskError {
    pub fn new(code: &'static str, message: impl Into<String>) -> Self {
        Self {
            code,
            message: message.into(),
            details: Vec::new(),
        }
    }

    pub fn with(mut self, key: &'static str, detail: Detail) -> Self {
        self.details.push((key, detail));
        self
    }

    pub fn cancelled(completed_steps: u32, started: bool) -> Self {
        Self::new(CANCELLED, "the task was cancelled")
            .with("completedSteps", Detail::Count(completed_steps))
            .with("started", Detail::Flag(started))
    }

    pub fn shutdown() -> Self {
        Self::new(
            ENGINE_SHUTDOWN,
            "the engine is shut down and accepts no new work",
        )
    }

    /// The panic text goes to stderr through the panic hook, not into the error: a panic message
    /// can name paths or values the caller must not see. The diagnostic id ties the two together.
    pub fn internal() -> Self {
        let id = format!(
            "gbrain-{}-{}",
            std::process::id(),
            DIAGNOSTIC.fetch_add(1, Ordering::Relaxed)
        );
        Self::new(
            INTERNAL_ERROR,
            "the Rust engine hit an internal error; the process is still running",
        )
        .with("diagnosticId", Detail::Text(id))
    }
}

/// Run `work` and turn a panic into an `internal_error`. Every exported function and every task
/// on the worker pool goes through this, because a panic that unwinds into the Node-API
/// boundary ends the process.
pub fn guard<T>(work: impl FnOnce() -> Result<T, TaskError>) -> Result<T, TaskError> {
    match catch_unwind(AssertUnwindSafe(work)) {
        Ok(result) => result,
        Err(payload) => {
            drop_payload(payload);
            Err(TaskError::internal())
        }
    }
}

fn drop_payload(payload: Box<dyn Any + Send>) {
    // A payload's own destructor may panic; that must not escape either.
    let _ = catch_unwind(AssertUnwindSafe(move || drop(payload)));
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_panic_becomes_internal_error_with_a_diagnostic_id() {
        let result: Result<(), TaskError> = guard(|| panic!("boom with /home/someone/secret"));
        let error = result.expect_err("a panic is an error");
        assert_eq!(error.code, INTERNAL_ERROR);
        assert!(
            !error.message.contains("secret"),
            "the panic text must not leak"
        );
        assert!(
            error
                .details
                .iter()
                .any(|(key, detail)| *key == "diagnosticId"
                    && matches!(detail, Detail::Text(id) if id.starts_with("gbrain-")))
        );
    }

    #[test]
    fn a_normal_result_and_a_typed_error_pass_through() {
        assert_eq!(guard(|| Ok::<_, TaskError>(7)), Ok(7));
        let error = guard::<()>(|| Err(TaskError::shutdown())).unwrap_err();
        assert_eq!(error.code, ENGINE_SHUTDOWN);
    }

    #[test]
    fn diagnostic_ids_are_unique() {
        let first = TaskError::internal();
        let second = TaskError::internal();
        assert_ne!(first.details, second.details);
    }
}