fix(ext/napi): call wrap/ref finalizers at shutdown (#32592)

- Track NAPI finalizer callbacks (from `napi_wrap`,
`napi_create_external`, `napi_add_finalizer`, `napi_set_instance_data`)
in a `PendingNapiFinalizer` list shared between `NapiState` and `Env`
- Call tracked finalizers in LIFO order during `MainWorker` shutdown
while V8 is still alive with a proper `HandleScope`, matching Node.js's
`RefTracker::FinalizeAll()` behavior
- When finalizers fire naturally via GC weak callbacks, they deregister
from the tracker to avoid double-calling

This fixes native addons like DuckDB that rely on C++ destructor cleanup
(e.g. WAL checkpointing) during process exit. Previously these
finalizers only ran via V8 GC weak callbacks, which never fire for
objects still reachable at exit.

Closes #27468

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: bartlomieju

cli/lib/worker.rs

@@ -853,6 +853,11 @@ impl LibMainWorker {
     self.worker.dispatch_process_exit_event()
   }
 
+  #[inline]
+  pub fn run_napi_ref_finalizers(&mut self) {
+    self.worker.run_napi_ref_finalizers()
+  }
+
   pub async fn execute_main_module(&mut self) -> Result<(), CoreError> {
     let id = self.worker.preload_main_module(&self.main_module).await?;
     self.worker.evaluate_module(id).await
@@ -905,6 +910,7 @@ impl LibMainWorker {
 
     self.worker.dispatch_unload_event()?;
     self.worker.dispatch_process_exit_event()?;
+    self.worker.run_napi_ref_finalizers();
 
     Ok(self.worker.exit_code())
   }

cli/tools/bench/mod.rs

@@ -291,6 +291,7 @@ async fn bench_specifier_inner(
   worker
     .dispatch_process_exit_event()
     .map_err(|e| CoreErrorKind::Js(e).into_box())?;
+  worker.run_napi_ref_finalizers();
 
   // Ensure the worker has settled so we can catch any remaining unhandled rejections. We don't
   // want to wait forever here.

cli/worker.rs

@@ -159,6 +159,7 @@ impl CliMainWorker {
 
     self.worker.dispatch_unload_event()?;
     self.worker.dispatch_process_exit_event()?;
+    self.worker.run_napi_ref_finalizers();
 
     if let Some(mut coverage_collector) = coverage_cell.borrow_mut().take() {
       coverage_collector.stop_collecting()?;
@@ -217,6 +218,7 @@ impl CliMainWorker {
 
         self.inner.worker.dispatch_unload_event()?;
         self.inner.worker.dispatch_process_exit_event()?;
+        self.inner.worker.run_napi_ref_finalizers();
 
         Ok(())
       }

ext/napi/js_native_api.rs

@@ -132,6 +132,9 @@ impl Reference {
     // it might free the reference (which would be a UAF)
     let ownership = reference.ownership;
     if let Some(finalize_cb) = finalize_cb {
+      // Deregister before calling so it won't be called again at shutdown
+      let env = unsafe { &*reference.env };
+      env.remove_ref_finalizer(finalize_data);
       unsafe {
         finalize_cb(reference.env as _, finalize_data, finalize_hint);
       }
@@ -2520,6 +2523,15 @@ fn napi_wrap(
     finalize_hint,
   );
 
+  if let Some(cb) = finalize_cb {
+    env.add_ref_finalizer(
+      env_ptr as napi_env,
+      cb,
+      native_object,
+      finalize_hint,
+    );
+  }
+
   let reference = Reference::into_raw(reference) as *mut c_void;
 
   if !result.is_null() {
@@ -2571,6 +2583,7 @@ fn unwrap(
   }
 
   if !keep {
+    env.remove_ref_finalizer(reference.finalize_data);
     assert!(obj.delete_private(scope, napi_wrap).unwrap_or(false));
     unsafe { Reference::remove(reference) };
   }
@@ -2622,6 +2635,12 @@ fn napi_create_external<'s>(
   let external = v8::External::new(scope, wrapper as _);
 
   if let Some(finalize_cb) = finalize_cb {
+    env.add_ref_finalizer(
+      env_ptr as napi_env,
+      finalize_cb,
+      data,
+      finalize_hint,
+    );
     Reference::into_raw(Reference::new(
       env_ptr,
       external.into(),
@@ -3669,6 +3688,16 @@ fn napi_add_finalizer(
   } else {
     ReferenceOwnership::Userland
   };
+
+  if let Some(cb) = finalize_cb {
+    env.add_ref_finalizer(
+      env_ptr as napi_env,
+      cb,
+      finalize_data,
+      finalize_hint,
+    );
+  }
+
   let reference = Reference::new(
     env,
     value.into(),
@@ -3725,6 +3754,9 @@ fn napi_set_instance_data(
 ) -> napi_status {
   let env = check_env!(env);
 
+  // Note: instance data finalizers are NOT registered in ref_tracker because
+  // they already have their own teardown path in NapiState::Drop which calls
+  // EnvShared instance_data finalize_cb directly.
   env.shared_mut().instance_data = Some(InstanceData {
     data,
     finalize_cb,

ext/napi/lib.rs

@@ -303,9 +303,22 @@ pub struct napi_node_version {
 pub trait PendingNapiAsyncWork: FnOnce() + Send + 'static {}
 impl<T> PendingNapiAsyncWork for T where T: FnOnce() + Send + 'static {}
 
+/// A pending NAPI finalizer callback to be called at environment shutdown.
+/// This matches Node.js's behavior of tracking references with finalize
+/// callbacks and calling them during `napi_env::DeleteMe()`.
+pub struct PendingNapiFinalizer {
+  pub env: napi_env,
+  pub cb: napi_finalize,
+  pub data: *mut c_void,
+  pub hint: *mut c_void,
+}
+
 pub struct NapiState {
   // Thread safe functions.
   pub env_cleanup_hooks: Rc<RefCell<Vec<(napi_cleanup_hook, *mut c_void)>>>,
+  /// Tracked finalizer callbacks that should be called at shutdown.
+  /// Matches Node.js `finalizing_reflist` / `reflist` behavior.
+  pub ref_tracker: Rc<RefCell<Vec<PendingNapiFinalizer>>>,
   pub env_shared_ptrs: Vec<*mut EnvShared>,
 }
 
@@ -345,6 +358,10 @@ impl Drop for NapiState {
       }
     }
 
+    // Note: remaining ref tracker entries are not finalized here because
+    // V8 is no longer alive. MainWorker::run_napi_ref_finalizers() handles
+    // this by calling finalizers directly while V8 is still alive.
+
     // Call instance data finalize callbacks for all registered EnvShared instances.
     // Each entry should be unique since each op_napi_open creates a fresh EnvShared.
     debug_assert!(
@@ -418,6 +435,7 @@ pub struct Env {
   pub shared: *mut EnvShared,
   pub async_work_sender: V8CrossThreadTaskSpawner,
   cleanup_hooks: Rc<RefCell<Vec<(napi_cleanup_hook, *mut c_void)>>>,
+  ref_tracker: Rc<RefCell<Vec<PendingNapiFinalizer>>>,
   external_ops_tracker: ExternalOpsTracker,
   pub last_error: napi_extended_error_info,
   pub last_exception: Option<v8::Global<v8::Value>>,
@@ -439,6 +457,7 @@ impl Env {
     report_error: v8::Global<v8::Function>,
     sender: V8CrossThreadTaskSpawner,
     cleanup_hooks: Rc<RefCell<Vec<(napi_cleanup_hook, *mut c_void)>>>,
+    ref_tracker: Rc<RefCell<Vec<PendingNapiFinalizer>>>,
     external_ops_tracker: ExternalOpsTracker,
   ) -> Self {
     Self {
@@ -451,6 +470,7 @@ impl Env {
       open_handle_scopes: 0,
       async_work_sender: sender,
       cleanup_hooks,
+      ref_tracker,
       external_ops_tracker,
       last_error: napi_extended_error_info {
         error_message: std::ptr::null(),
@@ -533,6 +553,28 @@ impl Env {
       None => panic!("Cannot remove cleanup hook which was not registered"),
     }
   }
+
+  pub fn add_ref_finalizer(
+    &self,
+    env: napi_env,
+    cb: napi_finalize,
+    data: *mut c_void,
+    hint: *mut c_void,
+  ) {
+    self.ref_tracker.borrow_mut().push(PendingNapiFinalizer {
+      env,
+      cb,
+      data,
+      hint,
+    });
+  }
+
+  pub fn remove_ref_finalizer(&self, data: *mut c_void) {
+    let mut tracker = self.ref_tracker.borrow_mut();
+    if let Some(pos) = tracker.iter().rposition(|f| f.data == data) {
+      tracker.remove(pos);
+    }
+  }
 }
 
 deno_core::extension!(deno_napi,
@@ -545,6 +587,7 @@ deno_core::extension!(deno_napi,
   state = |state, options| {
     state.put(NapiState {
       env_cleanup_hooks: Rc::new(RefCell::new(vec![])),
+      ref_tracker: Rc::new(RefCell::new(vec![])),
       env_shared_ptrs: vec![],
     });
     if let Some(loader) = options.deno_rt_native_addon_loader {
@@ -578,6 +621,7 @@ fn op_napi_open<'scope>(
   let (
     async_work_sender,
     cleanup_hooks,
+    ref_tracker,
     external_ops_tracker,
     deno_rt_native_addon_loader,
     path,
@@ -590,6 +634,7 @@ fn op_napi_open<'scope>(
     (
       op_state.borrow::<V8CrossThreadTaskSpawner>().clone(),
       napi_state.env_cleanup_hooks.clone(),
+      napi_state.ref_tracker.clone(),
       op_state.external_ops_tracker.clone(),
       op_state.try_borrow::<DenoRtNativeAddonLoaderRc>().cloned(),
       path,
@@ -618,6 +663,7 @@ fn op_napi_open<'scope>(
     v8::Global::new(scope, report_error),
     async_work_sender,
     cleanup_hooks,
+    ref_tracker,
     external_ops_tracker,
   );
   env.shared = Box::into_raw(Box::new(env_shared));

runtime/worker.rs

@@ -984,6 +984,42 @@ impl MainWorker {
     Ok(())
   }
 
+  /// Runs pending NAPI ref/wrap finalizers by calling them directly while V8
+  /// is still alive. This matches Node.js behavior where `napi_env::DeleteMe()`
+  /// calls `RefTracker::FinalizeAll()` during environment teardown.
+  pub fn run_napi_ref_finalizers(&mut self) {
+    let finalizers = {
+      let op_state = self.js_runtime.op_state();
+      let op_state = op_state.borrow();
+      match op_state.try_borrow::<deno_napi::NapiState>() {
+        Some(s) => {
+          let mut tracker = s.ref_tracker.borrow_mut();
+          std::mem::take(&mut *tracker)
+        }
+        None => return,
+      }
+    };
+    if finalizers.is_empty() {
+      return;
+    }
+
+    // Call each finalizer in reverse (LIFO) order within a proper HandleScope
+    // so native addon code can use NAPI functions during cleanup. LIFO matches
+    // Node.js's linked list behavior (head insertion → reverse iteration).
+    {
+      deno_core::scope!(scope, &mut self.js_runtime);
+      let _scope = v8::HandleScope::new(scope);
+      for f in finalizers.into_iter().rev() {
+        // SAFETY: The pointers (env, data, hint) were stored when the native
+        // addon called napi_wrap/napi_create_external/napi_add_finalizer and
+        // V8 is still alive (we have an active HandleScope).
+        unsafe {
+          (f.cb)(f.env, f.data, f.hint);
+        }
+      }
+    }
+  }
+
   /// Dispatches "beforeunload" event to the JavaScript runtime. Returns a boolean
   /// indicating if the event was prevented and thus event loop should continue
   /// running.

tests/integration/napi_tests.rs

@@ -98,3 +98,40 @@ fn napi_tests() {
   }
   assert!(output.status.success());
 }
+
+/// Test that NAPI wrap finalizers are called at shutdown even when the
+/// wrapped JS object is still reachable. This matches Node.js behavior
+/// and is required for native addons like DuckDB that rely on destructor
+/// cleanup (e.g., WAL checkpointing) during process exit.
+#[test_util::test]
+fn napi_wrap_leak_pointers_finalizer_on_shutdown() {
+  napi_build();
+
+  let output = deno_cmd()
+    .current_dir(napi_tests_path())
+    .arg("run")
+    .arg("--allow-read")
+    .arg("--allow-env")
+    .arg("--allow-ffi")
+    .arg("--config")
+    .arg(deno_config_path())
+    .arg("--no-lock")
+    .arg("wrap_leak.js")
+    .envs(env_vars_for_npm_tests())
+    .output()
+    .unwrap();
+  let stdout = std::str::from_utf8(&output.stdout).unwrap();
+  let stderr = std::str::from_utf8(&output.stderr).unwrap();
+
+  if !output.status.success() {
+    eprintln!("exit code {:?}", output.status.code());
+    println!("stdout {}", stdout);
+    println!("stderr {}", stderr);
+  }
+  assert!(output.status.success());
+  assert!(
+    stdout.contains("pointers released on shutdown"),
+    "Expected wrap finalizer to run at shutdown, got stdout: {}",
+    stdout
+  );
+}

tests/napi/instance_data_test.js

@@ -27,9 +27,9 @@ if (import.meta.main) {
     assertEquals(code, 0);
 
     const stdoutText = new TextDecoder().decode(stdout);
-    const stdoutLines = stdoutText.split("\n");
-    assertEquals(stdoutLines.length, 3);
-    assertEquals(stdoutLines[0], "set instance data");
-    assertEquals(stdoutLines[1], "instance_data_free(42)");
+    assertEquals(
+      stdoutText,
+      "set instance data\ninstance_data_free(42)\n",
+    );
   });
 }

tests/napi/src/finalizer.rs

@@ -144,6 +144,48 @@ extern "C" fn test_external_arraybuffer(
   result
 }
 
+/// Wrap finalizer that prints a message. Used to test that wrap finalizers
+/// are called at shutdown even when the wrapped object is still reachable.
+unsafe extern "C" fn wrap_leak_release(
+  _env: napi_env,
+  data: *mut ::std::os::raw::c_void,
+  _hint: *mut ::std::os::raw::c_void,
+) {
+  let msg = unsafe { Box::from_raw(data as *mut String) };
+  println!("{}", msg);
+}
+
+/// Creates a napi_wrap on the given JS object with a finalizer that prints
+/// a message. The wrap is NOT explicitly removed, so only the shutdown
+/// finalizer path will trigger the callback. This tests that NAPI wrap
+/// finalizers are called during environment teardown (matching Node.js
+/// behavior).
+extern "C" fn test_wrap_leak(
+  env: napi_env,
+  info: napi_callback_info,
+) -> napi_value {
+  let (args, argc, _) = napi_get_callback_info!(env, info, 1);
+  assert_eq!(argc, 1);
+
+  let mut ty = -1;
+  assert_napi_ok!(napi_typeof(env, args[0], &mut ty));
+  assert_eq!(ty, napi_object);
+
+  let msg = Box::new(String::from("pointers released on shutdown"));
+  let msg_ptr = Box::into_raw(msg) as *mut ::std::os::raw::c_void;
+
+  assert_napi_ok!(napi_wrap(
+    env,
+    args[0],
+    msg_ptr,
+    Some(wrap_leak_release),
+    ptr::null_mut(),
+    ptr::null_mut(),
+  ));
+
+  args[0]
+}
+
 pub fn init(env: napi_env, exports: napi_value) {
   let properties = &[
     napi_new_property!(env, "test_bind_finalizer", test_bind_finalizer),
@@ -159,6 +201,7 @@ pub fn init(env: napi_env, exports: napi_value) {
       "test_static_external_buffer",
       test_static_external_buffer
     ),
+    napi_new_property!(env, "test_wrap_leak", test_wrap_leak),
   ];
 
   assert_napi_ok!(napi_define_properties(