Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): stop the Node runtime leaking a libuv handle per future poll (#5691)
injaneityf49571cf3f96
diff --git a/libs/cua-driver/scripts/build-node-runtime.mjs b/libs/cua-driver/scripts/build-node-runtime.mjsindex 30e5dca82b..cd92dc151d 100644--- a/libs/cua-driver/scripts/build-node-runtime.mjs+++ b/libs/cua-driver/scripts/build-node-runtime.mjs@@ -9,6 +9,16 @@* this compatibility build keeps the same values and ownership while using* JavaScript-owned Uint8Arrays at the N-API boundary.*+ * UBRN 0.31.0-3 also builds a new callback trampoline, with its own+ * ThreadsafeFunction and libuv async handle, every time a JS function is passed+ * as a callback argument. The async poll loop passes its continuation callback+ * on every poll, so each await leaked one, and the host's event loop slowed as+ * it walked every leaked handle on each wakeup. UBRN fixed this in 0.31.0-4+ * (#440) by caching one trampoline per callback name and JS function. That+ * release also changes the RustBuffer boundary patched below, so this build+ * backports only the cache: node-runtime-trampoline-cache.rs is UBRN's+ * callback/cache.rs from that change, unmodified.+ ** The patched source remains MPL-2.0 and comes from the exact, pinned* uniffi-bindgen-react-native development dependency.*/@@ -144,6 +154,88 @@ function patchCall(source) {return `${source.slice(0, bodyStart)}${replacement}${source.slice(bodyEnd + bodyEndNeedle.length)}`}+function patchCallbackModule(source) {+ return replaceOnce(+ source,+ "pub(crate) mod vtable;",+ "pub(crate) mod vtable;\npub(crate) mod cache;",+ "callback module list",+ )+}++function patchRegisterTrampolines(source) {+ source = replaceOnce(+ source,+ " let capacity_symbol = Arc::new(unsafe { CapacitySymbol::new(env.raw())? });",+ ` let capacity_symbol = Arc::new(unsafe { CapacitySymbol::new(env.raw())? });+ // One cached trampoline per (callback name, JS function) for this registration.+ let trampolines = Arc::new(unsafe {+ crate::callback::cache::TrampolineCache::new(env.raw(), module.spec_callbacks().keys())?+ });`,+ "registration capacity Symbol",+ )+ source = replaceOnce(+ source,+ " let cap_sym_for_call = Arc::clone(&capacity_symbol);",+ " let cap_sym_for_call = Arc::clone(&capacity_symbol);\n let trampolines_for_call = Arc::clone(&trampolines);",+ "call closure captures",+ )+ return replaceOnce(+ source,+ " &cap_sym_for_call,\n",+ " &cap_sym_for_call,\n &trampolines_for_call,\n",+ "call dispatch arguments",+ )+}++function patchCallTrampolines(source) {+ source = replaceOnce(+ source,+ " has_rust_call_status: bool,\n capacity_symbol: &CapacitySymbol,\n) -> Result<JsUnknown> {",+ " has_rust_call_status: bool,\n capacity_symbol: &CapacitySymbol,\n trampolines: &callback::cache::TrampolineCache,\n) -> Result<JsUnknown> {",+ "call dispatch signature",+ )+ return replaceOnce(+ source,+ ` let js_fn = unsafe { napi::JsFunction::from_raw(env.raw(), js_val.raw())? };+ let user_data = callback::create_callback_user_data(env, js_fn, cb_name, module)?;+ let fn_ptr = module+ .make_callback_trampoline(+ cb_name,+ callback::on_js_thread,+ callback::dispatch_to_js_thread,+ callback::is_js_thread,+ user_data,+ )+ .map_err(core_err)?;+ slot::write_pointer(slot, fn_ptr);`,+ ` // Trampolines are never freed, so build at most one per JS function.+ let raw_fn_val = unsafe { js_val.raw() };+ let cached = unsafe { trampolines.get(env.raw(), raw_fn_val, cb_name)? };+ let fn_ptr = match cached {+ Some(fn_ptr) => fn_ptr,+ None => {+ let js_fn = unsafe { napi::JsFunction::from_raw(env.raw(), raw_fn_val)? };+ let user_data =+ callback::create_callback_user_data(env, js_fn, cb_name, module)?;+ let fn_ptr = module+ .make_callback_trampoline(+ cb_name,+ callback::on_js_thread,+ callback::dispatch_to_js_thread,+ callback::is_js_thread,+ user_data,+ )+ .map_err(core_err)?;+ unsafe { trampolines.set(env.raw(), raw_fn_val, cb_name, fn_ptr)? };+ fn_ptr+ }+ };+ slot::write_pointer(slot, fn_ptr);`,+ "callback argument dispatch",+ )+}+const temporaryRoot = mkdtempSync(join(tmpdir(), "cua-driver-node-runtime-"))try {const runtimeRoot = join(temporaryRoot, "runtime")@@ -156,7 +248,14 @@ try {const registerPath = join(runtimeRoot, "napi", "src", "register", "mod.rs")writeFileSync(registerPath, patchRegister(readFileSync(registerPath, "utf8")))const callPath = join(runtimeRoot, "napi", "src", "call", "mod.rs")- writeFileSync(callPath, patchCall(readFileSync(callPath, "utf8")))+ writeFileSync(callPath, patchCallTrampolines(patchCall(readFileSync(callPath, "utf8"))))+ writeFileSync(registerPath, patchRegisterTrampolines(readFileSync(registerPath, "utf8")))+ const callbackPath = join(runtimeRoot, "napi", "src", "callback", "mod.rs")+ writeFileSync(callbackPath, patchCallbackModule(readFileSync(callbackPath, "utf8")))+ copyFileSync(+ join(scriptDirectory, "node-runtime-trampoline-cache.rs"),+ join(runtimeRoot, "napi", "src", "callback", "cache.rs"),+ )const args = ["build", "--release", "--manifest-path", join(runtimeRoot, "napi", "Cargo.toml")]if (target) args.push("--target", target)diff --git a/libs/cua-driver/scripts/node-runtime-NOTICE.md b/libs/cua-driver/scripts/node-runtime-NOTICE.mdindex f84f0e9772..b98812435b 100644--- a/libs/cua-driver/scripts/node-runtime-NOTICE.md+++ b/libs/cua-driver/scripts/node-runtime-NOTICE.md@@ -5,8 +5,11 @@ runtime in `uniffi-bindgen-react-native` 0.31.0-3, copyright its contributorsand licensed under the Mozilla Public License 2.0.The corresponding source is the pinned npm development dependency plus the-deterministic transformations in `scripts/build-node-runtime.mjs`. The source-and build script are available in the Cua repository at the release tag that-matches this package.+deterministic transformations in `scripts/build-node-runtime.mjs`. Those+transformations add `scripts/node-runtime-trampoline-cache.rs`, which is+`runtimes/napi/src/callback/cache.rs` from `uniffi-bindgen-react-native` commit+5d24b38 (jhugman/uniffi-bindgen-react-native#440, released in 0.31.0-4),+unmodified and under the same license. The source and build script are+available in the Cua repository at the release tag that matches this package.<https://www.mozilla.org/MPL/2.0/>diff --git a/libs/cua-driver/scripts/node-runtime-trampoline-cache.rs b/libs/cua-driver/scripts/node-runtime-trampoline-cache.rsnew file mode 100644index 0000000000..6fcf32b983--- /dev/null+++ b/libs/cua-driver/scripts/node-runtime-trampoline-cache.rs@@ -0,0 +1,227 @@+/*+ * This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/+ */+//! Trampoline cache: one libffi trampoline per (callback name, JS function).+//!+//! Building a trampoline for a callback argument is expensive and **permanently+//! leaked**, by design: the library may invoke the function pointer from any thread+//! at any later time, so nothing can safely reclaim it. Each one costs+//!+//! - a strong `napi_ref` pinning the JS function,+//! - a leaked `CallbackUserData` (arg layout, cloned type descriptors, `Arc<Module>`),+//! - a fresh JS function plus a fresh `ThreadsafeFunction` (a libuv async handle),+//! and an entry appended to the env's TSFN registry,+//! - a leaked `TrampolineUserdata`, and+//! - a libffi `Closure`, which owns an executable page.+//!+//! Dispatch used to build one on *every* call that passed a callback, so the cost+//! became a ~3 KB per-call leak. That is reached from ordinary generated code: the+//! async poll loop passes its continuation callback on every poll, so every `await`+//! leaked ~3.2 KB regardless of argument types.+//!+//! Caching removes the per-call part without changing any lifetime: trampolines are+//! still never freed, there is just one per distinct (callback name, function) pair+//! instead of one per call. The async continuation is a module-level `const`, so it+//! is built once and reused for the life of the registration.+//!+//! The cached pointer lives on the JS function object under a hidden per-callback+//! Symbol, mirroring how [`crate::napi_utils::CapacitySymbol`] records RustBuffer+//! ownership on a view. Keying on the function object is what makes reuse safe:+//!+//! - The Symbols belong to one `register()` call, hence one `napi_env`, and a JS+//! function object cannot cross realms. So a cached trampoline is never handed to+//! a different env than the `raw_env`/`owner_thread` its userdata captured.+//! - A trampoline carries no per-call state. Callbacks receive their handle as an+//! ordinary argument, so reusing one across calls cannot mix up call state.+//!+//! A caller that passes a freshly created closure on every call gets no benefit and+//! behaves exactly as before — there is nothing stable to key on.++use std::collections::HashMap;+use std::ffi::c_void;++/// Per-registration hidden Symbols keyed by callback name, used to stash a built+/// trampoline pointer on the JS function it was built for.+pub struct TrampolineCache {+ /// One `napi_ref`'d Symbol per callback name in the module spec. Symbols are+ /// GC-managed; the strong reference keeps them alive for as long as the JS-side+ /// module facade, which is what makes the cache last as long as the registration.+ symbols: HashMap<String, napi::sys::napi_ref>,+ /// Captured so `Drop` releases each reference against the env that owns it.+ raw_env: napi::sys::napi_env,+}++// SAFETY: mirrors `CapacitySymbol`. These raw handles are only ever dereferenced on+// the JS thread that created them; `Send`/`Sync` is required because the cache is+// parked in an `Arc` captured by closures that napi-rs requires to be `Send`.+unsafe impl Send for TrampolineCache {}+unsafe impl Sync for TrampolineCache {}++impl TrampolineCache {+ /// Create one Symbol per callback name.+ ///+ /// # Safety+ ///+ /// `raw_env` must be a valid `napi_env` for the current callback scope.+ pub unsafe fn new<'a>(+ raw_env: napi::sys::napi_env,+ names: impl Iterator<Item = &'a String>,+ ) -> napi::Result<Self> {+ let mut symbols = HashMap::new();+ for name in names {+ let description = format!("uniffi.trampoline.{name}\0");+ let mut desc_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_string_utf8(+ raw_env,+ description.as_ptr() as *const _,+ description.len() - 1,+ &mut desc_val,+ );+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create trampoline symbol description".to_string(),+ ));+ }++ let mut sym_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_symbol(raw_env, desc_val, &mut sym_val);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create trampoline Symbol".to_string(),+ ));+ }++ let mut sym_ref: napi::sys::napi_ref = std::ptr::null_mut();+ let status = napi::sys::napi_create_reference(raw_env, sym_val, 1, &mut sym_ref);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to reference trampoline Symbol".to_string(),+ ));+ }+ symbols.insert(name.clone(), sym_ref);+ }+ Ok(Self { symbols, raw_env })+ }++ /// Resolve the Symbol for `callback_name`, if the module declares it.+ ///+ /// # Safety+ ///+ /// `raw_env` must match the env this cache was created in.+ unsafe fn symbol(+ &self,+ raw_env: napi::sys::napi_env,+ callback_name: &str,+ ) -> Option<napi::sys::napi_value> {+ let sym_ref = self.symbols.get(callback_name)?;+ let mut sym_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_get_reference_value(raw_env, *sym_ref, &mut sym_val);+ if status != napi::sys::Status::napi_ok || sym_val.is_null() {+ return None;+ }+ Some(sym_val)+ }++ /// Read the trampoline cached on `js_fn` for `callback_name`.+ ///+ /// Returns `Ok(None)` when nothing is cached yet. A lookup failure is also+ /// reported as `Ok(None)` rather than an error: the only cost of a miss is+ /// rebuilding the trampoline, which is exactly the pre-cache behaviour, so a+ /// transient napi hiccup must not fail an otherwise valid FFI call.+ ///+ /// # Safety+ ///+ /// `raw_env` must be valid for the current callback scope; `obj` must be a JS+ /// function value from that scope.+ pub unsafe fn get(+ &self,+ raw_env: napi::sys::napi_env,+ obj: napi::sys::napi_value,+ callback_name: &str,+ ) -> napi::Result<Option<*const c_void>> {+ let Some(sym_val) = self.symbol(raw_env, callback_name) else {+ return Ok(None);+ };++ let mut has = false;+ let status = napi::sys::napi_has_own_property(raw_env, obj, sym_val, &mut has);+ if status != napi::sys::Status::napi_ok || !has {+ return Ok(None);+ }++ let mut val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_get_property(raw_env, obj, sym_val, &mut val);+ if status != napi::sys::Status::napi_ok || val.is_null() {+ return Ok(None);+ }++ let mut ptr: u64 = 0;+ let mut lossless = false;+ let status = napi::sys::napi_get_value_bigint_uint64(raw_env, val, &mut ptr, &mut lossless);+ if status != napi::sys::Status::napi_ok || !lossless || ptr == 0 {+ return Ok(None);+ }+ Ok(Some(ptr as *const c_void))+ }++ /// Cache `fn_ptr` on `js_fn` for `callback_name`.+ ///+ /// Defined non-enumerable so the marker cannot show up in property enumeration+ /// or structural comparison of a user-supplied function.+ ///+ /// # Safety+ ///+ /// As [`Self::get`].+ pub unsafe fn set(+ &self,+ raw_env: napi::sys::napi_env,+ obj: napi::sys::napi_value,+ callback_name: &str,+ fn_ptr: *const c_void,+ ) -> napi::Result<()> {+ let Some(sym_val) = self.symbol(raw_env, callback_name) else {+ return Ok(());+ };++ let mut val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_bigint_uint64(raw_env, fn_ptr as u64, &mut val);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create BigInt for trampoline pointer".to_string(),+ ));+ }++ let descriptor = napi::sys::napi_property_descriptor {+ utf8name: std::ptr::null(),+ name: sym_val,+ method: None,+ getter: None,+ setter: None,+ value: val,+ attributes: napi::sys::PropertyAttributes::writable,+ data: std::ptr::null_mut(),+ };+ let status = napi::sys::napi_define_properties(raw_env, obj, 1, &descriptor);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to cache trampoline pointer".to_string(),+ ));+ }+ Ok(())+ }+}++impl Drop for TrampolineCache {+ fn drop(&mut self) {+ for sym_ref in self.symbols.values() {+ // SAFETY: each ref was created against `self.raw_env` with refcount 1 and+ // has not been deleted. The trampolines the Symbols pointed at stay leaked+ // on purpose — see the module docs.+ unsafe {+ napi::sys::napi_delete_reference(self.raw_env, *sym_ref);+ }+ }+ }+}diff --git a/libs/cua-driver/typescript/test/native-runtime-callbacks.test.mjs b/libs/cua-driver/typescript/test/native-runtime-callbacks.test.mjsnew file mode 100644index 0000000000..a9d99b18b6--- /dev/null+++ b/libs/cua-driver/typescript/test/native-runtime-callbacks.test.mjs@@ -0,0 +1,59 @@+import assert from "node:assert/strict"+import { existsSync } from "node:fs"+import path from "node:path"+import test from "node:test"+import { fileURLToPath } from "node:url"++// Every await of an async SDK call passes the same continuation callback to+// rust_future_poll. The Node runtime must build one trampoline for it, not one+// per poll: each trampoline owns a ThreadsafeFunction whose libuv async handle+// is never freed, and the host's event loop walks every one of them on each+// wakeup. A pending waitForExit polls many times a second, so a per-poll build+// slowed an Electron main process to a stall within a day.+//+// RSS is too noisy to assert at this scale. The runtime records the cached+// trampoline on the function under a hidden Symbol, so assert on that instead.++const testDirectory = path.dirname(fileURLToPath(import.meta.url))+const distribution = path.resolve(testDirectory, "../dist")+const available = existsSync(path.join(distribution, "native", "cua_driver_sdk-ffi.js"))++test(+ "async calls reuse one continuation trampoline across polls",+ { skip: !available, timeout: 30_000 },+ async () => {+ const { default: nativeModule } = await import(+ path.join(distribution, "native", "cua_driver_sdk-ffi.js")+ )+ const sdk = await import(path.join(distribution, "index.js"))+ const native = nativeModule()+ const continuations = new Set()+ for (const name of Object.keys(native)) {+ if (!name.includes("rust_future_poll")) continue+ const poll = native[name]+ native[name] = (future, continuation, handle) => {+ continuations.add(continuation)+ return poll(future, continuation, handle)+ }+ }++ const host = new sdk.EmbeddedCuaDriverHost(+ path.join(testDirectory, "missing cua-driver"),+ "com.example.test",+ )+ try {+ const markers = []+ for (let call = 0; call < 50; call += 1) {+ await host.waitForExit("missing-generation").catch(() => {})+ const [continuation] = continuations+ markers.push(Object.getOwnPropertySymbols(continuation).map((key) => continuation[key]))+ }+ assert.equal(continuations.size, 1, "the SDK passes one continuation function")+ assert.equal(markers[0].length, 1, "the first poll caches one trampoline")+ assert.equal(typeof markers[0][0], "bigint")+ assert.deepEqual(markers.at(-1), markers[0], "later polls reuse the cached trampoline")+ } finally {+ host.uniffiDestroy()+ }+ },+)diff --git a/libs/cua/scripts/build-node-runtime.mjs b/libs/cua/scripts/build-node-runtime.mjsindex 2c6ae18441..a540f4eb79 100644--- a/libs/cua/scripts/build-node-runtime.mjs+++ b/libs/cua/scripts/build-node-runtime.mjs@@ -9,6 +9,16 @@* this compatibility build keeps the same values and ownership while using* JavaScript-owned Uint8Arrays at the N-API boundary.*+ * UBRN 0.31.0-3 also builds a new callback trampoline, with its own+ * ThreadsafeFunction and libuv async handle, every time a JS function is passed+ * as a callback argument. The async poll loop passes its continuation callback+ * on every poll, so each await leaked one, and the host's event loop slowed as+ * it walked every leaked handle on each wakeup. UBRN fixed this in 0.31.0-4+ * (#440) by caching one trampoline per callback name and JS function. That+ * release also changes the RustBuffer boundary patched below, so this build+ * backports only the cache: node-runtime-trampoline-cache.rs is UBRN's+ * callback/cache.rs from that change, unmodified.+ ** The patched source remains MPL-2.0 and comes from the exact, pinned* uniffi-bindgen-react-native development dependency.*/@@ -144,6 +154,88 @@ function patchCall(source) {return `${source.slice(0, bodyStart)}${replacement}${source.slice(bodyEnd + bodyEndNeedle.length)}`}+function patchCallbackModule(source) {+ return replaceOnce(+ source,+ "pub(crate) mod vtable;",+ "pub(crate) mod vtable;\npub(crate) mod cache;",+ "callback module list",+ )+}++function patchRegisterTrampolines(source) {+ source = replaceOnce(+ source,+ " let capacity_symbol = Arc::new(unsafe { CapacitySymbol::new(env.raw())? });",+ ` let capacity_symbol = Arc::new(unsafe { CapacitySymbol::new(env.raw())? });+ // One cached trampoline per (callback name, JS function) for this registration.+ let trampolines = Arc::new(unsafe {+ crate::callback::cache::TrampolineCache::new(env.raw(), module.spec_callbacks().keys())?+ });`,+ "registration capacity Symbol",+ )+ source = replaceOnce(+ source,+ " let cap_sym_for_call = Arc::clone(&capacity_symbol);",+ " let cap_sym_for_call = Arc::clone(&capacity_symbol);\n let trampolines_for_call = Arc::clone(&trampolines);",+ "call closure captures",+ )+ return replaceOnce(+ source,+ " &cap_sym_for_call,\n",+ " &cap_sym_for_call,\n &trampolines_for_call,\n",+ "call dispatch arguments",+ )+}++function patchCallTrampolines(source) {+ source = replaceOnce(+ source,+ " has_rust_call_status: bool,\n capacity_symbol: &CapacitySymbol,\n) -> Result<JsUnknown> {",+ " has_rust_call_status: bool,\n capacity_symbol: &CapacitySymbol,\n trampolines: &callback::cache::TrampolineCache,\n) -> Result<JsUnknown> {",+ "call dispatch signature",+ )+ return replaceOnce(+ source,+ ` let js_fn = unsafe { napi::JsFunction::from_raw(env.raw(), js_val.raw())? };+ let user_data = callback::create_callback_user_data(env, js_fn, cb_name, module)?;+ let fn_ptr = module+ .make_callback_trampoline(+ cb_name,+ callback::on_js_thread,+ callback::dispatch_to_js_thread,+ callback::is_js_thread,+ user_data,+ )+ .map_err(core_err)?;+ slot::write_pointer(slot, fn_ptr);`,+ ` // Trampolines are never freed, so build at most one per JS function.+ let raw_fn_val = unsafe { js_val.raw() };+ let cached = unsafe { trampolines.get(env.raw(), raw_fn_val, cb_name)? };+ let fn_ptr = match cached {+ Some(fn_ptr) => fn_ptr,+ None => {+ let js_fn = unsafe { napi::JsFunction::from_raw(env.raw(), raw_fn_val)? };+ let user_data =+ callback::create_callback_user_data(env, js_fn, cb_name, module)?;+ let fn_ptr = module+ .make_callback_trampoline(+ cb_name,+ callback::on_js_thread,+ callback::dispatch_to_js_thread,+ callback::is_js_thread,+ user_data,+ )+ .map_err(core_err)?;+ unsafe { trampolines.set(env.raw(), raw_fn_val, cb_name, fn_ptr)? };+ fn_ptr+ }+ };+ slot::write_pointer(slot, fn_ptr);`,+ "callback argument dispatch",+ )+}+const temporaryRoot = mkdtempSync(join(tmpdir(), "cua-node-runtime-"))try {const runtimeRoot = join(temporaryRoot, "runtime")@@ -156,7 +248,14 @@ try {const registerPath = join(runtimeRoot, "napi", "src", "register", "mod.rs")writeFileSync(registerPath, patchRegister(readFileSync(registerPath, "utf8")))const callPath = join(runtimeRoot, "napi", "src", "call", "mod.rs")- writeFileSync(callPath, patchCall(readFileSync(callPath, "utf8")))+ writeFileSync(callPath, patchCallTrampolines(patchCall(readFileSync(callPath, "utf8"))))+ writeFileSync(registerPath, patchRegisterTrampolines(readFileSync(registerPath, "utf8")))+ const callbackPath = join(runtimeRoot, "napi", "src", "callback", "mod.rs")+ writeFileSync(callbackPath, patchCallbackModule(readFileSync(callbackPath, "utf8")))+ copyFileSync(+ join(scriptDirectory, "node-runtime-trampoline-cache.rs"),+ join(runtimeRoot, "napi", "src", "callback", "cache.rs"),+ )// Respect CARGO_TARGET_DIR (shared CI caches set it); pass it explicitly// so the artifact location below always matches the build's.diff --git a/libs/cua/scripts/node-runtime-NOTICE.md b/libs/cua/scripts/node-runtime-NOTICE.mdindex f903e4ce32..997404e1a1 100644--- a/libs/cua/scripts/node-runtime-NOTICE.md+++ b/libs/cua/scripts/node-runtime-NOTICE.md@@ -5,8 +5,11 @@ runtime in `uniffi-bindgen-react-native` 0.31.0-3, copyright its contributorsand licensed under the Mozilla Public License 2.0.The corresponding source is the pinned npm development dependency plus the-deterministic transformations in `scripts/build-node-runtime.mjs`. The source-and build script are available in the Cua repository at the release tag that-matches this package.+deterministic transformations in `scripts/build-node-runtime.mjs`. Those+transformations add `scripts/node-runtime-trampoline-cache.rs`, which is+`runtimes/napi/src/callback/cache.rs` from `uniffi-bindgen-react-native` commit+5d24b38 (jhugman/uniffi-bindgen-react-native#440, released in 0.31.0-4),+unmodified and under the same license. The source and build script are+available in the Cua repository at the release tag that matches this package.<https://www.mozilla.org/MPL/2.0/>diff --git a/libs/cua/scripts/node-runtime-trampoline-cache.rs b/libs/cua/scripts/node-runtime-trampoline-cache.rsnew file mode 100644index 0000000000..6fcf32b983--- /dev/null+++ b/libs/cua/scripts/node-runtime-trampoline-cache.rs@@ -0,0 +1,227 @@+/*+ * This Source Code Form is subject to the terms of the Mozilla Public+ * License, v. 2.0. If a copy of the MPL was not distributed with this+ * file, You can obtain one at http://mozilla.org/MPL/2.0/+ */+//! Trampoline cache: one libffi trampoline per (callback name, JS function).+//!+//! Building a trampoline for a callback argument is expensive and **permanently+//! leaked**, by design: the library may invoke the function pointer from any thread+//! at any later time, so nothing can safely reclaim it. Each one costs+//!+//! - a strong `napi_ref` pinning the JS function,+//! - a leaked `CallbackUserData` (arg layout, cloned type descriptors, `Arc<Module>`),+//! - a fresh JS function plus a fresh `ThreadsafeFunction` (a libuv async handle),+//! and an entry appended to the env's TSFN registry,+//! - a leaked `TrampolineUserdata`, and+//! - a libffi `Closure`, which owns an executable page.+//!+//! Dispatch used to build one on *every* call that passed a callback, so the cost+//! became a ~3 KB per-call leak. That is reached from ordinary generated code: the+//! async poll loop passes its continuation callback on every poll, so every `await`+//! leaked ~3.2 KB regardless of argument types.+//!+//! Caching removes the per-call part without changing any lifetime: trampolines are+//! still never freed, there is just one per distinct (callback name, function) pair+//! instead of one per call. The async continuation is a module-level `const`, so it+//! is built once and reused for the life of the registration.+//!+//! The cached pointer lives on the JS function object under a hidden per-callback+//! Symbol, mirroring how [`crate::napi_utils::CapacitySymbol`] records RustBuffer+//! ownership on a view. Keying on the function object is what makes reuse safe:+//!+//! - The Symbols belong to one `register()` call, hence one `napi_env`, and a JS+//! function object cannot cross realms. So a cached trampoline is never handed to+//! a different env than the `raw_env`/`owner_thread` its userdata captured.+//! - A trampoline carries no per-call state. Callbacks receive their handle as an+//! ordinary argument, so reusing one across calls cannot mix up call state.+//!+//! A caller that passes a freshly created closure on every call gets no benefit and+//! behaves exactly as before — there is nothing stable to key on.++use std::collections::HashMap;+use std::ffi::c_void;++/// Per-registration hidden Symbols keyed by callback name, used to stash a built+/// trampoline pointer on the JS function it was built for.+pub struct TrampolineCache {+ /// One `napi_ref`'d Symbol per callback name in the module spec. Symbols are+ /// GC-managed; the strong reference keeps them alive for as long as the JS-side+ /// module facade, which is what makes the cache last as long as the registration.+ symbols: HashMap<String, napi::sys::napi_ref>,+ /// Captured so `Drop` releases each reference against the env that owns it.+ raw_env: napi::sys::napi_env,+}++// SAFETY: mirrors `CapacitySymbol`. These raw handles are only ever dereferenced on+// the JS thread that created them; `Send`/`Sync` is required because the cache is+// parked in an `Arc` captured by closures that napi-rs requires to be `Send`.+unsafe impl Send for TrampolineCache {}+unsafe impl Sync for TrampolineCache {}++impl TrampolineCache {+ /// Create one Symbol per callback name.+ ///+ /// # Safety+ ///+ /// `raw_env` must be a valid `napi_env` for the current callback scope.+ pub unsafe fn new<'a>(+ raw_env: napi::sys::napi_env,+ names: impl Iterator<Item = &'a String>,+ ) -> napi::Result<Self> {+ let mut symbols = HashMap::new();+ for name in names {+ let description = format!("uniffi.trampoline.{name}\0");+ let mut desc_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_string_utf8(+ raw_env,+ description.as_ptr() as *const _,+ description.len() - 1,+ &mut desc_val,+ );+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create trampoline symbol description".to_string(),+ ));+ }++ let mut sym_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_symbol(raw_env, desc_val, &mut sym_val);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create trampoline Symbol".to_string(),+ ));+ }++ let mut sym_ref: napi::sys::napi_ref = std::ptr::null_mut();+ let status = napi::sys::napi_create_reference(raw_env, sym_val, 1, &mut sym_ref);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to reference trampoline Symbol".to_string(),+ ));+ }+ symbols.insert(name.clone(), sym_ref);+ }+ Ok(Self { symbols, raw_env })+ }++ /// Resolve the Symbol for `callback_name`, if the module declares it.+ ///+ /// # Safety+ ///+ /// `raw_env` must match the env this cache was created in.+ unsafe fn symbol(+ &self,+ raw_env: napi::sys::napi_env,+ callback_name: &str,+ ) -> Option<napi::sys::napi_value> {+ let sym_ref = self.symbols.get(callback_name)?;+ let mut sym_val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_get_reference_value(raw_env, *sym_ref, &mut sym_val);+ if status != napi::sys::Status::napi_ok || sym_val.is_null() {+ return None;+ }+ Some(sym_val)+ }++ /// Read the trampoline cached on `js_fn` for `callback_name`.+ ///+ /// Returns `Ok(None)` when nothing is cached yet. A lookup failure is also+ /// reported as `Ok(None)` rather than an error: the only cost of a miss is+ /// rebuilding the trampoline, which is exactly the pre-cache behaviour, so a+ /// transient napi hiccup must not fail an otherwise valid FFI call.+ ///+ /// # Safety+ ///+ /// `raw_env` must be valid for the current callback scope; `obj` must be a JS+ /// function value from that scope.+ pub unsafe fn get(+ &self,+ raw_env: napi::sys::napi_env,+ obj: napi::sys::napi_value,+ callback_name: &str,+ ) -> napi::Result<Option<*const c_void>> {+ let Some(sym_val) = self.symbol(raw_env, callback_name) else {+ return Ok(None);+ };++ let mut has = false;+ let status = napi::sys::napi_has_own_property(raw_env, obj, sym_val, &mut has);+ if status != napi::sys::Status::napi_ok || !has {+ return Ok(None);+ }++ let mut val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_get_property(raw_env, obj, sym_val, &mut val);+ if status != napi::sys::Status::napi_ok || val.is_null() {+ return Ok(None);+ }++ let mut ptr: u64 = 0;+ let mut lossless = false;+ let status = napi::sys::napi_get_value_bigint_uint64(raw_env, val, &mut ptr, &mut lossless);+ if status != napi::sys::Status::napi_ok || !lossless || ptr == 0 {+ return Ok(None);+ }+ Ok(Some(ptr as *const c_void))+ }++ /// Cache `fn_ptr` on `js_fn` for `callback_name`.+ ///+ /// Defined non-enumerable so the marker cannot show up in property enumeration+ /// or structural comparison of a user-supplied function.+ ///+ /// # Safety+ ///+ /// As [`Self::get`].+ pub unsafe fn set(+ &self,+ raw_env: napi::sys::napi_env,+ obj: napi::sys::napi_value,+ callback_name: &str,+ fn_ptr: *const c_void,+ ) -> napi::Result<()> {+ let Some(sym_val) = self.symbol(raw_env, callback_name) else {+ return Ok(());+ };++ let mut val: napi::sys::napi_value = std::ptr::null_mut();+ let status = napi::sys::napi_create_bigint_uint64(raw_env, fn_ptr as u64, &mut val);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to create BigInt for trampoline pointer".to_string(),+ ));+ }++ let descriptor = napi::sys::napi_property_descriptor {+ utf8name: std::ptr::null(),+ name: sym_val,+ method: None,+ getter: None,+ setter: None,+ value: val,+ attributes: napi::sys::PropertyAttributes::writable,+ data: std::ptr::null_mut(),+ };+ let status = napi::sys::napi_define_properties(raw_env, obj, 1, &descriptor);+ if status != napi::sys::Status::napi_ok {+ return Err(napi::Error::from_reason(+ "Failed to cache trampoline pointer".to_string(),+ ));+ }+ Ok(())+ }+}++impl Drop for TrampolineCache {+ fn drop(&mut self) {+ for sym_ref in self.symbols.values() {+ // SAFETY: each ref was created against `self.raw_env` with refcount 1 and+ // has not been deleted. The trampolines the Symbols pointed at stay leaked+ // on purpose — see the module docs.+ unsafe {+ napi::sys::napi_delete_reference(self.raw_env, *sym_ref);+ }+ }+ }+}