Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.4 KB
Raw Blame
//! JavaScript-facing exports. Everything here is a thin shell around `error` and `pool`.
//!
//! Rules every export follows:
//! - the body runs inside `guard`, so a panic is a JavaScript `Error` with code `internal_error`
//!   and the process keeps running;
//! - async work runs on the Rust worker pool and settles a promise, so the Bun event loop is
//!   never blocked;
//! - errors are real `Error` objects with a stable `code` (and, for `cancelled`, the number of
//!   `completedSteps`), never a bare message.

use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use std::sync::{Arc, Mutex};
use std::time::Duration;

use napi::bindgen_prelude::{
    Float32Array, FromNapiValue, Function, Object, ToNapiValue, TypeName, ValidateNapiValue,
};
use napi::threadsafe_function::ThreadsafeFunctionCallMode;
use napi::{Env, JsDeferred, JsValue, Status, ValueType, sys};
use napi_derive::napi;

use crate::error::{Detail, TaskError, guard};
use crate::pool::{self, CancelToken as Token, Task};

type TaskResult<T> = std::result::Result<T, TaskError>;

/// Build the JavaScript `Error` for a typed error: `message`, a stable `code`, and its details.
fn js_error(env: &Env, error: TaskError) -> napi::Error {
    let build = || -> napi::Result<napi::Error> {
        let mut object = env.create_error(napi::Error::new(
            Status::GenericFailure,
            error.message.clone(),
        ))?;
        object.set("code", error.code)?;
        for (key, detail) in &error.details {
            match detail {
                Detail::Count(n) => object.set(*key, *n)?,
                Detail::Flag(flag) => object.set(*key, *flag)?,
                Detail::Text(text) => object.set(*key, text.as_str())?,
            }
        }
        Ok(napi::Error::from(object.to_unknown()))
    };
    build().unwrap_or_else(|_| {
        napi::Error::new(
            Status::GenericFailure,
            format!("{}: {}", error.code, error.message),
        )
    })
}

/// Run a synchronous export: panic to `internal_error`, typed error to a thrown `Error`.
fn sync_call<T>(env: &Env, work: impl FnOnce() -> TaskResult<T>) -> napi::Result<T> {
    guard(work).map_err(|error| js_error(env, error))
}

#[napi(module_exports)]
pub fn module_exports(mut exports: Object, env: Env) -> napi::Result<()> {
    // Plain data properties, so the loader reads them without calling anything.
    exports.set("target", crate::target())?;
    exports.set("engineAbi", crate::ENGINE_ABI)?;
    exports.set("engineBuild", crate::ENGINE_BUILD)?;
    exports.set("catalogVersion", crate::CATALOG_VERSION)?;
    exports.set("formatVersions", env.create_array(0)?)?;
    exports.set("sinkMaxQueueSize", SINK_QUEUE_SIZE as u32)?;
    Ok(())
}

// ---------------------------------------------------------------------------------------------
// Typed arrays
// ---------------------------------------------------------------------------------------------

/// Adds in `f64`, starting from +0.0. (`Iterator::sum` on floats starts from -0.0, which would
/// turn an empty array into `-0` in JavaScript.)
fn sum_as_f64(values: impl IntoIterator<Item = f32>) -> f64 {
    values
        .into_iter()
        .fold(0.0, |total, v| total + f64::from(v))
}

/// A `Float32Array` argument. A view of a `SharedArrayBuffer` is refused with the same
/// `InvalidArg` error as an argument of the wrong type, because another Worker could write it
/// during the call.
///
/// That refusal is the safety argument. It asks the runtime (`napi_is_arraybuffer` on the view's
/// buffer), which reads the engine's own record of the buffer, so no JavaScript state (a replaced
/// global constructor, a swapped prototype) can change the answer, and an unclear answer is
/// treated as shared. Rust never makes a `&[f32]` or `&mut [f32]` over the caller's memory: every
/// read and write goes through `AtomicU32` cells with relaxed ordering (see [`PlainF32::cells`]),
/// which compile to plain loads and stores. Atomics do not make shared memory safe (another Worker
/// may write it with accesses of a different size), which is why shared memory is refused.
pub struct PlainF32 {
    /// Keeps the JavaScript array alive for the call.
    _array: Float32Array,
    /// First element (the view's byte offset already applied) and element count, as Node-API
    /// reported them. Null or zero for an empty array.
    data: *mut f32,
    length: usize,
}

impl PlainF32 {
    /// The caller's elements as atomic cells.
    fn cells(&self) -> &[AtomicU32] {
        if self.data.is_null() || self.length == 0 {
            return &[];
        }
        // SAFETY: `data` points at `length` elements of 4 bytes that stay allocated while
        // `_array` is held (this struct only lives for one call on the JavaScript thread).
        // `AtomicU32` has the size and alignment of `u32`, and the pointer is 4-aligned (checked
        // in `from_napi_value`). The buffer is a plain ArrayBuffer (`backed_by_shared_memory`),
        // so only this thread, blocked in the call, can reach it.
        unsafe { std::slice::from_raw_parts(self.data.cast::<AtomicU32>(), self.length) }
    }

    /// Reads every element.
    fn values(&self) -> impl Iterator<Item = f32> + '_ {
        self.cells()
            .iter()
            .map(|cell| f32::from_bits(cell.load(Ordering::Relaxed)))
    }

    /// A Rust-owned copy, for work that outlives the call.
    fn to_vec(&self) -> Vec<f32> {
        self.values().collect()
    }
}

impl TypeName for PlainF32 {
    fn type_name() -> &'static str {
        "Float32Array"
    }

    fn value_type() -> ValueType {
        ValueType::Object
    }
}

impl ValidateNapiValue for PlainF32 {}

impl FromNapiValue for PlainF32 {
    unsafe fn from_napi_value(env: sys::napi_env, value: sys::napi_value) -> napi::Result<Self> {
        // SAFETY: `env` and `value` come straight from Node-API for this call.
        if unsafe { backed_by_shared_memory(env, value) } {
            return Err(napi::Error::new(
                Status::InvalidArg,
                "a Float32Array over a SharedArrayBuffer is not accepted; copy it into a plain Float32Array first",
            ));
        }
        // SAFETY: as above.
        let array = unsafe { Float32Array::from_napi_value(env, value) }?;
        let mut kind = 0;
        let mut length = 0;
        let mut data = std::ptr::null_mut();
        let mut buffer = std::ptr::null_mut();
        let mut offset = 0;
        // SAFETY: every out pointer is a valid local; `value` is a Float32Array (checked above).
        let status = unsafe {
            sys::napi_get_typedarray_info(
                env,
                value,
                &mut kind,
                &mut length,
                &mut data,
                &mut buffer,
                &mut offset,
            )
        };
        let data = data.cast::<f32>();
        if status != sys::Status::napi_ok || (!data.is_null() && !data.is_aligned()) {
            return Err(napi::Error::new(
                Status::InvalidArg,
                "the Float32Array's memory could not be read safely",
            ));
        }
        Ok(Self {
            _array: array,
            data,
            length,
        })
    }
}

/// True when `value` is a typed array over memory that may be shared, or when that cannot be
/// told. Only the runtime's `napi_is_arraybuffer` answer counts: a buffer it does not call a plain
/// ArrayBuffer is treated as shared. A value that is not a typed array returns false, so the
/// `Float32Array` conversion reports its own wrong-type error.
///
/// # Safety
/// `env` and `value` must be live handles of the current Node-API call.
unsafe fn backed_by_shared_memory(env: sys::napi_env, value: sys::napi_value) -> bool {
    let ok = sys::Status::napi_ok;
    let mut kind = 0;
    let mut length = 0;
    let mut data = std::ptr::null_mut();
    let mut buffer = std::ptr::null_mut();
    let mut offset = 0;
    // SAFETY: every out pointer is a valid local.
    let status = unsafe {
        sys::napi_get_typedarray_info(
            env,
            value,
            &mut kind,
            &mut length,
            &mut data,
            &mut buffer,
            &mut offset,
        )
    };
    if status != ok {
        return false;
    }
    if buffer.is_null() {
        return true;
    }
    let mut plain = false;
    // SAFETY: `buffer` is the live handle the call above returned.
    let status = unsafe { sys::napi_is_arraybuffer(env, buffer, &mut plain) };
    status != ok || !plain
}

/// Sum of a `Float32Array`, added in `f64`. Reads the JavaScript memory in place for the length
/// of the call (a view with a byte offset is honoured); nothing is copied and nothing is kept.
#[napi]
pub fn sum_f32(env: &Env, values: PlainF32) -> napi::Result<f64> {
    sync_call(env, || Ok(sum_as_f64(values.values())))
}

/// A new `Float32Array` with every value multiplied by `factor`. The input is left alone and the
/// result is a separate array.
#[napi]
pub fn scale_f32(env: &Env, values: PlainF32, factor: f64) -> napi::Result<Float32Array> {
    sync_call(env, || {
        let scaled: Vec<f32> = values
            .values()
            .map(|v| (f64::from(v) * factor) as f32)
            .collect();
        Ok(Float32Array::new(scaled))
    })
}

/// Multiplies every value of the caller's array by `factor`, writing into the same memory.
/// Synchronous only: the JavaScript thread is blocked for the whole call, so nothing else can
/// touch the array while it is written.
#[napi]
pub fn scale_in_place_f32(env: &Env, values: PlainF32, factor: f64) -> napi::Result<u32> {
    sync_call(env, || {
        let cells = values.cells();
        for cell in cells {
            let v = f32::from_bits(cell.load(Ordering::Relaxed));
            cell.store(
                ((f64::from(v) * factor) as f32).to_bits(),
                Ordering::Relaxed,
            );
        }
        Ok(cells.len() as u32)
    })
}

// ---------------------------------------------------------------------------------------------
// Panics
// ---------------------------------------------------------------------------------------------

/// Panics on purpose, to prove a synchronous panic becomes a JavaScript error.
#[napi]
pub fn probe_panic_sync(env: &Env) -> napi::Result<()> {
    sync_call(env, || -> TaskResult<()> {
        panic!("probe_panic_sync panicked on purpose")
    })
}

// ---------------------------------------------------------------------------------------------
// Cancellation token
// ---------------------------------------------------------------------------------------------

/// What a JavaScript `AbortSignal` is mapped to: `signal.addEventListener('abort', () => token.cancel())`.
#[napi]
pub struct CancelToken {
    flag: Token,
}

#[napi]
impl CancelToken {
    #[napi(constructor)]
    pub fn new() -> Self {
        Self { flag: Token::new() }
    }

    #[napi]
    pub fn cancel(&self) {
        self.flag.cancel();
    }

    #[napi(getter)]
    pub fn cancelled(&self) -> bool {
        self.flag.is_cancelled()
    }
}

// ---------------------------------------------------------------------------------------------
// The worker pool
// ---------------------------------------------------------------------------------------------

type Resolver<T> = Box<dyn FnOnce(Env) -> napi::Result<T> + Send>;
type Work<T> = Box<dyn FnOnce() -> TaskResult<T> + Send>;

/// A pool task that settles a JavaScript promise: resolved with the work's value, or rejected
/// with a typed `Error`.
struct PromiseTask<T: ToNapiValue + Send + 'static> {
    deferred: JsDeferred<T, Resolver<T>>,
    work: Work<T>,
}

impl<T: ToNapiValue + Send + 'static> Task for PromiseTask<T> {
    fn run(self: Box<Self>) {
        let PromiseTask { deferred, work } = *self;
        let outcome = guard(work);
        settle(deferred, outcome);
    }

    fn cancel(self: Box<Self>, error: TaskError) {
        settle(self.deferred, Err(error));
    }
}

fn settle<T: ToNapiValue + Send + 'static>(
    deferred: JsDeferred<T, Resolver<T>>,
    outcome: TaskResult<T>,
) {
    // The error object is built on the JavaScript thread, where Node-API may be called.
    deferred.resolve(Box::new(move |env| {
        outcome.map_err(|error| js_error(&env, error))
    }));
}

/// Start `work` on the pool and return its promise. A pool that no longer takes work returns a
/// promise already rejected with `engine_shutdown`.
fn spawn<'env, T: ToNapiValue + Send + 'static>(
    env: &'env Env,
    pool: &pool::Pool,
    work: impl FnOnce() -> TaskResult<T> + Send + 'static,
) -> napi::Result<Object<'env>> {
    let (deferred, promise) = env.create_deferred::<T, Resolver<T>>()?;
    let task = Box::new(PromiseTask {
        deferred,
        work: Box::new(work) as Work<T>,
    });
    if let Err(refused) = pool.submit(task) {
        refused.cancel(TaskError::shutdown());
    }
    Ok(promise)
}

/// Worker threads still running across every pool in this process. A pool that is shut down,
/// or whose object was collected, stops counting once its threads exit.
#[napi]
pub fn live_workers() -> u32 {
    pool::live_workers()
}

/// What `shutdown` reports.
#[napi(object)]
pub struct ShutdownReport {
    /// Tasks that were queued and never started; each was rejected with `cancelled`.
    pub cancelled_queued: u32,
    /// Tasks that were running when shutdown began and finished inside the wait.
    pub finished_running: u32,
    /// Tasks still running when the wait ended; they finish on their own later.
    pub abandoned_running: u32,
}

/// A pool of Rust worker threads. Its calls return promises; the JavaScript thread only queues
/// work and settles results.
#[napi]
pub struct Pool {
    pool: pool::Pool,
}

#[napi]
impl Pool {
    /// Starts `workers` threads: at least 1, at most 256. If a thread cannot start, throws
    /// `internal_error` and stops the threads that did start.
    #[napi(constructor)]
    pub fn new(env: &Env, workers: u32) -> napi::Result<Self> {
        sync_call(env, || pool::Pool::new(workers as usize)).map(|pool| Self { pool })
    }

    /// Worker threads still running their loop.
    #[napi(getter)]
    pub fn workers(&self) -> u32 {
        self.pool.workers()
    }

    /// `running`, `shutting_down` or `closed`.
    #[napi(getter)]
    pub fn state(&self) -> String {
        self.pool.phase().as_str().to_owned()
    }

    #[napi(getter)]
    pub fn queued(&self) -> u32 {
        self.pool.queued()
    }

    #[napi(getter)]
    pub fn running(&self) -> u32 {
        self.pool.running()
    }

    /// Holds a worker for `ms` milliseconds, then resolves with `ms`. The event loop stays free.
    #[napi]
    pub fn block_for<'env>(&self, env: &'env Env, ms: u32) -> napi::Result<Object<'env>> {
        spawn(env, &self.pool, move || {
            std::thread::sleep(Duration::from_millis(u64::from(ms)));
            Ok(ms)
        })
    }

    /// `steps` steps of `step_ms` each. Resolves with the steps done. If `cancel` is cancelled
    /// after the task started, rejects with `cancelled` and `completedSteps`.
    #[napi]
    pub fn run_steps<'env>(
        &self,
        env: &'env Env,
        steps: u32,
        step_ms: u32,
        cancel: Option<&CancelToken>,
    ) -> napi::Result<Object<'env>> {
        let cancel = cancel.map(|t| t.flag.clone());
        spawn(env, &self.pool, move || {
            pool::run_steps(
                steps,
                Duration::from_millis(u64::from(step_ms)),
                cancel.as_ref(),
            )
        })
    }

    /// Async sum. The values are copied before the call returns, because the JavaScript array
    /// may change or be freed while a worker runs.
    #[napi]
    pub fn sum_f32<'env>(&self, env: &'env Env, values: PlainF32) -> napi::Result<Object<'env>> {
        let copy: Vec<f32> = values.to_vec();
        spawn(env, &self.pool, move || Ok(sum_as_f64(copy)))
    }

    /// Async scale. The result is a new `Float32Array` made on the JavaScript thread.
    #[napi]
    pub fn scale_f32<'env>(
        &self,
        env: &'env Env,
        values: PlainF32,
        factor: f64,
    ) -> napi::Result<Object<'env>> {
        let copy: Vec<f32> = values.to_vec();
        spawn(env, &self.pool, move || {
            Ok(Float32Array::new(
                copy.iter()
                    .map(|v| (f64::from(*v) * factor) as f32)
                    .collect(),
            ))
        })
    }

    /// Panics on a worker, to prove an async panic becomes a rejected promise and the pool lives on.
    #[napi]
    pub fn probe_panic<'env>(&self, env: &'env Env) -> napi::Result<Object<'env>> {
        spawn(env, &self.pool, || -> TaskResult<u32> {
            panic!("probe_panic panicked on purpose")
        })
    }

    /// Stop admission, cancel queued tasks, wait up to `wait_ms` for running ones, then close.
    /// Admission closes before this returns: any call made after it, even while the returned
    /// promise is pending, rejects with `engine_shutdown`.
    #[napi]
    pub fn shutdown<'env>(&self, env: &'env Env, wait_ms: u32) -> napi::Result<Object<'env>> {
        let (deferred, promise) =
            env.create_deferred::<ShutdownReport, Resolver<ShutdownReport>>()?;
        let draining = self.pool.begin_shutdown();
        let wait = Duration::from_millis(u64::from(wait_ms));
        // The thread takes the work out of this slot. If the thread cannot start, the slot still
        // holds it here, so no queued task or promise is left unsettled.
        let slot = Arc::new(Mutex::new(Some((draining, deferred))));
        let thread_slot = Arc::clone(&slot);
        // The wait blocks, so it runs on its own thread, not the JavaScript thread or a worker.
        let spawned = std::thread::Builder::new()
            .name("gbrain-shutdown".into())
            .spawn(move || {
                if let Some((draining, deferred)) = take(&thread_slot) {
                    settle_shutdown(deferred, draining.finish(wait));
                }
            });
        if spawned.is_err()
            && let Some((draining, deferred)) = take(&slot)
        {
            draining.finish(Duration::ZERO);
            let error = TaskError::internal();
            deferred.resolve(Box::new(move |env| Err(js_error(&env, error))));
        }
        Ok(promise)
    }
}

/// A pool whose JavaScript object is collected without `shutdown` closes at once, so its idle
/// workers exit instead of waiting forever. Queued tasks are cancelled; running ones finish.
impl Drop for Pool {
    fn drop(&mut self) {
        self.pool.close_now();
    }
}

type PendingShutdown = (
    pool::Draining,
    JsDeferred<ShutdownReport, Resolver<ShutdownReport>>,
);

fn take(slot: &Mutex<Option<PendingShutdown>>) -> Option<PendingShutdown> {
    slot.lock()
        .unwrap_or_else(|poisoned| poisoned.into_inner())
        .take()
}

fn settle_shutdown(
    deferred: JsDeferred<ShutdownReport, Resolver<ShutdownReport>>,
    report: pool::ShutdownReport,
) {
    deferred.resolve(Box::new(move |_| {
        Ok(ShutdownReport {
            cancelled_queued: report.cancelled_queued,
            finished_running: report.finished_running,
            abandoned_running: report.abandoned_running,
        })
    }));
}

// ---------------------------------------------------------------------------------------------
// Threadsafe-function queue
// ---------------------------------------------------------------------------------------------

/// The bounded queue size of a [`Sink`]. A const generic in napi-rs, so one fixed value.
const SINK_QUEUE_SIZE: usize = 4;

type SinkFunction = napi::threadsafe_function::ThreadsafeFunction<
    u32,
    (),
    u32,
    Status,
    false,
    true,
    SINK_QUEUE_SIZE,
>;

/// A JavaScript callback fed through a bounded threadsafe-function queue. `emit` never blocks and
/// says what the queue did with the value: `ok`, `queue_full` or `closing`.
///
/// `queue_full` comes from the runtime (Bun) itself. `closing` is reported by this crate from its
/// own closed flag after `close()`; the underlying function is released when the Sink is dropped.
#[napi]
pub struct Sink {
    function: Arc<SinkFunction>,
    closed: Arc<AtomicBool>,
}

fn status_name(status: Status) -> &'static str {
    match status {
        Status::Ok => "ok",
        Status::QueueFull => "queue_full",
        Status::Closing => "closing",
        _ => "error",
    }
}

#[napi]
impl Sink {
    #[napi(constructor)]
    pub fn new(callback: Function<'_, u32, ()>) -> napi::Result<Self> {
        let function = callback
            .build_threadsafe_function::<u32>()
            .callee_handled::<false>()
            .weak::<true>()
            .max_queue_size::<SINK_QUEUE_SIZE>()
            .build()?;
        Ok(Self {
            function: Arc::new(function),
            closed: Arc::new(AtomicBool::new(false)),
        })
    }

    /// Queue `value` for the callback without blocking.
    #[napi]
    pub fn emit(&self, value: u32) -> String {
        let status = guard(|| {
            Ok(if self.closed.load(Ordering::SeqCst) {
                Status::Closing
            } else {
                self.function
                    .call(value, ThreadsafeFunctionCallMode::NonBlocking)
            })
        });
        status.map_or("error", status_name).to_owned()
    }

    /// Emit `count` values from a Rust thread instead of the JavaScript thread; resolves with
    /// the status of each.
    #[napi]
    pub fn emit_from_thread<'env>(&self, env: &'env Env, count: u32) -> napi::Result<Object<'env>> {
        let (deferred, promise) = env.create_deferred::<Vec<String>, Resolver<Vec<String>>>()?;
        let function = Arc::clone(&self.function);
        let closed = Arc::clone(&self.closed);
        let spawned = std::thread::Builder::new()
            .name("gbrain-sink-emit".into())
            .spawn(move || {
                let statuses: Vec<String> = (0..count)
                    .map(|n| {
                        if closed.load(Ordering::SeqCst) {
                            Status::Closing
                        } else {
                            function.call(n, ThreadsafeFunctionCallMode::NonBlocking)
                        }
                    })
                    .map(|status| status_name(status).to_owned())
                    .collect();
                deferred.resolve(Box::new(move |_| Ok(statuses)));
            });
        if spawned.is_err() {
            return Err(js_error(env, TaskError::internal()));
        }
        Ok(promise)
    }

    /// Mark the sink closed: later `emit` calls return `closing`. Values already queued are still delivered.
    #[napi]
    pub fn close(&self) -> napi::Result<()> {
        self.closed.store(true, Ordering::SeqCst);
        Ok(())
    }
}