feat: host allowlisted Node-API v8 addons

changelog.d/8523-node-api-host.md

@@ -0,0 +1,6 @@
+Added opt-in execution of prebuilt Node-API v8 addons on desktop/server targets,
+including exact package policy, authenticated relocatable sidecars,
+`require()`/`process.dlopen()` loading, narrow host symbol exports, GC-safe
+lifetimes, buffers, promises, async work, and threadsafe functions.
+Also aligned Windows `@parcel/watcher` facade event paths with the published
+`watcher.node` binding by hiding verbatim-path prefixes at the JavaScript boundary.

crates/perry-codegen/src/lower_call/native_table/node_core_process.rs

@@ -173,7 +173,7 @@ pub(super) const NODE_CORE_PROCESS_ROWS: &[NativeModSig] = &[
         method: "dlopen",
         class_filter: None,
         runtime: "js_process_dlopen",
-        args: &[],
+        args: &[NA_F64, NA_F64, NA_F64],
         ret: NR_F64,
     },
     NativeModSig {

crates/perry-ext-parcel-watcher/src/lib.rs

@@ -195,6 +195,20 @@ fn normalize_root(path: PathBuf) -> PathBuf {
     fs::canonicalize(&absolute).unwrap_or(absolute)
 }
 
+fn js_visible_path(path: &Path) -> String {
+    let path = path.to_string_lossy();
+    #[cfg(windows)]
+    {
+        if let Some(path) = path.strip_prefix(r"\\?\UNC\") {
+            return format!(r"\\{path}");
+        }
+        if let Some(path) = path.strip_prefix(r"\\?\") {
+            return path.to_owned();
+        }
+    }
+    path.into_owned()
+}
+
 unsafe fn read_ptr_string(ptr: *const StringHeader) -> Option<String> {
     if ptr.is_null() {
         return None;
@@ -461,7 +475,7 @@ fn event_array(events: &[ParcelEvent]) -> f64 {
     let rooted_array = scope.root_nanbox(f64::from_bits(JsValue::from_object_ptr(array).bits()));
     let (packed, shape) = build_object_shape(&["path", "type"]);
     for event in events {
-        let path = alloc_string(&event.path.to_string_lossy());
+        let path = alloc_string(&js_visible_path(&event.path));
         let path = scope.root_nanbox(f64::from_bits(
             JsValue::from_string_ptr(path.as_raw()).bits(),
         ));
@@ -862,6 +876,19 @@ pub unsafe extern "C" fn js_parcel_watcher_get_events_since(
 mod tests {
     use super::*;
 
+    #[cfg(windows)]
+    #[test]
+    fn event_paths_do_not_expose_windows_verbatim_prefixes() {
+        assert_eq!(
+            js_visible_path(Path::new(r"\\?\C:\project\src\index.ts")),
+            r"C:\project\src\index.ts"
+        );
+        assert_eq!(
+            js_visible_path(Path::new(r"\\?\UNC\server\share\index.ts")),
+            r"\\server\share\index.ts"
+        );
+    }
+
     #[test]
     fn coalescing_matches_parcel_batch_semantics() {
         let temp = tempfile::tempdir().unwrap();

crates/perry-hir/src/lower/expr_call/native_module/process_module.rs

@@ -143,19 +143,13 @@ pub(super) fn try_process_module_methods(
                     }));
                 }
                 "dlopen" => {
-                    // #1409: process.dlopen(module, filename, flags?)
-                    // is Node's native-addon (.node) loader. Perry
-                    // statically links every dependency at compile
-                    // time — there's no dynamic loader to call.
-                    // Returning undefined is the closest no-op:
-                    // call sites that probe for the function before
-                    // attempting to load an addon (a common pattern
-                    // in optional-dep wrappers) see typeof "function"
-                    // and a "loaded" non-error, then fall back to
-                    // their pure-JS path. Real addon-loading
-                    // attempts will surface as the addon's exports
-                    // being undefined downstream.
-                    return Ok(Ok(Expr::Undefined));
+                    return Ok(Ok(Expr::NativeMethodCall {
+                        module: "process".to_string(),
+                        class_name: None,
+                        object: None,
+                        method: "dlopen".to_string(),
+                        args,
+                    }));
                 }
                 "hasUncaughtExceptionCaptureCallback" => {
                     return Ok(Ok(Expr::NativeMethodCall {

crates/perry-runtime/Cargo.toml

@@ -239,7 +239,7 @@ ohos-napi = []
 wasm-host = []
 # #8523: opt-in Node-API ABI and host-core symbols. The compiler enables this
 # only for an allowlisted native-addon graph, preserving the default size gate.
-node-api-host = []
+node-api-host = ["dep:hex", "dep:sha2"]
 # #6559: runtime dynamic-code evaluation — `new Function(p1, …, body)` with a
 # RUNTIME-constructed body parses the generated source with perry-parser (SWC)
 # and runs it through a scoped tree-walking interpreter (`src/dyn_eval/`).
@@ -292,6 +292,8 @@ temporal_rs = { version = "0.2.3", default-features = false, features = ["std",
 
 serde.workspace = true
 serde_json.workspace = true
+hex = { workspace = true, optional = true }
+sha2 = { version = "0.11", optional = true }
 # TLS client identity callbacks run from the external net archive, before the
 # stdlib TLS module is necessarily linked. Keep the legacy peer-certificate
 # object builder in the runtime so that callback path has no stdlib symbol

crates/perry-runtime/build.rs

@@ -535,10 +535,36 @@ fn generate_single_byte_encodings(out_dir: &str) {
 
 fn main() {
     println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=src/node_api_host/symbols.txt");
     println!("cargo:rerun-if-changed=../perry-dispatch/src/lib.rs");
+    println!("cargo:rerun-if-env-changed=TARGET");
+    println!(
+        "cargo:rustc-env=PERRY_RUNTIME_TARGET={}",
+        std::env::var("TARGET").expect("TARGET not set by Cargo")
+    );
     emit_runtime_build_id();
 
     let out_dir = std::env::var("OUT_DIR").expect("OUT_DIR not set");
+    let symbols = std::fs::read_to_string("src/node_api_host/symbols.txt")
+        .expect("read Node-API symbol inventory");
+    let names = symbols
+        .lines()
+        .map(str::trim)
+        .filter(|name| !name.is_empty() && !name.starts_with('#'))
+        .collect::<Vec<_>>();
+    let mut anchors = format!(
+        "#[used]\nstatic NODE_API_HOST_SYMBOL_ANCHORS: [NodeApiSymbol; {}] = [\n",
+        names.len()
+    );
+    for name in names {
+        writeln!(anchors, "    NodeApiSymbol(super::{name} as *const ()),").unwrap();
+    }
+    anchors.push_str("];\n");
+    std::fs::write(
+        std::path::Path::new(&out_dir).join("node_api_host_symbol_anchors.rs"),
+        anchors,
+    )
+    .expect("write Node-API symbol anchors");
     generate_single_byte_encodings(&out_dir);
     let stubs_dest = std::path::Path::new(&out_dir).join("perry_ui_harmonyos_stubs.rs");
     let manifest_dest = std::path::Path::new(&out_dir).join("perry_stub_manifest.rs");

crates/perry-runtime/src/buffer/detach.rs

@@ -84,7 +84,12 @@ pub fn detach_array_buffer(addr: usize) {
     // Typed-array views (`new Float32Array(ab, ...)`) record their backing in
     // a separate side table; zero those lengths too.
     crate::typedarray_view::zero_views_of_detached_backing(addr);
-    decommit_payload_pages(buffer_data_mut(buf), capacity as usize);
+    // External ArrayBuffers borrow addon-owned memory. Detaching severs the
+    // JavaScript view but must never decommit pages which Perry did not
+    // allocate; the registered finalizer still receives the original pointer.
+    if !super::is_foreign_backed_buffer(addr) {
+        decommit_payload_pages(buffer_data_mut(buf), capacity as usize);
+    }
 }
 
 /// Release the page-aligned interior of a detached payload back to the OS.

crates/perry-runtime/src/buffer/header.rs

@@ -652,6 +652,10 @@ fn foreign_backing(addr: usize) -> Option<usize> {
     FOREIGN_BACKING_REGISTRY.with(|r| r.borrow().get(&addr).copied())
 }
 
+pub(crate) fn is_foreign_backed_buffer(addr: usize) -> bool {
+    foreign_backing(addr).is_some()
+}
+
 /// Post-trace registry pruning (mirrors the #6010 Map/Set pattern): collect
 /// registered buffers whose header is genuinely dead so the sweep subphase
 /// can drop their side-table state. All buffers are TENURED old-arena

crates/perry-runtime/src/buffer/mod.rs

@@ -57,7 +57,7 @@ pub use header::{
 };
 pub(crate) use header::{
     buffer_alloc_foreign, collect_dead_registered_buffers_post_trace,
-    finalize_collected_dead_buffer,
+    finalize_collected_dead_buffer, is_foreign_backed_buffer,
 };
 #[cfg(test)]
 pub(crate) use header::{test_data_view_registry_len, test_shared_array_buffer_registry_len};

crates/perry-runtime/src/gc/dead_owner.rs

@@ -401,6 +401,12 @@ pub(super) const DEAD_KEY_PRUNES: &[DeadKeyPrune] = &[
         owner: DeadKeyOwner::Any,
         prune: crate::proxy::prune_dead_reflect_metadata_targets,
     },
+    #[cfg(feature = "node-api-host")]
+    DeadKeyPrune {
+        table: "NODE_API_OBJECT_METADATA",
+        owner: DeadKeyOwner::Any,
+        prune: crate::node_api_host::prune_dead_object_meta_owners,
+    },
 ];
 
 fn fan_out(

crates/perry-runtime/src/lib.rs

@@ -488,6 +488,8 @@ pub(crate) mod stdlib_pump {
     #[no_mangle]
     pub extern "C" fn js_run_stdlib_pump() {
         crate::promise::js_native_async_process_pending();
+        #[cfg(feature = "node-api-host")]
+        crate::node_api_host::process_pending();
         crate::os::js_process_signal_drain();
         // Drain the tty resize-pending flag (#347 Phase 3). Lives in
         // perry-runtime, not stdlib, so it runs even when stdlib isn't
@@ -533,6 +535,10 @@ pub(crate) mod stdlib_pump {
     /// async ops, etc.). Returns 0 if perry-stdlib is not linked.
     #[no_mangle]
     pub extern "C" fn js_stdlib_has_active_handles() -> i32 {
+        #[cfg(feature = "node-api-host")]
+        if crate::node_api_host::has_active_work() {
+            return 1;
+        }
         if crate::promise::js_native_async_has_active() != 0 {
             return 1;
         }