Implement hermes_napi_host for async work and thread-safe functions (#398)

* Implement hermes_napi_host and pass it to hermes_napi_create_env

Provide the Phase 3 host integration for Hermes' first-party Node-API:

- New HermesNapiHost.{hpp,cpp}: a mirror of the hermes_napi_host struct
  (pinned to HERMES_GIT_SHA) and a HostContext per React Native runtime,
  backed by a process-global 4-thread worker pool (post_work /
  cancel_work) and the runtime's CallInvoker behind a type-erased JS
  dispatcher (post_task and work completions). fatal_exception
  stringifies the error, logs and aborts; uv_loop and
  ref_loop/unref_loop stay null by design. Contexts are retained for the
  process lifetime because the env reads the struct during Runtime
  teardown after env cleanup hooks have run.
- CxxNodeApiHostModule passes the host at env creation - before the
  addon's init runs, fixing init-time async work - and drops
  setCallInvoker.
- Delete the RuntimeNodeApiAsync overrides: async work falls through to
  Hermes' implementation, so execute now runs on a worker thread instead
  of the JS thread, and thread-safe functions work for the first time.
- tests/async: execute/complete thread-identity assertions, a gated
  blocking execute (deadlock-proof that execute is off the JS thread)
  and a deterministic cancel-of-running-work case.
- tests/threadsafe-function: port of Node's test_threadsafe_function
  (pthread shim for uv threads, upstream assertions restored) plus
  JS-thread and never-inline supplements; re-enable the
  async_work_thread_safe_function example (its SIGABRT was the null
  host).
- packages/host/tests: Catch2 suite exercising the worker pool,
  cancellation atomicity, post_task ordering/reentrancy and the teardown
  drop path on plain Linux, with a host-cpp-tests CI job mirroring
  weak-node-api-tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y6xHHeMFF853z5R6th5CkF

* Trigger CI for the label-gated device lanes

The Check workflow only reacts to opened/synchronize/reopened, so the
Apple and Android labels added to the PR need a synchronize event to be
seen by the job conditions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y6xHHeMFF853z5R6th5CkF

* Trigger CI with the weak-node-api and host labels applied

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y6xHHeMFF853z5R6th5CkF

* Address review: truthful teardown outcomes, duplicate-queue drop

- JsDispatcher now reports acceptance and WorkItem holds its HostContext
  strongly: the weak_ptr could never expire (contexts are retained for
  the process lifetime), so the pool's drop branches were dead code and
  napi_cancel_async_work could claim success for a completion the
  dispatcher was about to drop. cancel_work now returns the dispatcher's
  verdict, and workerMain/postTask log drops where they actually happen.
- WorkerPool::enqueue drops a double-queued (loopData, workData) instead
  of enqueueing it: a second entry meant two completions for one
  napi_async_work and a use-after-free once the addon deletes the work
  inside the first. Covered by a new Catch2 test; the saturation helper
  now uses distinct jobs per worker so it does not trip the detection.
- Delete HostContext copy/move: host_.data points at this.
- Justify the CallInvoker-liveness assumption at the dispatcher site
  (RuntimeSchedulerCallInvoker holds a weak RuntimeScheduler owned
  together with the runtime, so accepted work cannot outlive it) and
  correct the WorkItem comment: the (loopData, workData) pair separates
  runtimes/reloads, not envs.
- Rework the Catch2 teardown test to model an expired CallInvoker (the
  state production reaches) instead of dropping the last context ref
  (which it never does), and cover the rejected post_task path.
- Scope the 30s mocha timeout to the threadsafe-function suite so a
  genuine deadlock elsewhere still fails fast; add a TODO on
  fatal_exception about routing through RN error handling.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y6xHHeMFF853z5R6th5CkF

---------

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

Author: kraenhansen

.changeset/hermes-napi-host-integration.md

@@ -0,0 +1,5 @@
+---
+"react-native-node-api": minor
+---
+
+Provide a `hermes_napi_host` implementation to the Hermes Node-API environments. This enables thread-safe functions (`napi_create_threadsafe_function` and friends) and moves `napi_async_work` execution onto a worker pool — previously the `execute` callback ran on the JavaScript thread, blocking it for the duration of the work. The host is also in place before an addon's module init runs, so async work and thread-safe functions can now be created during initialization.

.github/workflows/check.yml

@@ -143,6 +143,42 @@ jobs:
           cmake --build build
           ctest --test-dir build --output-on-failure
         working-directory: packages/weak-node-api
+  host-cpp-tests:
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/next' || contains(github.event.pull_request.labels.*.name, 'host')
+    strategy:
+      fail-fast: false
+      matrix:
+        runner:
+          - ubuntu-latest
+          - windows-latest
+          - macos-latest
+    runs-on: ${{ matrix.runner }}
+    name: Host C++ tests (${{ matrix.runner }})
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v6
+        with:
+          node-version: lts/krypton
+          cache: pnpm
+      - name: Setup cpp tools
+        uses: aminya/setup-cpp@v1
+        with:
+          clang-format: true
+      - name: ccache
+        uses: hendrikmuhs/ccache-action@v1.2
+        with:
+          key: ${{ github.job }}-${{ runner.os }}
+      - run: pnpm install
+      - run: pnpm run build
+      - name: Prepare weak-node-api
+        run: pnpm --filter weak-node-api run prebuild:prepare
+      - name: Build and run react-native-node-api host C++ tests
+        run: |
+          cmake -S tests -B tests/build
+          cmake --build tests/build
+          ctest --test-dir tests/build --output-on-failure
+        working-directory: packages/host
   test-ios:
     if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/next' || contains(github.event.pull_request.labels.*.name, 'Apple 🍎')
     name: Test app (iOS)

apps/test-app/App.tsx

@@ -38,7 +38,13 @@ function loadTests({
     )) {
       describe(suiteName, () => {
         for (const [exampleName, requireExample] of Object.entries(examples)) {
-          it(exampleName, async () => {
+          it(exampleName, async function () {
+            if (exampleName === "threadsafe-function") {
+              // The ported Node.js suite marshals thousands of values across
+              // threads; every other example keeps the default timeout so a
+              // genuine deadlock still fails fast.
+              this.timeout(30_000);
+            }
             const test = requireExample();
             if (test instanceof Function) {
               const result = test();

docs/HOW-IT-WORKS.md

@@ -54,7 +54,7 @@ Hermes implements both halves of Node-API: the engine-specific functions (see [j
 - `ref_loop` / `unref_loop` — keep the event loop alive while a thread-safe function is referenced, modelling libuv's "ref" semantics.
 - `fatal_exception` and, for embedders that have one, a libuv loop pointer for `napi_get_uv_event_loop`.
 
-`react-native-node-api` provides that struct, backed by React Native's `CallInvoker` for anything that has to land on the JavaScript thread and a worker pool for the rest.
+`react-native-node-api` provides that struct (see `packages/host/cpp/HermesNapiHost.cpp`), backed by React Native's `CallInvoker` for anything that has to land on the JavaScript thread and a process-global worker pool (four threads, like libuv's default) for the rest. `ref_loop` / `unref_loop` and the libuv loop pointer are deliberately left null: React Native's JavaScript thread has no ref-counted event-loop lifetime to model, so thread-safe function ref/unref are tracked but inert, and `napi_get_uv_event_loop` returns `napi_generic_failure` as upstream documents for hosts without libuv.
 
 ## `my-app` regain control and call `add`
 

eslint.config.js

@@ -62,6 +62,9 @@ export default tseslint.config(
       },
       globals: {
         ...globals.commonjs,
+        // Timers provided by React Native's runtime, where these files run.
+        setTimeout: "readonly",
+        setImmediate: "readonly",
       },
     },
     rules: {

packages/host/.gitignore

@@ -18,3 +18,6 @@ android/build/
 
 # Generated via `npm run generate-weak-node-api-injector`
 /cpp/WeakNodeApiInjector.cpp
+
+# C++ test build artifacts (see `npm run test:configure`)
+/tests/build/

packages/host/android/CMakeLists.txt

@@ -14,8 +14,8 @@ add_library(node-api-host SHARED
   ../cpp/WeakNodeApiInjector.cpp
   ../cpp/RuntimeNodeApi.cpp
   ../cpp/RuntimeNodeApi.hpp
-  ../cpp/RuntimeNodeApiAsync.cpp
-  ../cpp/RuntimeNodeApiAsync.hpp  
+  ../cpp/HermesNapiHost.cpp
+  ../cpp/HermesNapiHost.hpp
 )
 
 target_include_directories(node-api-host PRIVATE

packages/host/cpp/CxxNodeApiHostModule.cpp

@@ -1,27 +1,10 @@
 #include "CxxNodeApiHostModule.hpp"
 #include "Logger.hpp"
-#include "RuntimeNodeApiAsync.hpp"
 
 #include <jsi/hermes-interfaces.h>
 
 using namespace facebook;
 
-// Declared by the vendored Hermes in API/napi/hermes_napi.h. We forward declare
-// it here (rather than including that header) to avoid pulling in Hermes' own
-// node_api.h alongside the weak-node-api copy already included transitively.
-//
-// The declaration must be `extern "C"`: since facebook/hermes#2106 (included in
-// the pinned Hermes commit) the public hermes_napi.h wraps these entry points
-// in `extern "C"`, so Hermes exports the unmangled C symbol. Without matching C
-// linkage here the reference would be to the C++-mangled name and the app fails
-// to link ("Undefined symbol: hermes_napi_create_env"). Passing host as nullptr
-// is enough — async work / thread-safe functions will return failure until a
-// host integration is wired up (Phase 3).
-extern "C" {
-struct hermes_napi_host;
-napi_env hermes_napi_create_env(void *hermes_runtime, hermes_napi_host *host);
-}
-
 namespace callstack::react_native_node_api {
 
 CxxNodeApiHostModule::CxxNodeApiHostModule(
@@ -31,6 +14,40 @@ CxxNodeApiHostModule::CxxNodeApiHostModule(
       MethodMetadata{1, &CxxNodeApiHostModule::requireNodeAddon};
 
   callInvoker_ = std::move(jsInvoker);
+
+  // The JS-thread dispatcher behind the hermes_napi_host integration:
+  // CallInvoker::invokeAsync is callable from any thread, never runs the
+  // function inline and delivers in order on the JS thread.
+  //
+  // Teardown is the load-bearing case. What the host integration needs is
+  // that a function handed to this dispatcher either runs on the JS thread
+  // while the runtime is alive, or is dropped — never invoked against a
+  // destroyed runtime. In bridgeless React Native the CallInvoker received
+  // here is a RuntimeSchedulerCallInvoker holding a std::weak_ptr to the
+  // RuntimeScheduler; the ReactInstance owns scheduler and runtime together
+  // and invokeAsync no-ops once the scheduler is gone, so work cannot outlive
+  // the runtime it targets. The weak capture below covers the remaining
+  // window where this module (and its CallInvoker reference) is released
+  // during instance teardown.
+  //
+  // Dropping is safe precisely because a drop implies that teardown: every
+  // env this host serves is owned by that same runtime and destroyed with it,
+  // so the completion or tsfn dispatch being dropped has no live observer.
+  // The one caller that could still see the difference —
+  // napi_cancel_async_work — receives the verdict through this dispatcher's
+  // return value (see HostContext::cancelWork).
+  hostContext_ = HostContext::create(
+      [weakInvoker = std::weak_ptr(callInvoker_)](std::function<void()> &&fn) {
+        auto invoker = weakInvoker.lock();
+        if (!invoker) {
+          log_warning(
+              "NapiHost: dropping a task posted after runtime teardown");
+          return false;
+        }
+        invoker->invokeAsync(std::move(fn));
+        return true;
+      });
+  HostContext::retainForProcessLifetime(hostContext_);
 }
 
 jsi::Value
@@ -141,7 +158,8 @@ bool CxxNodeApiHostModule::initializeNodeModule(jsi::Runtime &rt,
                 "create a Node-API environment");
       abort();
     }
-    addon.env = hermes_napi_create_env(hermes->getVMRuntimeUnsafe(), nullptr);
+    addon.env =
+        hermes_napi_create_env(hermes->getVMRuntimeUnsafe(), hostContext_->host());
     assert(addon.env != nullptr);
   }
   napi_env env = addon.env;
@@ -163,7 +181,6 @@ bool CxxNodeApiHostModule::initializeNodeModule(jsi::Runtime &rt,
       napi_set_named_property(env, global, addon.generatedName.data(), exports);
   assert(status == napi_ok);
 
-  callstack::react_native_node_api::setCallInvoker(env, callInvoker_);
   return true;
 }
 

packages/host/cpp/CxxNodeApiHostModule.hpp

@@ -5,6 +5,7 @@
 #include <node_api.h>
 
 #include "AddonLoaders.hpp"
+#include "HermesNapiHost.hpp"
 
 namespace callstack::react_native_node_api {
 
@@ -37,6 +38,9 @@ class JSI_EXPORT CxxNodeApiHostModule : public facebook::react::TurboModule {
   };
   std::unordered_map<std::string, NodeAddon> nodeAddons_;
   std::shared_ptr<facebook::react::CallInvoker> callInvoker_;
+  // The hermes_napi_host integration passed to every env this module creates.
+  // Also retained process-wide, as the envs outlive this module on teardown.
+  std::shared_ptr<HostContext> hostContext_;
 
   using LoaderPolicy = PosixLoader; // FIXME: HACK: This is temporary workaround
                                     // for my lazyness (work on iOS and Android)