Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mjs
index 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.md
index 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 contributors
and 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.rs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.md
index 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 contributors
and 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.rs
new file mode 100644
index 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);
+ }
+ }
+ }
+}