@crossbind/core-embind-napi 2.0.0-beta.62 → 2.0.0-beta.63

package/README.md

@@ -4,7 +4,7 @@ Runs the crossbind embind runtime inside a native Node.js addon, so the bindings
 WebAssembly and React Native also build `.node` addons for Node.js and Electron.
 
 <a href="https://www.npmjs.com/package/@crossbind/core-embind-napi">
-    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/core-embind-napi?style=for-the-badge" />
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/core-embind-napi/beta?style=for-the-badge" />
 </a>
 <a href="https://github.com/crossbind/crossbind/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/github/license/crossbind/crossbind?style=for-the-badge" />
@@ -12,15 +12,17 @@ WebAssembly and React Native also build `.node` addons for Node.js and Electron.
 
 ## Use
 
-Add it next to `crossbind` and build the native platform:
+Add it next to `crossbind` and build the addons of this machine's platform, or of every desktop
+platform:
 
 ```bash
-pnpm add -D crossbind @crossbind/core-embind-napi
-pnpm crossbind build -p darwin
+pnpm add -D crossbind@beta @crossbind/core-embind-napi@beta
+pnpm crossbind build -p host -e node -b release
+pnpm crossbind build -p darwin,linux,linuxmusl,win32 -e node -b release
 ```
 
-`dist/` then holds one addon per platform and architecture (`<name>.darwin-arm64.node`,
-`<name>.darwin-x64.node`) and the loader that picks one at runtime:
+`dist/` then holds one addon per platform and architecture (e.g. `<name>.darwin-arm64.node`,
+`<name>.linux-x64.node`, `<name>.win32-x64.node`) and the loader that picks one at runtime:
 
 ```js
 const initNative = require('./dist/<name>.native.cjs');
@@ -30,12 +32,14 @@ const { Native } = await initNative();
 
 crossbind resolves this package from your project; you never import it yourself. See the
 [Node.js integration guide](https://github.com/crossbind/crossbind/blob/main/docs/playbooks/integration/nodejs.md#native-addon-node-api) for
-requirements and current limits (macOS only, no `worker_threads` yet).
+requirements, Electron and current limits (no `worker_threads` yet).
 
 ## Contents
 
 - `cpp/` — the addon's CMake project and its Node-API entry point.
 - `js/loader.js` — the loader crossbind bundles into `dist/<name>.native.cjs`.
+- `js/addonPlatform.js` — tells glibc and musl Linux apart, so the loader picks the `linux` or `linuxmusl` addon.
+- `js/unpackedPath.js` — points a packaged Electron app's addon at the data its asar archive keeps unpacked.
 - `third_party/node-api-jsi/` — Microsoft's JSI implementation over Node-API (MIT), vendored at a
   pinned commit; provenance and local patches are in its README.
 

package/cpp/CMakeLists.txt

@@ -45,8 +45,10 @@ if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
     find_package(Threads REQUIRED)
     target_link_libraries(addon PRIVATE Threads::Threads ${CMAKE_DL_LIBS})
     target_link_options(addon PRIVATE "LINKER:--exclude-libs,ALL")
+    file(GLOB MUSL_LIBC "${CMAKE_SYSROOT}/lib/ld-musl-*.so.1")
     add_custom_command(TARGET addon POST_BUILD
         COMMAND "${CMAKE_COMMAND}" "-DNM=${CMAKE_NM}" "-DADDON=$<TARGET_FILE:addon>"
+            "-DUNVERSIONED_LIBRARIES=${MUSL_LIBC}"
             -P "${CMAKE_CURRENT_SOURCE_DIR}/check-undefined.cmake"
         VERBATIM)
 endif()
@@ -66,4 +68,9 @@ if(APPLE)
         string(REGEX REPLACE "^NODE_API_FUNC\\(([A-Za-z0-9_]+)\\).*" "\\1" func "${line}")
         target_link_options(addon PRIVATE "LINKER:-U,_${func}")
     endforeach()
+    # Only Node-API's entry points leave the addon: dyld merges exported weak definitions across the
+    # images of a process, so two addons would share inline state such as embind's registration guards.
+    target_link_options(addon PRIVATE
+        "LINKER:-exported_symbol,_napi_register_module_v1"
+        "LINKER:-exported_symbol,_node_api_module_get_api_version_v1")
 endif()

package/cpp/check-undefined.cmake

@@ -1,6 +1,20 @@
 # A Linux shared object may leave symbols undefined, and the loader binds functions lazily: an addon
 # that misses an archive loads, then dies at its first call into the missing code. Every undefined
 # symbol has to be a Node-API function or carry the version of a system library that defines it.
+# musl versions nothing, so a name its C library (UNVERSIONED_LIBRARIES) defines passes as it is.
+set(defined)
+foreach(library IN LISTS UNVERSIONED_LIBRARIES)
+    execute_process(
+        COMMAND "${NM}" -D --defined-only "${library}"
+        OUTPUT_VARIABLE exports
+        COMMAND_ERROR_IS_FATAL ANY)
+    string(REPLACE "\n" ";" export_lines "${exports}")
+    foreach(export_line IN LISTS export_lines)
+        if(export_line MATCHES " ([^ ]+)$")
+            list(APPEND defined "${CMAKE_MATCH_1}")
+        endif()
+    endforeach()
+endforeach()
 execute_process(
     COMMAND "${NM}" -D --undefined-only "${ADDON}"
     OUTPUT_VARIABLE listing
@@ -8,8 +22,14 @@ execute_process(
 string(REPLACE "\n" ";" lines "${listing}")
 set(unresolved)
 foreach(line IN LISTS lines)
-    if(line MATCHES "^ *U ([^@ ]+)$" AND NOT CMAKE_MATCH_1 MATCHES "^(napi|node_api)_")
-        list(APPEND unresolved "${CMAKE_MATCH_1}")
+    if(NOT line MATCHES "^ *U ([^@ ]+)$")
+        continue()
+    endif()
+    # A failed MATCHES clears CMAKE_MATCH_1, so the name is kept before the next one.
+    set(symbol "${CMAKE_MATCH_1}")
+    list(FIND defined "${symbol}" index)
+    if(NOT symbol MATCHES "^(napi|node_api)_" AND index EQUAL -1)
+        list(APPEND unresolved "${symbol}")
     endif()
 endforeach()
 if(unresolved)

package/cpp/src/node_api_module.cpp

@@ -82,9 +82,10 @@ std::string readString(napi_env env, napi_value value) {
     return result;
 }
 
-// start(dataPath) registers every EMSCRIPTEN_BINDINGS block of the addon into this environment's
-// embind runtime, so embind.js must already be loaded. A second call in the same environment is a
-// no-op: registering twice fails with "Cannot register public name ... twice".
+// start(dataPath, scope) registers every EMSCRIPTEN_BINDINGS block of the addon into this
+// environment's embind runtime, so embind.js must already be loaded. scope is the object that
+// runtime keeps its state on, which this addon's global() returns. A second call in the same
+// environment is a no-op: registering twice fails with "Cannot register public name ... twice".
 napi_value Start(napi_env env, napi_callback_info info) {
     void *existing = nullptr;
     NODE_API(napi_get_instance_data)(env, &existing);
@@ -100,17 +101,20 @@ napi_value Start(napi_env env, napi_callback_info info) {
         return nullptr;
     }
 
-    size_t argc = 1;
-    napi_value argv[1];
+    size_t argc = 2;
+    napi_value argv[2];
     NODE_API(napi_get_cb_info)(env, info, &argc, argv, nullptr, nullptr);
     const std::string dataPath = argc > 0 ? readString(env, argv[0]) : std::string();
+    napi_valuetype scopeType = napi_undefined;
+    if (argc > 1) NODE_API(napi_typeof)(env, argv[1], &scopeType);
+    napi_value scope = scopeType == napi_object ? argv[1] : nullptr;
 
     // An exception must not unwind through Node-API, which would end the process.
     try {
         auto state = std::make_unique<EnvState>();
         state->env = env;
         JSRuntimeApi::setCurrent(&state->api);
-        state->runtime = Microsoft::NodeApiJsi::makeNodeApiJsiRuntime(env, &state->api, [] {});
+        state->runtime = Microsoft::NodeApiJsi::makeNodeApiJsiRuntime(env, &state->api, [] {}, scope);
         // The environment owns it before any binding registers: registered functions point into it,
         // so it has to outlive a registration that fails halfway.
         EnvState *owned = state.release();

package/js/addonLocation.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+
+// A project's own build leaves the addon beside the loader. A package that publishes one addon per
+// platform ships it in <package>-<platform>-<arch>, an optional dependency whose main is the addon.
+export default function addonLocation({ dir, fileName, packageName, exists, resolve }) {
+    const beside = path.join(dir, fileName);
+    if (exists(beside) || !packageName) return beside;
+    try {
+        return resolve(packageName);
+    } catch {
+        return beside;
+    }
+}

package/js/addonPlatform.js

@@ -0,0 +1,19 @@
+// The platform part of an addon file name. Node reports musl and glibc systems alike as 'linux'; a
+// process linked against glibc names that glibc in its report header, a musl one does not.
+export default function addonPlatform(platform = process.platform, readReport = processReport) {
+    if (platform !== 'linux') return platform;
+    const header = readReport()?.header;
+    return !header || header.glibcVersionRuntime ? 'linux' : 'linuxmusl';
+}
+
+function processReport() {
+    if (!process.report) return undefined;
+    // Only the header is read; the network section can stall on DNS lookups.
+    const { excludeNetwork } = process.report;
+    process.report.excludeNetwork = true;
+    try {
+        return process.report.getReport();
+    } finally {
+        process.report.excludeNetwork = excludeNetwork;
+    }
+}

package/js/loader.js

@@ -1,12 +1,29 @@
 // Entry of the per-project loader crossbind bundles next to the native addons
 // (dist/<name>.native.cjs). It keeps the wasm build's initNative() contract, so the same app code
 // runs on either build.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
-import Module from '@crossbind/core-embind-jsi';
+import Module, { crossbindScope } from '@crossbind/core-embind-jsi';
 import systemConfig from 'crossbind/systemConfig';
+import addonPlatform from './addonPlatform.js';
+import addonLocation from './addonLocation.js';
+import missingAddonRemedy from './missingAddon.js';
+import stopOnExit from './stopOnExit.js';
+import unpackedPath from './unpackedPath.js';
 
-function addonFileName() {
-    return systemConfig.paths.addon.replace('{platform}', process.platform).replace('{arch}', process.arch);
+const platform = addonPlatform();
+const fill = (pattern) => pattern.replace('{platform}', platform).replace('{arch}', process.arch);
+const addonPackage = systemConfig.paths.addonPackage ? fill(systemConfig.paths.addonPackage) : null;
+
+function addonFile(config) {
+    return config.addonPath ?? addonLocation({
+        dir: __dirname,
+        fileName: fill(systemConfig.paths.addon),
+        packageName: addonPackage,
+        exists: fs.existsSync,
+        resolve: createRequire(__filename).resolve,
+    });
 }
 
 function loadAddon(file) {
@@ -14,38 +31,43 @@ function loadAddon(file) {
     try {
         process.dlopen(addon, file);
     } catch (error) {
-        throw new Error(
-            `crossbind: cannot load ${file} - build it with \`crossbind build -p ${process.platform} -a ${process.arch}\`.`,
-            { cause: error },
-        );
+        throw new Error(`crossbind: cannot load ${file} - ${fs.existsSync(file) ? error.message : missingAddonRemedy({ platform, arch: process.arch, addonPackage, published: Object.keys(systemConfig.env) })}.`, { cause: error });
     }
     return addon.exports;
 }
 
-function setEnv(dataPath, runtimeEnv) {
+function setEnv(dataPath, runtimeEnv = {}) {
+    const fillDataPath = (value) => String(value).replace('_CROSSBIND_DATA_PATH_', dataPath);
     // Build-time values are keyed by addon: a target-scoped value must not leak from one arch's
-    // build into another's. Values passed to initNative() win, as in the wasm runtime.
-    const env = { ...systemConfig.env[`${process.platform}-${process.arch}`], ...runtimeEnv };
-    Object.entries(env).forEach(([key, value]) => {
-        Module.Crossbind.setEnv(key, String(value).replace('_CROSSBIND_DATA_PATH_', dataPath), false);
+    // build into another's. They never replace a variable the process already has; values passed to
+    // initNative() do, as in the wasm runtime, even after a package entry booted the addon.
+    Object.entries(systemConfig.env[`${platform}-${process.arch}`] ?? {}).forEach(([key, value]) => {
+        Module.Crossbind.setEnv(key, fillDataPath(value), false);
+    });
+    Object.entries(runtimeEnv).forEach(([key, value]) => {
+        Module.Crossbind.setEnv(key, fillDataPath(value), true);
     });
 }
 
 let addon = null;
+let addonDataPath = null;
 
 function boot(config) {
-    const dataPath = config.dataPath ?? path.join(__dirname, 'data');
     // Loaded and started once per process: Node cannot unload an addon, and a second dlopen gets a
     // fresh environment whose start() would register every binding twice.
     if (!addon) {
-        const loaded = loadAddon(config.addonPath ?? path.join(__dirname, addonFileName()));
-        loaded.start(dataPath);
+        addonDataPath = config.dataPath ?? unpackedPath(path.join(__dirname, 'data'));
+        const loaded = loadAddon(addonFile(config));
+        // The embind runtime this bundle carries keeps its state on crossbindScope (crossbind's utils/scopedEmbind.js).
+        loaded.start(addonDataPath, crossbindScope);
         // Native values released after this (thread-local ones die inside exit()) must not call
         // back into the runtime.
-        process.once('exit', () => loaded.stop());
+        stopOnExit(() => loaded.stop());
         addon = loaded;
+    } else if (config.dataPath && config.dataPath !== addonDataPath) {
+        throw new Error(`crossbind: the addon started with its data at ${addonDataPath}; a process cannot move it to ${config.dataPath}.`);
     }
-    setEnv(dataPath, config.env);
+    setEnv(addonDataPath, config.env);
     return Module;
 }
 
@@ -63,6 +85,11 @@ export default function initNative(config = {}) {
     return booted;
 }
 
+// Loading an addon is synchronous, so a package entry boots it on require.
+initNative.sync = function sync(config = {}) {
+    return boot(config);
+};
+
 // The wasm runtime's contract: forget the booted module so the next call boots again. Native state
 // cannot be reset (Node cannot unload an addon), so that call resolves the same module.
 initNative.terminate = function terminate() {

package/js/missingAddon.js

@@ -0,0 +1,9 @@
+// What a process without its addon is told: install the addon package npm left out, learn that the package
+// publishes none for this machine, or build the addon an app makes itself. published lists the
+// <platform>-<arch> of every addon the package ships.
+export default function missingAddonRemedy({ platform, arch, addonPackage, published }) {
+    const target = `${platform}-${arch}`;
+    if (!addonPackage) return `build it with \`crossbind build -p ${platform} -a ${arch}\``;
+    if (!published.includes(target)) return `this package publishes no addon for ${target}, only for ${published.join(', ')}`;
+    return `install ${addonPackage}, which npm leaves out with --omit=optional; addons exist for ${published.join(', ')}`;
+}

package/js/stopOnExit.js

@@ -0,0 +1,15 @@
+// Every package bundles a loader of its own, and Node warns at an eleventh 'exit' listener, so the addons share one,
+// found by a registered symbol. Each boot moves it to the end of the list: the stops then run after every handler
+// registered so far, as a listener added at that boot would, since a call into an addon after its stop crashes.
+const ADDON_STOPS = Symbol.for('crossbind.addonStops.v1');
+
+export default function stopOnExit(stop, proc = process) {
+    if (!proc[ADDON_STOPS]) {
+        const stops = [];
+        proc[ADDON_STOPS] = { stops, onExit: () => stops.forEach((stopAddon) => stopAddon()) };
+    }
+    const { stops, onExit } = proc[ADDON_STOPS];
+    stops.push(stop);
+    proc.removeListener('exit', onExit);
+    proc.on('exit', onExit);
+}

package/js/unpackedPath.js

@@ -0,0 +1,5 @@
+// Native code cannot read inside an Electron asar archive, so a packaged app keeps what an addon
+// reads in <archive>.asar.unpacked beside it.
+export default function unpackedPath(file, isElectron = Boolean(process.versions.electron)) {
+    return isElectron ? file.replace(/\.asar(?=[\\/]|$)/, '.asar.unpacked') : file;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossbind/core-embind-napi",
-  "version": "2.0.0-beta.62",
+  "version": "2.0.0-beta.63",
   "description": "Node-API host for the crossbind embind runtime: native Node.js addons from the same C++ and Rust bindings.",
   "homepage": "https://github.com/crossbind/crossbind/tree/main/core/embind-napi#readme",
   "repository": {
@@ -14,7 +14,7 @@
     "third_party"
   ],
   "dependencies": {
-    "@crossbind/core-embind-jsi": "^2.0.0-beta.62"
+    "@crossbind/core-embind-jsi": "^2.0.0-beta.63"
   },
   "keywords": [
     "embind",

package/third_party/node-api-jsi/README.md

@@ -53,3 +53,7 @@ no `jsi-version.h` is needed.
   it. A string return went from 75 to 69 ns and a string argument from 95 to 84 ns; together with
   the direct BigInt read, a Rust `xxh64` call on 32 bytes with a BigInt seed and result went from
   141 to 110 ns. A million callbacks in one call peak at the same 70 MB.
+- `makeNodeApiJsiRuntime` takes an optional object that `global()` returns in place of the
+  global object. Each addon's loader bundles its own embind runtime, which keeps its `Module` and
+  the functions the addon calls by name on such an object, so addons of several packages run in
+  one process. The runtime's own lookups (`Error`, `Proxy`, `Symbol`) still use the global object.

package/third_party/node-api-jsi/src/NodeApiJsiRuntime.cpp

@@ -200,7 +200,8 @@ class NodeApiJsiRuntime : public jsi::Runtime, public crossbind::IDirectReads {
   NodeApiJsiRuntime(
       napi_env env,
       JSRuntimeApi *jsrApi,
-      std::function<void()> onDelete) noexcept;
+      std::function<void()> onDelete,
+      napi_value globalScope) noexcept;
   ~NodeApiJsiRuntime() override;
 
   jsi::ICast *castInterface(const jsi::UUID &interfaceUUID) override;
@@ -1116,6 +1117,7 @@ class NodeApiJsiRuntime : public jsi::Runtime, public crossbind::IDirectReads {
   struct CachedValue {
     NodeApiRefHolder Error;
     NodeApiRefHolder Global;
+    NodeApiRefHolder GlobalScope;
     NodeApiRefHolder HostObjectProxyHandler;
     NodeApiRefHolder ProxyConstructor;
     NodeApiRefHolder SymbolToString;
@@ -1214,7 +1216,8 @@ bool StringKey::EqualTo::operator()(
 NodeApiJsiRuntime::NodeApiJsiRuntime(
     napi_env env,
     JSRuntimeApi *jsrApi,
-    std::function<void()> onDelete) noexcept
+    std::function<void()> onDelete,
+    napi_value globalScope) noexcept
     : env_(env), jsrApi_(jsrApi), onDelete_(std::move(onDelete)) {
   NodeApiScope scope{*this};
   propertyId_.Error = makeNodeApiRef(
@@ -1266,6 +1269,10 @@ NodeApiJsiRuntime::NodeApiJsiRuntime(
 
   cachedValue_.Global =
       makeNodeApiRef(getGlobal(), NodeApiPointerValueKind::Object);
+  if (globalScope) {
+    cachedValue_.GlobalScope =
+        makeNodeApiRef(globalScope, NodeApiPointerValueKind::Object);
+  }
   cachedValue_.Error = makeNodeApiRef(
       getProperty(
           getNodeApiValue(cachedValue_.Global),
@@ -1337,7 +1344,9 @@ bool NodeApiJsiRuntime::drainMicrotasks(int maxMicrotasksHint) {
 #endif
 
 jsi::Object NodeApiJsiRuntime::global() {
-  return make<jsi::Object>(cachedValue_.Global->clone(*this));
+  const NodeApiRefHolder &global =
+      cachedValue_.GlobalScope ? cachedValue_.GlobalScope : cachedValue_.Global;
+  return make<jsi::Object>(global->clone(*this));
 }
 
 std::string NodeApiJsiRuntime::description() {
@@ -3737,8 +3746,10 @@ void NodeApiJsiRuntime::popPointerValueScope() noexcept {
 std::unique_ptr<jsi::Runtime> makeNodeApiJsiRuntime(
     napi_env env,
     JSRuntimeApi *jsrApi,
-    std::function<void()> onDelete) noexcept {
-  return std::make_unique<NodeApiJsiRuntime>(env, jsrApi, std::move(onDelete));
+    std::function<void()> onDelete,
+    napi_value globalScope) noexcept {
+  return std::make_unique<NodeApiJsiRuntime>(
+      env, jsrApi, std::move(onDelete), globalScope);
 }
 
 } // namespace Microsoft::NodeApiJsi

package/third_party/node-api-jsi/src/NodeApiJsiRuntime.h

@@ -15,7 +15,8 @@ namespace Microsoft::NodeApiJsi {
 std::unique_ptr<facebook::jsi::Runtime> makeNodeApiJsiRuntime(
     napi_env env,
     JSRuntimeApi *jsrApi,
-    std::function<void()> onDelete) noexcept;
+    std::function<void()> onDelete,
+    napi_value globalScope = nullptr) noexcept;
 
 struct NodeApiEnvScope {
   NodeApiEnvScope(napi_env env) : env_(env) {