@napi-rs/cli 3.10.4 → 3.10.5

package/src/api/__tests__/templates.spec.ts

@@ -1123,6 +1123,241 @@ for (const { name, code } of eagerWasiLoaderCases) {
   })
 }
 
+// `napi_prepare_wasm_env_cleanup` waits: it returns only once the addon's async
+// runtime has quiesced, and on a threaded artifact the work it waits for can be
+// waiting for a JavaScript turn from the very thread the export runs on — which
+// never comes, because that thread is inside the export. The addon exposes the
+// same teardown as `…_begin` / `napi_wasm_runtime_work_pending` / `…_finish` so
+// a loader can put real turns in the middle. Every shape that can yield has to
+// use it, and every shape has to keep working against an addon that has no such
+// exports.
+const TWO_PHASE_BARRIER_BY_FLAVOR = {
+  eager: {
+    detect:
+      /if \(typeof begin !== 'function' \|\|\s*typeof finish !== 'function'\) \{/,
+    poll: '}, __WASM_RUNTIME_WORK_POLL_INTERVAL_MS)',
+    finish: '.then(finishCleanup, finishCleanup)',
+    fallback: '__prepareWasmEnvCleanup()',
+    report: '__reportUnreachedWasmEnvSettlements()',
+    // The closer a caller that cannot yield uses to end a parked handshake,
+    // and the point at which the poll publishes it.
+    parked: '__finishParkedWasmEnvCleanup',
+    publishParked: '__finishParkedWasmEnvCleanup = finishCleanup',
+    clearParked: '__finishParkedWasmEnvCleanup = undefined',
+  },
+  deferred: {
+    detect:
+      /if \(typeof __begin !== 'function' \|\|\s*typeof __finish !== 'function'\) \{/,
+    poll: '}, __WASM_RUNTIME_WORK_POLL_INTERVAL_MS)',
+    finish: `return __pollWasmRuntimeWork(__workPending).then(
+      __finishEnvCleanup,
+      __finishEnvCleanup,
+    )`,
+    fallback: '__prepareEnvCleanup()',
+    report: '__reportUnreachedSettlements()',
+    parked: '__finishParkedEnvCleanup',
+    publishParked: '__finishParkedEnvCleanup = __finishEnvCleanup',
+    clearParked: '__finishParkedEnvCleanup = undefined',
+  },
+} as const
+
+for (const { name, code } of wasiLoaderCases) {
+  const barrier =
+    TWO_PHASE_BARRIER_BY_FLAVOR[
+      code.includes(EAGER_ROLLBACK_SIGNATURE) ? 'eager' : 'deferred'
+    ]
+  test(`WASI loader polls the two-phase wasm env cleanup: ${name}`, (t) => {
+    t.true(
+      code.includes('napi_prepare_wasm_env_cleanup_begin'),
+      'loader must start the teardown without joining',
+    )
+    t.true(
+      code.includes('napi_wasm_runtime_work_pending'),
+      'loader must poll the runtime between the two halves; without it there is nothing to wait on',
+    )
+    t.true(
+      code.includes('napi_prepare_wasm_env_cleanup_finish'),
+      'loader must still join: finish is the call that owes quiescence',
+    )
+    // Optional, exactly like every other export in this teardown: an addon
+    // built against a napi crate that predates the split keeps the single
+    // blocking call.
+    t.regex(code, barrier.detect, 'the split must be feature-detected')
+    t.true(
+      code.includes(barrier.fallback),
+      'a loader that finds no split must fall back to the single call',
+    )
+    // Unbounded, and deliberately so. The only way to end the poll early is to
+    // call `…_finish`, which joins on the JavaScript thread — the very thread
+    // the work it joins may be waiting for a turn from — so a budget would not
+    // end that wait, it would only move it somewhere the thread can no longer
+    // be reached. Same reason the async-work drain has no deadline. A host that
+    // breaks the "no blocking closure may wait on a JavaScript turn" rule keeps
+    // its disposal promise pending instead of wedging the thread.
+    t.false(
+      code.includes('__WASM_RUNTIME_DRAIN_TURNS'),
+      'the poll must not carry a turn budget',
+    )
+    t.is(
+      code.split('for (;;) {').length - 1,
+      1,
+      'the poll must be an unbounded loop',
+    )
+    t.true(
+      code.includes(barrier.poll),
+      'the poll must yield with a real referenced timer, not a macrotask spin',
+    )
+    // `__scheduleTimer` falls back to the macrotask scheduler when `setTimeout`
+    // is missing or throws — but not when it is present, returns a handle and
+    // never fires (fake timers; a host whose timers belong to an IO context
+    // that is gone). With no budget left to bail the poll out, that host would
+    // park it forever. Arm both until timers have actually arrived, then pace
+    // on the timer alone rather than spinning the zero-delay queue.
+    //
+    // Whether they arrive is a property of the poll, never of the module: a
+    // host can lose its timers between two disposals, and in the deferred
+    // shape every instance shares this module — one healthy instance must not
+    // disarm the fallback for the next one.
+    t.false(
+      code.includes('let __wasmRuntimePollTimerArrived'),
+      'the pacing state must not outlive the poll that learned it',
+    )
+    t.is(
+      code.split('function __createWasmRuntimePollPace()').length - 1,
+      1,
+      'one definition of the pacing state',
+    )
+    t.is(
+      code.split('__createWasmRuntimePollPace()').length - 1,
+      2,
+      'and exactly one caller: the poll loop, which owns it for its own run',
+    )
+    const yieldStart = code.indexOf('function __yieldWasmRuntimePollTurn(')
+    t.true(yieldStart > 0, 'the poll must yield through one shared turn helper')
+    const yieldTurn = code.slice(yieldStart, code.indexOf('\n}\n', yieldStart))
+    t.true(
+      yieldTurn.includes('__scheduleTimer(') &&
+        yieldTurn.includes('__scheduleMacrotask('),
+      'an undecided turn must arm both primitives, so an inert setTimeout cannot park the poll',
+    )
+    t.true(
+      yieldTurn.includes('pace.arrivals++'),
+      'the timer callback must count that timers work on this host',
+    )
+    t.true(
+      yieldTurn.includes(
+        'pace.arrivals < __WASM_RUNTIME_WORK_POLL_TRUSTED_ARRIVALS',
+      ),
+      'and one arrival must not be enough: it can be a timer armed before the host stopped running them',
+    )
+    // A poll that has settled onto the timer alone has nothing left to fall
+    // back on if the timers stop mid-poll — the turn that armed the dead timer
+    // is the turn that parks, and a parked poll schedules nothing that could
+    // notice. Every turn keeps a longer timer outstanding for that.
+    t.true(
+      yieldTurn.includes('__armWasmRuntimePollStallBackup('),
+      'every turn must keep a stall backup outstanding, armed while the timers still work',
+    )
+    const backupStart = code.indexOf(
+      'function __armWasmRuntimePollStallBackup(',
+    )
+    t.true(backupStart > 0, 'the backup must be one shared helper')
+    const stallBackup = code.slice(
+      backupStart,
+      code.indexOf('\n}\n', backupStart),
+    )
+    t.true(
+      stallBackup.includes('pace.arrivals = 0'),
+      'a turn the backup has to end proves the timers stopped: the poll goes back to arming both',
+    )
+    t.true(
+      stallBackup.includes('pace.settleTurn'),
+      'and the backup must end whichever turn is parked, not the one that armed it',
+    )
+    // By due time, never by how long the parked turn has been waiting. A host
+    // runs its timers in due order, so a backup that runs while a turn due a
+    // window earlier is still parked proves that turn's timer was dropped —
+    // and a healthy turn, whose timer runs first and clears `settleTurn`, is
+    // never touched. Measuring the wait instead has a phase hole: arms spaced
+    // further apart than the window leave the turn that parks between them
+    // with no backup young enough to rescue it.
+    t.regex(
+      stallBackup,
+      /pace\.turnTimerDueAt > (?:__)?dueAt - __WASM_RUNTIME_WORK_POLL_STALL_MS/,
+      'the backup must judge by due time, so there is no phase to fall through',
+    )
+    t.false(
+      stallBackup.includes('Date.now() -'),
+      'and it must not measure how long the parked turn has waited',
+    )
+    t.true(
+      yieldTurn.includes('pace.settleTurn = undefined'),
+      'a turn that ends must stop being the parked one, or a later backup reads a due time already answered',
+    )
+    t.regex(
+      yieldTurn,
+      /if \(__settled\??\) \{\s*return\s*\}|if \(settled\) \{\s*return\s*\}/,
+      'whichever primitive loses the race must resolve nothing: one poll per turn',
+    )
+    t.true(
+      code.includes(barrier.finish),
+      'finish must run whether the poll ended, timed out or could not run at all',
+    )
+    // The one caller that cannot yield is the raw `Context.destroy()` the
+    // wrapper intercepts, and the queue it leaves behind is discarded by the
+    // destroy that follows. Say so, once, without throwing.
+    t.true(
+      code.includes(barrier.report),
+      'the single-call barrier must report settlements nothing can reach any more',
+    )
+    // The window between the halves spans real event-loop turns, so a caller
+    // that cannot yield — the CJS 'exit' teardown, the managed beforeExit one —
+    // can land in the middle of one. It cannot wait for the poll; it has to
+    // close the handshake itself, because `…_finish` is the call that joins and
+    // lowers the barrier. Without this the context is destroyed with the
+    // barrier still raised, the runtime never joined and the destroy recorded
+    // as done.
+    t.is(
+      code.split(barrier.publishParked).length - 1,
+      1,
+      'the poll must publish a closer before it yields',
+    )
+    t.is(
+      code.split(barrier.clearParked).length - 1,
+      1,
+      'finishing the handshake must retract that closer exactly once',
+    )
+    const parkedIndex = code.indexOf(`const ${barrier.parked}`)
+    t.true(
+      parkedIndex > 0 || code.includes(`let ${barrier.parked}`),
+      'the closer must live outside the barrier, where a non-yielding caller can reach it',
+    )
+    // And the single call is where it is reached: every teardown path runs the
+    // barrier through it before destroying, so closing a parked handshake there
+    // covers all of them at once.
+    const isEager = barrier.parked === '__finishParkedWasmEnvCleanup'
+    const prepareStart = code.indexOf(
+      isEager
+        ? `function ${barrier.fallback.replace('()', '')}() {`
+        : `const ${barrier.fallback.replace('()', '')} = () => {`,
+    )
+    t.true(prepareStart > 0, 'the single-call barrier must be one function')
+    const prepareBody = code.slice(
+      prepareStart,
+      code.indexOf(isEager ? '\n}\n' : '\n  }\n', prepareStart),
+    )
+    const closerIndex = prepareBody.indexOf(barrier.parked)
+    t.true(
+      closerIndex > 0,
+      'the single call must close a parked handshake instead of skipping the barrier',
+    )
+    t.true(
+      closerIndex < prepareBody.indexOf('napi_prepare_wasm_env_cleanup'),
+      'and it must close it before looking the single-call export up: a parked handshake is already begun',
+    )
+  })
+}
+
 // The loaders order their own teardown barrier-then-destroy, but the emnapi
 // context is a live object: an embedder or test harness holding it, or emnapi's
 // own `beforeExit` auto-destroy on a host where `suppressDestroy()` is absent,
@@ -1140,14 +1375,22 @@ const CONTEXT_DESTROY_WRAP_SIGNATURE =
 const preparingBarrierGuards = {
   shared: {
     probe: '__isPreparingWasmEnvCleanup',
+    // Both barrier entry points read it: the single call and the two-phase
+    // form, which keeps it raised across the turns it yields. The single call
+    // splits the check in two, because a handshake parked between the halves is
+    // one it closes rather than refuses — see the two-phase test above — so the
+    // shape below is the reentrancy half alone.
+    entryGuard: `  if (__emnapiWasmEnvCleanupPreparing) {
+    return
+  }`,
+    twoPhaseEntryGuard: `  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
+    return
+  }`,
     snippets: [
       'let __emnapiWasmEnvCleanupPreparing = false',
       `function __isPreparingWasmEnvCleanup() {
   return __emnapiWasmEnvCleanupPreparing
 }`,
-      `  if (__emnapiWasmEnvCleanupPrepared || __emnapiWasmEnvCleanupPreparing) {
-    return
-  }`,
       `    __emnapiWasmEnvCleanupPreparing = true
     try {
       prepare()
@@ -1158,12 +1401,15 @@ const preparingBarrierGuards = {
   },
   deferred: {
     probe: '__isPreparingEnvCleanup',
+    entryGuard: `    if (__wasmEnvCleanupPreparing) {
+      return
+    }`,
+    twoPhaseEntryGuard: `    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
+      return
+    }`,
     snippets: [
       'let __wasmEnvCleanupPreparing = false',
       'const __isPreparingEnvCleanup = () => __wasmEnvCleanupPreparing',
-      `    if (__wasmEnvCleanupPrepared || __wasmEnvCleanupPreparing) {
-      return
-    }`,
       `      __wasmEnvCleanupPreparing = true
       try {
         __prepareWasmEnvCleanup()
@@ -1267,6 +1513,20 @@ for (const { name, code, prepare, guard } of wrappedContextCreationCases) {
         `barrier must carry its in-flight guard exactly once: ${snippet}`,
       )
     }
+    // Both barrier entry points — the single call and the two-phase form —
+    // refuse to re-enter a barrier already in flight. The two-phase form still
+    // tests the pair in one condition; the single call tests the reentrancy
+    // half on its own, after it has dealt with a parked handshake.
+    t.is(
+      code.split(guard.entryGuard).length - 1,
+      1,
+      'the single call must refuse to re-enter a barrier already in flight',
+    )
+    t.is(
+      code.split(guard.twoPhaseEntryGuard).length - 1,
+      1,
+      'the two-phase barrier must refuse to re-enter a barrier already in flight',
+    )
     t.is(
       code.split(NESTED_DESTROY_NO_OP).length - 1,
       1,

package/src/api/build.ts

@@ -42,7 +42,9 @@ import {
   removeNodeStreamWebTypeImports,
   rewriteUnboundNodeGlobalTypeQueries,
   rewriteTypeImportReferences,
+  checkSelfsign,
   scanExportedName,
+  signFileAtomic,
   type Target,
   targetToEnvVar,
   tryInstallCargoBinary,
@@ -254,7 +256,7 @@ export function checkAsyncRuntimeHostContract({
   }
   if (!asyncRuntime && missingHostExports.length === 0) {
     return {
-      warning: `${packageName} exports the napi-async-runtime host contract but napi.wasm.asyncRuntime is not enabled. The generated WASI loaders will not install the CurrentThread task and timer hosts, so async exports will never make progress unless the host is installed by hand.`,
+      warning: `${packageName} exports the napi-async-runtime host contract but napi.wasm.asyncRuntime is not enabled. The generated WASI loaders will not install the CurrentThread task and timer hosts, so a binding running the CurrentThread flavor (the default on every wasm target) will make no progress unless the hosts are installed by hand. A wasm32-wasip1-threads binding that configures MultiThread does not need them.`,
     }
   }
   return {}
@@ -1138,6 +1140,7 @@ export async function buildProject(rawOptions: BuildOptions) {
 
   const options: ParsedBuildOptions = {
     dtsCache: true,
+    ohosSign: true,
     ...rawOptions,
     format: resolveBuildFormat(rawOptions),
     cwd: rawOptions.cwd ?? process.cwd(),
@@ -2466,6 +2469,40 @@ class Builder {
       } else {
         await copyFileAtomic(src, dest)
         artifactReplaced = true
+        // OpenHarmony devices refuse to load unsigned `.so` files, so inject
+        // the fs-verity `.codesign` self-signature unless `--no-ohos-sign`.
+        if (
+          this.target.platform === 'openharmony' &&
+          this.options.ohosSign !== false
+        ) {
+          debug('Self-signing OpenHarmony artifact:')
+          debug('  %i', dest)
+          try {
+            // Force mode: the OHOS SDK linker can already self-sign artifacts
+            // when its opt-in code-signing is enabled — strip that signature
+            // and re-sign rather than failing on the existing `.codesign`
+            // section.
+            signFileAtomic(dest, true)
+            // Re-verify the signature we just wrote so a corrupt or
+            // mis-injected `.codesign` section is surfaced immediately.
+            const { ok, reason } = checkSelfsign(readFileSync(dest))
+            if (!ok) {
+              debug.warn(
+                `OpenHarmony self-sign verification failed: ${dest}: ${reason}`,
+              )
+            }
+          } catch (e) {
+            // Self-signing is best-effort: HarmonyOS only ships on aarch64,
+            // and the algorithm (like the official binary-sign-tool) is only
+            // exercised against aarch64 artifacts — warn instead of failing
+            // the whole build when e.g. an x86_64 artifact cannot be signed.
+            // signElf rejects before writing anything, so `dest` still holds
+            // the copied artifact.
+            debug.warn(
+              `Skip OpenHarmony self-signing: ${dest}: ${(e as Error).message}`,
+            )
+          }
+        }
       }
       this.outputs.push({
         kind: dest.endsWith('.node') ? 'node' : isWasm ? 'wasm' : 'exe',