Get it working

Author: timfish

.github/workflows/ci.yml

@@ -1,4 +1,3 @@
-
 name: "CI: Build & Test"
 on:
   push:
@@ -9,7 +8,7 @@ on:
 
 permissions:
   contents: read
-  packages: read      # Required for GHCR
+  packages: read # Required for GHCR
 
 jobs:
   job_lint:
@@ -408,9 +407,36 @@ jobs:
       - name: Run tests
         run: yarn test
 
+  job_test_bindings_recompile:
+    name: Test (recompile from source) (v${{ matrix.node }}) ${{ matrix.os }}
+    needs: [job_build]
+    runs-on: ${{ matrix.os }}
+    env:
+      DELETE_BINARIES: true
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node: [18, 26]
+    steps:
+      - name: Check out current commit
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ matrix.node }}
+      - name: Install dependencies
+        run: yarn install --ignore-engines --ignore-scripts --frozen-lockfile
+      - name: Download Tarball
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: ${{ github.sha }}
+      - name: Run tests
+        run: yarn test
+
   job_required_jobs_passed:
     name: All required jobs passed
-    needs: [job_lint, job_test_bindings]
+    needs: [job_lint, job_test_bindings, job_test_bindings_recompile]
     # Always run this, even if a dependent job failed
     if: always()
     runs-on: ubuntu-latest

package.json

@@ -16,6 +16,7 @@
     "sentry"
   ],
   "scripts": {
+    "install": "node -p \"'@sentry/node-native-stacktrace@' + require('./package.json').version\"",
     "lint": "yarn lint:eslint && yarn lint:clang",
     "lint:eslint": "eslint . --format stylish",
     "lint:clang": "node scripts/clang-format.mjs",
@@ -24,21 +25,23 @@
     "fix:clang": "node scripts/clang-format.mjs --fix",
     "build": "yarn clean && yarn build:lib && yarn build:bindings:configure && yarn build:bindings",
     "build:lib": "tsc",
-    "build:copy-binary": "node -e \"import { copyBinary } from './lib/index.js'; copyBinary();\"",
+    "build:copy-binary": "node -e \"const { copyBinary } = require('./lib/copy-binary.js'); copyBinary();\"",
     "build:bindings:configure": "node-gyp configure",
     "build:bindings:configure:arm64": "node-gyp configure --arch=arm64 --target_arch=arm64",
-    "build:bindings": "node-gyp build && yarn build:copy-binary",
-    "build:bindings:arm64": "node-gyp build --arch=arm64 && yarn build:copy-binary",
+    "build:bindings": "yarn build:lib && node-gyp build && yarn build:copy-binary",
+    "build:bindings:arm64": "yarn build:lib && node-gyp build --arch=arm64 && yarn build:copy-binary",
     "build:tarball": "npm pack",
     "clean": "node-gyp clean && rm -rf lib && rm -rf build && rm -f *.tgz",
     "test": "node ./test/prepare.mjs && vitest run --poolOptions.forks.singleFork --silent=false --disable-console-intercept"
   },
+  "gypfile": false,
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
     "detect-libc": "^2.0.4",
-    "node-abi": "^3.89.0"
+    "node-abi": "^3.92.0",
+    "node-gyp": "^11.5.0"
   },
   "devDependencies": {
     "@sentry-internal/eslint-config-sdk": "^9.22.0",
@@ -47,7 +50,6 @@
     "clang-format": "^1.8.0",
     "cross-env": "^7.0.3",
     "eslint": "^7.0.0",
-    "node-gyp": "^11.2.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.4"
   },

src/constants.ts

@@ -0,0 +1,11 @@
+
+import * as os from 'node:os';
+import { versions } from 'node:process';
+import * as libc from 'detect-libc';
+import { getAbi } from 'node-abi';
+
+export const stdlib = libc.familySync();
+export const platform = process.env['BUILD_PLATFORM'] || os.platform();
+export const arch = process.env['BUILD_ARCH'] || os.arch();
+export const abi = getAbi(versions.node, 'node');
+export const identifier = [platform, arch, stdlib, abi].filter(c => c !== undefined && c !== null).join('-');

src/copy-binary.ts

@@ -0,0 +1,30 @@
+/* eslint-disable no-console */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { identifier } from './constants';
+
+const source = path.join(__dirname, '..', 'build', 'Release', 'stack-trace.node');
+const target = path.join(__dirname, '..', 'lib', `stack-trace-${identifier}.node`);
+
+/**
+ * Copies the compiled binary from the build directory to the lib directory with the correct name based on the current platform and Node version.
+ *
+ * @hidden We only use this for copying the binary after building, it is not intended to be used by end users.
+ */
+export function copyBinary(): void {
+  const build = path.resolve(__dirname, '..', 'lib');
+  if (!fs.existsSync(build)) {
+    fs.mkdirSync(build, { recursive: true });
+  }
+
+  if (!fs.existsSync(source)) {
+    throw new Error(`Source file does not exist: ${  source}`);
+  } else {
+    if (fs.existsSync(target)) {
+      console.log('Target file already exists, overwriting it');
+      fs.unlinkSync(target);
+    }
+    console.log('Copying', source, 'to', target);
+    fs.copyFileSync(source, target);
+  }
+}

src/index.ts

@@ -1,19 +1,12 @@
 /* eslint-disable no-console */
 import type { AsyncLocalStorage } from 'node:async_hooks';
 import { spawnSync } from 'node:child_process';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
-import { env, versions } from 'node:process';
+import { env } from 'node:process';
 import { threadId } from 'node:worker_threads';
-import * as libc from 'detect-libc';
-import { getAbi } from 'node-abi';
-
-const stdlib = libc.familySync();
-const platform = process.env['BUILD_PLATFORM'] || os.platform();
-const arch = process.env['BUILD_ARCH'] || os.arch();
-const abi = getAbi(versions.node, 'node');
-const identifier = [platform, arch, stdlib, abi].filter(c => c !== undefined && c !== null).join('-');
+import { abi, arch, identifier, platform, stdlib } from './constants';
+import { copyBinary } from './copy-binary';
+import { withRebuildLock } from './rebuild-lock';
 
 type AsyncStorageArgs = {
   /** The AsyncLocalStorage instance used to fetch the store */
@@ -56,60 +49,34 @@ interface Native {
   getThreadsLastSeen(): Record<string, number>;
 }
 
-/**
- * Copies the compiled binary from the build directory to the lib directory with the correct name based on the current platform and Node version.
- *
- * @hidden We only use this for copying the binary after building, it is not intended to be used by end users.
- */
-export function copyBinary(): void {
-  const build = path.resolve(__dirname, '..', 'lib');
-  if (!fs.existsSync(build)) {
-    fs.mkdirSync(build, { recursive: true });
-  }
-
-  if (!fs.existsSync(source)) {
-    console.log('Source file does not exist:', source);
-    process.exit(1);
-  } else {
-    if (fs.existsSync(target)) {
-      console.log('Target file already exists, overwriting it');
-      fs.unlinkSync(target);
-    }
-    console.log('Copying', source, 'to', target);
-    fs.copyFileSync(source, target);
-  }
-}
-
-const source = path.join(__dirname, '..', 'build', 'Release', 'stack-trace.node');
-const target = path.join(__dirname, '..', 'lib', `stack-trace-${identifier}.node`);
-
 function clean(err: Buffer): string {
   return err.toString().trim();
 }
 
 function recompileFromSource(): void {
   const cwd = path.join(__dirname, '..');
+  // Resolve node-gyp from its package entry so it's found even when
+  // node_modules/.bin/ is not in PATH (e.g. outside of npm run scripts).
+  const nodeGyp = require.resolve('node-gyp/bin/node-gyp.js');
   console.log('Compiling from source...');
-  let spawn = spawnSync('node-gyp', ['configure'], {
+  let spawn = spawnSync(process.execPath, [nodeGyp, 'configure'], {
     cwd,
     stdio: ['inherit', 'inherit', 'pipe'],
     env: process.env,
-    shell: true,
   });
   if (spawn.status !== 0) {
     console.log('Failed to configure gyp');
-    console.log(clean(spawn.stderr));
+    if (spawn.stderr) console.log(clean(spawn.stderr));
     return;
   }
-  spawn = spawnSync('node-gyp', ['build'], {
+  spawn = spawnSync(process.execPath, [nodeGyp, 'build'], {
     cwd,
     stdio: ['inherit', 'inherit', 'pipe'],
     env: process.env,
-    shell: true,
   });
   if (spawn.status !== 0) {
     console.log('Failed to build bindings');
-    console.log(clean(spawn.stderr));
+    if (spawn.stderr) console.log(clean(spawn.stderr));
     return;
   }
 
@@ -280,7 +247,7 @@ function getNativeModule(): Native {
     try {
       return require('../build/Release/stack-trace.node');
     } catch (e) {
-      console.warn('The \'@sentry-internal/node-native-stacktrace\' binary could not be found. Use \'@electron/rebuild\' to ensure the native module is built for Electron.');
+      console.warn('The \'@sentry/node-native-stacktrace\' binary could not be found. Use \'@electron/rebuild\' to ensure the native module is built for Electron.');
       throw e;
     }
   }
@@ -290,13 +257,15 @@ function getNativeModule(): Native {
     return nativeModule;
   }
 
-  try {
-    recompileFromSource();
-  } catch (e) {
-    console.warn('Failed to compile from source:', e);
-  }
+  withRebuildLock(() => {
+    try {
+      recompileFromSource();
+    } catch (e) {
+      console.warn('Failed to compile from source:', e);
+    }
+  });
 
-  // Try again after attempting to recompile, in case the binary is now available.
+  // Try again after recompile (or after another caller finished theirs).
   nativeModule = tryLoad();
 
   if (nativeModule) {
@@ -308,7 +277,26 @@ function getNativeModule(): Native {
 
 const native = getNativeModule();
 
+/**
+ * Registers the current thread with the native module.
+ *
+ * This should be called on every thread that you want to capture stack traces from.
+ *
+ * @param threadName The name of the thread
+ *
+ * threadName defaults to the `threadId` if not provided.
+ */
 export function registerThread(threadName?: string): void;
+/**
+ * Registers the current thread with the native module.
+ *
+ * This should be called on every thread that you want to capture stack traces from.
+ *
+ * @param storageOrThread Either the name of the thread, or an object containing an AsyncLocalStorage instance and optional storage key.
+ * @param threadName The name of the thread, if the first argument is an object.
+ *
+ * threadName defaults to the `threadId` if not provided.
+ */
 export function registerThread(storageOrThread: AsyncStorageArgs | string, threadName?: string): void;
 /**
  * Registers the current thread with the native module.

src/rebuild-lock.ts

@@ -0,0 +1,73 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const lockFile = path.join(__dirname, '..', '.rebuild-lock');
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // EPERM: process exists but we can't signal it — treat as alive
+    // ESRCH: no such process — stale lock
+    return (e as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+function tryAcquire(): number | undefined {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(lockFile, 'wx');
+    fs.writeSync(fd, String(process.pid));
+    return fd;
+  } catch {
+    try { if (fd !== undefined) fs.closeSync(fd); } catch { /* ignore */ }
+    return undefined;
+  }
+}
+
+function release(fd: number): void {
+  try { fs.closeSync(fd); } catch { /* ignore */ }
+  try { fs.unlinkSync(lockFile); } catch { /* ignore */ }
+}
+
+function clearStaleLock(): void {
+  try {
+    const pid = parseInt(fs.readFileSync(lockFile, 'utf8'), 10);
+    if (!isNaN(pid) && !isProcessAlive(pid)) {
+      fs.unlinkSync(lockFile);
+    }
+  } catch { /* ignore — another waiter may have already cleared it */ }
+}
+
+function waitForLockRelease(): void {
+  const timer = new Int32Array(new SharedArrayBuffer(4));
+  while (fs.existsSync(lockFile)) {
+    clearStaleLock();
+    Atomics.wait(timer, 0, 0, 250);
+  }
+}
+
+/**
+ * Runs `work` while holding an exclusive lock on `lockFile`. If another caller
+ * holds the lock, blocks until it is released (or until a stale lock from a
+ * crashed process is detected and cleared).
+ */
+export function withRebuildLock(work: () => void): void {
+  let fd = tryAcquire();
+
+  if (fd === undefined) {
+    waitForLockRelease();
+    // Try once more after waiting — another waiter may have cleared a stale
+    // lock and then done the rebuild itself, so we may not need to rebuild.
+    fd = tryAcquire();
+  }
+
+  if (fd !== undefined) {
+    try {
+      work();
+    } finally {
+      release(fd);
+    }
+  }
+}

test/e2e.test.mjs

@@ -7,7 +7,7 @@ const __dirname = import.meta.dirname || new URL('.', import.meta.url).pathname;
 const NODE_MAJOR_VERSION = parseInt(process.versions.node.split('.')[0], 10);
 
 // macOS emulated x64 in CI is very slow!
-const timeout = process.env.CI && process.platform === 'darwin' ? 60000 : 20000;
+const timeout = (process.env.CI && process.platform === 'darwin') || process.env.DELETE_BINARIES ? 60000 : 20000;
 
 async function runTest(...paths) {
   console.time('Test Run');

test/prepare.mjs

@@ -1,5 +1,5 @@
 import { execSync, spawnSync } from 'node:child_process';
-import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -40,6 +40,16 @@ function installTarballAsDependency(root) {
 
   console.log('Installing dependencies...');
   execSync('yarn install', { cwd: root, stdio: 'inherit' });
+
+  // For recompile from source tests, we need to ensure the pre-built binaries are removed
+  if (process.env.DELETE_BINARIES) {
+    const unpackedDir = join(root, 'node_modules', '@sentry/node-native-stacktrace', 'lib');
+    readdirSync(unpackedDir).forEach(file => {
+      if (file.endsWith('.node')) {
+        rmSync(join(unpackedDir, file));
+      }
+    });
+  }
 }
 
 installTarballAsDependency(__dirname);