@napi-rs/cli 3.10.4 → 3.10.6

package/docs/build.md

@@ -58,3 +58,4 @@ new NapiCli().build({
 | features          | --features,-F         | string[]            | false    |         | Space-separated list of features to activate                                                                                                                                                                                                                                                                                                                                                                         |
 | allFeatures       | --all-features        | boolean             | false    |         | Activate all available features                                                                                                                                                                                                                                                                                                                                                                                      |
 | noDefaultFeatures | --no-default-features | boolean             | false    |         | Do not activate the `default` feature                                                                                                                                                                                                                                                                                                                                                                                |
+| ohosSign          | --ohos-sign           | boolean             | false    | true    | Whether to self-sign the built binary for OpenHarmony targets by injecting a `.codesign` fs-verity section, so the `.so` can be loaded on HarmonyOS devices. Only works with `*-unknown-linux-ohos` targets                                                                                                                                                                                                          |

package/docs/wasi.md

@@ -390,12 +390,16 @@ override the default in either direction:
 
 ## Shared async runtime hosts
 
-`CurrentThread` is the only async-runtime flavor on WebAssembly, for both
-`wasm32-wasip1` and `wasm32-wasip1-threads`. An addon built with the
-`napi-async-runtime` crate therefore makes no progress until a JavaScript task
-host publishes its runnable turns, and its timers never fire until a timer host
-relays them. Set `napi.wasm.asyncRuntime` and the generated loaders install
-both for you:
+`CurrentThread` is the default async-runtime flavor on every WebAssembly
+target, and the only flavor on threadless `wasm32-wasip1`. On
+`wasm32-wasip1-threads` an addon may select `MultiThread` instead — always an
+explicit host act, never a default (see the crate's "Running MultiThread on
+`wasm32-wasip1-threads`" section).
+
+A `CurrentThread` addon built with the `napi-async-runtime` crate makes no
+progress until a JavaScript task host publishes its runnable turns, and its
+timers never fire until a timer host relays them. Set `napi.wasm.asyncRuntime`
+and the generated loaders install both for you:
 
 ```json
 {
@@ -407,8 +411,16 @@ both for you:
 }
 ```
 
-This affects WASI output only. Native `.node` bindings run the `MultiThread`
-flavor on real threads and need no JavaScript host.
+This affects WASI output only. Native `.node` bindings default to the
+`MultiThread` flavor on real threads and need no JavaScript host.
+
+Keep the flag on even for a `wasm32-wasip1-threads` addon that configures
+`MultiThread`. The loaders cannot see the flavor, so they install both hosts
+unconditionally — and a `MultiThread` runtime never uses either: its futures
+run on the Rayon pool instead of published host turns, and its timers come from
+the executor-owned heap plus a timekeeper thread. The installed task host is an
+unref'd threadsafe function, so it does not hold the event loop open. That is
+what lets one artifact choose its flavor at runtime.
 
 With the flag on:
 
@@ -526,3 +538,334 @@ would never boot and the caller would deadlock waiting for it. With a
 pre-created pool, spawning is only a message to an already-running worker,
 and if the pool is exhausted the fallback allocates a fresh worker that
 boots once the spawning parent returns to its event loop.
+
+## Detecting the threaded target from Rust
+
+rustc gives you nothing to tell the two WASI targets apart. `rustc --print
+cfg` emits an _identical_ set for `wasm32-wasip1` and
+`wasm32-wasip1-threads` — same `target_arch`, same `target_os`, same
+`target_env = "p1"` — and `target_feature = "atomics"` is set for neither,
+because the wasm `atomics` feature is still unstable and the stable channel
+keeps unstable target features out of the cfg set
+([rust-lang/rust#77839](https://github.com/rust-lang/rust/issues/77839)).
+Passing `-C target-feature=+atomics` does not change that: rustc warns that
+the feature is unstable and the cfg still does not appear. Only the exact
+cargo `TARGET` answers the question, and only a build script can read it.
+
+An addon crate gets the answer for free. `napi_build::setup()` emits
+`cfg(napi_wasi_threads)` when — and only when — the crate is being compiled
+for `wasm32-wasip1-threads`, so the addon can write:
+
+```rust
+#[cfg(napi_wasi_threads)]
+const WORKERS: usize = 4;
+#[cfg(not(napi_wasi_threads))]
+const WORKERS: usize = 1;
+```
+
+`setup()` also prints the matching `cargo::rustc-check-cfg` line on _every_
+target, so `#[cfg(napi_wasi_threads)]` is a known cfg everywhere and never
+trips the `unexpected_cfgs` lint on the targets where it is not set.
+
+A build-script cfg is crate-local: it reaches the crate whose `build.rs`
+printed it and nothing else. Another crate in the same graph that needs the
+distinction therefore needs its own build script — which is why `napi` and
+`napi-async-runtime` each carry one:
+
+```rust
+// build.rs
+fn main() {
+  println!("cargo::rustc-check-cfg=cfg(my_wasi_threads)");
+  if std::env::var("TARGET").as_deref() == Ok("wasm32-wasip1-threads") {
+    println!("cargo::rustc-cfg=my_wasi_threads");
+  }
+}
+```
+
+Use the older single-colon `cargo:` form if the crate's `rust-version` is
+below 1.77.
+
+Absence has to be the conservative branch. The cfg is permission to use
+shared memory and real threads, never a requirement that something be
+configured: a plain `cargo build`, `cargo test`, or rust-analyzer run — no
+`napi build`, no CLI, no `RUSTFLAGS` — must still compile a correct crate on
+the `not(...)` side. Nothing outside the build script can set it, so a
+mistake there is silent.
+
+### Third-party locks
+
+`parking_lot_core`, the lock core under `parking_lot` and `dashmap`, does not
+follow this rule, and an addon can pull it in without ever naming it. Its
+only threaded-wasm parker is gated on the crate's `nightly` feature _and_
+`target_feature = "atomics"` (0.9.12, `src/thread_parker/mod.rs:69`), so on
+stable the cascade falls through to the wasm stub, whose `prepare_park` is
+`panic!("Parking not supported on this platform")`
+(`src/thread_parker/wasm.rs:26`). The build succeeds and the addon dies at the
+first _contended_ lock, on a target whose `std` has fully working threads.
+
+Upstream
+[Amanieu/parking_lot#529](https://github.com/Amanieu/parking_lot/pull/529)
+adds a `std::sync::Mutex` and `Condvar` parker for WASI, but its selection arm
+keys on `target_feature = "atomics"` as well, so it cannot be reached on
+stable either. Until that is resolved there are two options:
+
+- Keep `parking_lot` and `dashmap` out of the `wasm32-wasip1-threads`
+  dependency graph, or
+- route the whole graph through a `parking_lot_core` that detects the triple
+  in its own `build.rs`, exactly as above. napi-rs maintains that fork and
+  publishes it as `lock_api-napi` 0.4.15, `parking_lot_core-napi` 0.9.13 and
+  `parking_lot-napi` 0.12.6; each keeps the upstream `[lib] name`, so
+  `use parking_lot::Mutex` still compiles. A transitive user such as
+  `dashmap` is only reachable through `[patch.crates-io]`, and the only
+  form cargo accepts is a git pin on the fork's `wasi-threads-parker`
+  branch, which still carries the _upstream_ package names. Pin the exact
+  revision rather than the branch, so the lock stays reproducible:
+
+  ```toml
+  [patch.crates-io.parking_lot_core]
+  git = "https://github.com/napi-rs/parking_lot"
+  rev = "ac046ba44e72159e90e36b7323b1058ba1d48ad2"
+  ```
+
+  The published `*-napi` crates cannot be named in such an entry. Cargo
+  rejects a crates.io package replacing another crates.io package, because
+  a patch must point to a different source:
+
+  ```toml
+  [patch.crates-io]
+  parking_lot_core = { package = "parking_lot_core-napi", version = "0.9.13" }
+  ```
+
+  ```text
+  error: patch for `parking_lot_core-napi` points to the same source, but
+  patches must point to different sources
+  ```
+
+  Over a path or git source the entry resolves, and is then dropped. Cargo
+  does honour `package =` — it selects that package from the replacement
+  source — but the selected package keeps its own name, and a dependency on
+  `parking_lot_core` is satisfied only by a package named
+  `parking_lot_core`. The fork's `master` carries the renamed manifests
+  (`name = "parking_lot_core-napi"`), so pointing the rename at it gives:
+
+  ```toml
+  [patch.crates-io.parking_lot_core]
+  git = "https://github.com/napi-rs/parking_lot"
+  rev = "e243c6c43832c151bce2887fcb209b5b8b72ac61" # master
+  package = "parking_lot_core-napi"
+  ```
+
+  ```text
+  warning: patch `parking_lot_core-napi v0.9.13 (…?rev=e243c6c4…)` was not
+  used in the crate graph
+  ```
+
+  The lock then records it under `[[patch.unused]]` and `dashmap` keeps
+  building against stock `parking_lot_core` 0.9.12 — the panicking parker.
+
+Verified on the patched core: a contended probe under `wasmtime run -S
+threads` — `Mutex`, `Condvar`, `RwLock`, `park_until`, `notify_all`, `DashMap`
+— reports `ALL OK` with zero parking stubs left in the module, and rolldown's
+threaded WASI artifact passed its stability lane 3 of 3.
+
+## Shared memory growth on `wasm32-wasip1-threads`
+
+Every thread of a threaded WASI addon runs on one shared `WebAssembly.Memory`.
+V8 updates that memory's size only on the thread that grew it. Every other
+thread keeps checking `memory.fill`, `memory.copy` and atomics against its old
+size until it handles V8's grow interrupt, and on a host without V8's wasm trap
+handler (`--disable-wasm-trap-handler`, or `--wasm-enforce-bounds-checks`) it
+checks every load and store that way. Such a thread traps with `memory access
+out of bounds` on heap pages another thread just grew. V8 fixed this in
+[v8/v8@3424101](https://github.com/v8/v8/commit/34241014663390c72e08c123faef6fedf395be8e);
+napi-rs works around it until the hosts it supports ship that fix.
+
+The workaround is on for every addon built for exactly `wasm32-wasip1-threads`
+with `napi` and `napi_build::setup()`. There is nothing to call or configure:
+
+```text
+malloc / free / calloc / realloc / ...   (Rust's System, wasi-libc, emnapi's `malloc` export)
+  -> napi's __wrap_* (napi-build links with --wrap)
+       LOCK (spin; sched_yield every 64 spins; never memory.atomic.wait)
+         another thread saw a larger memory? memory.grow(0)   refresh this thread
+         dlmalloc
+           -> __wrap_sbrk: the reserve first, else grow >= 16 MiB,
+                           refresh and publish the new size
+       UNLOCK
+
+task poll, block_on poll, blocking closure      (napi-async-runtime)
+AsyncTask compute, AsyncRuntimeTask poll,       (napi)
+napi's default Tokio runtime and spawn_blocking
+  -> another thread saw a larger memory? memory.grow(0)   one atomic load + one thread-local load
+```
+
+- **The allocator lock.** `napi_build::setup()` links with `--wrap` for the 10
+  entries of wasi-libc's dlmalloc and for `sbrk`, so every allocation reaches a
+  `__wrap_*` function in `napi`. It takes one lock, refreshes the thread's size
+  when another thread has seen a larger memory, and runs the real call. The
+  thread that grows the memory publishes the new size before it unlocks, so
+  every thread is current before dlmalloc touches a byte for it. The lock also
+  covers calloc's zero fill and realloc's copy, and C code that calls `sbrk`
+  itself takes it too. It spins like dlmalloc's own lock, so it is safe on a
+  browser main thread, where `memory.atomic.wait` traps.
+- **The handoff refresh.** Memory can reach a thread without an allocation
+  there: a task that allocated on one thread resumes on another, or a closure
+  runs on a pool thread. `napi-async-runtime` and napi's own cross-thread
+  entries check the size before they run such work.
+- **The heap break.** dlmalloc first uses the pages between the module's own
+  memory and the memory the loader created (`napi.wasm.initialMemory`): they
+  exist on every thread from the start, so they never need a refresh, and
+  nothing grows until they are used. Past them it only uses pages it grew
+  itself, at least 16 MiB at a time, so pages another allocator grew never
+  reach dlmalloc. The heap never reaches 2 GiB: an allocation that would pass
+  it fails. Node's `node:wasi` (v24 and later) answers `EINVAL` to
+  `clock_time_get` and `fd_seek` when a pointer is at or above 2 GiB.
+
+The threaded `.wasm` exports `malloc` and `free` as before (`@emnapi/core`
+calls them); they now go through the lock. It also exports the 11 `__wrap_*`
+functions, `napi_wasm_heap_sync_stat`, `napi_wasm_thread_crashed` and
+`napi_wasm_thread_crash_flag_address`, because Rust exports every
+`#[no_mangle]` function of a cdylib. They are not an API.
+The threadless `wasm32-wasip1` artifact has none of this.
+
+The addon's `napi-build` must be the same package as `napi`'s own
+build-dependency (a path or git `napi` needs `napi-build` from the same
+checkout). With two copies, the addon's `setup()` does not wrap the allocator,
+and the link fails with an undefined symbol,
+`napi_wasi_heap_sync_needs_napi_build_setup_with_wasi_heap_sync`.
+
+### Test counters
+
+`napi_wasm_heap_sync_stat(index)` returns one counter as a `u32`. It is for
+tests and diagnosis; `examples/wasi-heap-sync/stress.mjs` and rolldown's
+threaded stress test read it by index, so an index keeps its meaning.
+
+| index     | value                                                                                       |
+| --------- | ------------------------------------------------------------------------------------------- |
+| 0         | heap growths: `memory.grow(n > 0)` calls by `__wrap_sbrk`                                   |
+| 1         | refreshes after taking the lock (including each thread's first)                             |
+| 2         | blocks that ended past the thread's refreshed size when dlmalloc returned them; must stay 0 |
+| 3         | the heap break, in pages (rounded up); 0 before the first `sbrk`                            |
+| 4         | `__heap_end` (where the break starts), in pages; 0 before the first `sbrk`                  |
+| 5         | refreshes at handoffs (napi-async-runtime and napi's cross-thread entries)                  |
+| any other | `u32::MAX`                                                                                  |
+
+With the loader's default memory a small load reads 0 at index 0: the heap fits
+in the reserve and never grows.
+
+### Cost
+
+Measured in rolldown on its copy of this code, before napi-rs took it over:
+the same lock and break. napi's copy adds the check that keeps other
+allocators' pages out of the break, and keeps the shared size in a cache line
+of its own. Release wasm, Node 24.21 on arm64, 10 interleaved rounds, medians
+in ms:
+
+| load                              | before the lock | with the lock | cost |
+| --------------------------------- | --------------- | ------------- | ---- |
+| MultiThread, 16 builds            | 310.5           | 334.5         | 8%   |
+| MultiThread, 16 builds, JS plugin | 1518            | 1589.5        | 5%   |
+| MultiThread, parse 16x3           | 218.5           | 241           | 10%  |
+| CurrentThread, parse 16x3         | 216.5           | 240.5         | 11%  |
+| CurrentThread, transform 16x3     | 623.5           | 640           | 3%   |
+
+"Before the lock" already grew the heap at least 16 MiB at a time. That part
+of the workaround had made the same loads 1.6-3.2x faster than growing in
+dlmalloc's own small steps (transform: no change), and the lock keeps most of
+that gain. The handoff check alone measured at noise level. Other workloads,
+x64, Linux, Windows and browsers are not measured.
+
+### Opting out
+
+Pass `--cfg napi_wasi_no_heap_sync` in the target rustflags, for example
+`RUSTFLAGS="--cfg napi_wasi_no_heap_sync" napi build --target
+wasm32-wasip1-threads`. `napi` then leaves out the wrappers and its handoff
+checks, and `napi-build` leaves out the `--wrap` link arguments; both read the
+same cfg, so they cannot come apart. `napi-async-runtime`'s check stays, but it
+never fires: nothing publishes a larger size. `napi_build::setup()` declares
+the cfg, so addon code can test `#[cfg(napi_wasi_no_heap_sync)]` too. Without
+the workaround the trap above comes back on hosts without the V8 fix.
+
+### What it does not cover
+
+- A `#[global_allocator]` that calls `memory.grow` itself (mimalloc's WASI
+  build, talc, lol_alloc, the `dlmalloc` crate) is not locked, and its growth
+  is never published. One that ends in libc `malloc`, like std's `System`, is
+  locked.
+- Memory that reaches a running thread mid-poll (a channel message, an `Arc`)
+  and is touched there before that thread's next allocation or handoff, after
+  another thread grew the memory. Below the reserve nothing grows. A
+  threadsafe-function call, deferred or async work delivered on the JavaScript
+  thread is covered: between taking it off its queue and calling back into the
+  module, emnapi runs JavaScript frames (`napi_open_handle_scope`,
+  `napi_get_reference_value`, `emnapi_is_node_binding_available`,
+  `_emnapi_callback_into_module`), and a JavaScript frame handles V8's grow
+  interrupt. What remains there is emnapi's own read of the queue node in C, on
+  hosts without the trap handler.
+- Work on threads the addon starts or runs itself: a runtime passed to
+  `create_custom_tokio_runtime`, direct `tokio::task::spawn_blocking` calls,
+  and a host's own threads outside `napi-async-runtime`'s scheduler.
+- A thread that crashes while it holds the lock leaves the others spinning, as
+  a crash inside dlmalloc's own lock always did.
+
+## Shutdown polls never wait
+
+A loader's `dispose()` runs the environment cleanup in two phases with a poll
+between them: `napi_prepare_wasm_env_cleanup_begin`, then
+`napi_wasm_runtime_work_pending` once per event-loop turn until it answers 0,
+then `napi_prepare_wasm_env_cleanup_finish`. The poll never blocks, and that
+includes locks: when a lock the answer is read under is held by another
+thread, it answers 1 and the loader polls again on its next turn. On
+`wasm32-wasip1-threads` a thread that traps unwinds nothing, so a lock it held
+stays held; a poll that waited for it would park the JavaScript thread in
+`memory.atomic.wait32` for good, before the loader can see the crash. A custom
+`AsyncRuntime` backend must keep the same rule in `shutdown_work_pending`. The
+process-exit teardown has no turns to give and makes the single blocking call,
+`napi_prepare_wasm_env_cleanup`.
+
+The two phases themselves may wait. With `napi-async-runtime` on
+`wasm32-wasip1-threads` they wait in 1 ms slices on the JavaScript thread, and
+between slices read the addon's crash flag: one 4-byte word in the shared wasm
+memory. Once it is set, the next slice traps, and the loader reports the crash
+instead of hanging.
+
+The generated worker sets that word itself, with `Atomics.store`, so it needs
+no wasm instance:
+
+```
+loader thread                            pool worker
+─────────────                            ───────────
+instantiate; in beforeInit:
+  napi_wasm_thread_crash_flag_address()
+  view = Int32Array(memory, address, 1)
+spawn → Worker({ workerData: {           load → start → run
+  crashFlag, crashReport,                  ...
+  addonCrashFlag: view } })              dies (trap, error, failed load):
+  ...                                      write crashReport
+cleanup waits in slices ◄──────────────    Atomics.store(crashFlag, 1)
+  view word is 1 → trap                    Atomics.store(addonCrashFlag, 1)
+catch → crash rejection                    emnapi's own error report
+```
+
+- The Node worker gets the view in `workerData`. The browser worker gets it by
+  `postMessage`: the browser pool is created before the wasm is instantiated,
+  so the loader posts it to each pool worker after `beforeInit`, and to a
+  worker created later right away.
+- The loader's crash flag always goes up first, so when the trap reaches the
+  loader it already sees the crash.
+- A worker whose own setup throws (`@napi-rs/wasm-runtime` cannot be
+  resolved, say) raises both flags too, then fails as before.
+- A worker that fails while it loads — after the thread spawn that created it
+  already returned — raises the flag the same way. `napi_wasm_thread_crashed`,
+  which stores into the same word, is only the fallback for a worker that has
+  an instance but no view.
+- An addon built with an older napi has no address export: the loader passes
+  no view, and the waits stay unbounded, as before.
+
+What still cannot raise the flag: a worker that fails before any of its own
+code runs, or that is killed from outside — the `Worker` cannot start, runs
+out of memory, or is terminated by its resource limits. The loader sees those
+only through the worker's `'error'` or `'exit'` event, which needs a turn of
+its event loop, so a cleanup wait already in progress keeps waiting. The same
+holds before `beforeInit`: a thread spawned while the wasm initializes gets a
+worker with no view.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@napi-rs/cli",
-  "version": "3.10.4",
+  "version": "3.10.6",
   "description": "Cli tools for napi-rs",
   "author": "LongYinan <lynweklm@gmail.com>",
   "homepage": "https://napi.rs/",
@@ -87,7 +87,7 @@
     "emnapi": "^2.0.0-alpha.4",
     "empathic": "^2.0.1",
     "env-paths": "^4.0.0",
-    "oxc-parser": "^0.150.0",
+    "oxc-parser": "^0.152.0",
     "tsdown": "^0.23.0",
     "tslib": "^2.8.1"
   },