@nubjs/nub-linux-x64 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubjs/nub-linux-x64",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Nub binary for linux-x64",
   "license": "MIT",
   "repository": "https://github.com/nubjs/nub",

package/runtime/navigator-locks.mjs

@@ -1,10 +1,21 @@
-// Web Locks API polyfill for Node 22.x (native on Node 24.5+).
-// Single-process only — locks don't coordinate across workers.
+// Web Locks API polyfill for Node < 24.5 (native on Node 24.5+, #58666).
+// Single-process only — locks don't coordinate across worker threads (a deliberate
+// scope: the common in-process serialization use is covered; cross-thread coordination
+// would need a SharedArrayBuffer waitlist and is out of scope until there's demand).
+//
+// Spec: https://w3c.github.io/web-locks/. Modeled to match Node's own
+// internal/locks.js (the native impl on 24.5+) so behavior is identical across the
+// version boundary — including `steal`, AbortSignal integration, and the option/name
+// validation that the WPT web-locks suite exercises. Requires a `navigator` object to
+// host `navigator.locks`; navigator-shim.mjs backfills that on Node < 21 and MUST run
+// first.
 
 if (typeof globalThis.navigator === "object" && typeof globalThis.navigator.locks === "undefined") {
-  // Track held locks: name → { mode, count } where count > 1 means shared holders
-  const held = new Map();
-  const queue = new Map();
+  const AbortSig = globalThis.AbortSignal;
+
+  const abortError = (msg) => new DOMException(msg || "The operation was aborted", "AbortError");
+  const stolenError = () => abortError("The lock was stolen by another request");
+  const notSupported = (msg) => new DOMException(msg, "NotSupportedError");
 
   class Lock {
     #name;
@@ -17,113 +28,209 @@ if (typeof globalThis.navigator === "object" && typeof globalThis.navigator.lock
     get mode() { return this.#mode; }
   }
 
+  // held: name → { mode, holders:Set<Holder> }. A shared grant has N holders sharing
+  // one record; an exclusive grant has exactly one. queue: name → Array<Waiter> (FIFO).
+  const held = new Map();
+  const queue = new Map();
+
   function canAcquire(name, mode) {
-    const current = held.get(name);
-    if (!current) return true;
-    if (mode === "shared" && current.mode === "shared") return true;
-    return false;
+    const rec = held.get(name);
+    if (!rec) return true;
+    return mode === "shared" && rec.mode === "shared";
   }
 
-  function acquire(name, mode) {
-    const current = held.get(name);
-    if (current && mode === "shared" && current.mode === "shared") {
-      current.count++;
-    } else {
-      held.set(name, { mode, count: 1 });
-    }
+  // A FRESH request may be granted immediately only when no waiters are already
+  // queued for the name — otherwise it must queue behind them. This is the
+  // reader/writer FAIRNESS rule: a new shared request must NOT barge ahead of a
+  // pending exclusive request and join the current shared holders, which would
+  // starve the writer (WPT mode-mixed "An exclusive lock between shared locks").
+  // drainQueue, which only ever grants from the FRONT of the queue, keeps using
+  // canAcquire directly.
+  function canGrantNow(name, mode) {
+    const q = queue.get(name);
+    if (q && q.length > 0) return false;
+    return canAcquire(name, mode);
   }
 
-  function release(name) {
-    const current = held.get(name);
-    if (!current) return;
-    current.count--;
-    if (current.count <= 0) {
-      held.delete(name);
-      drainQueue(name);
-    }
+  function addHolder(name, mode, holder) {
+    const rec = held.get(name);
+    if (rec) rec.holders.add(holder);
+    else held.set(name, { mode, holders: new Set([holder]) });
+  }
+
+  function removeHolder(name, holder) {
+    const rec = held.get(name);
+    if (!rec) return;
+    rec.holders.delete(holder);
+    if (rec.holders.size === 0) held.delete(name);
   }
 
+  function enqueue(name, waiter) {
+    let q = queue.get(name);
+    if (!q) queue.set(name, (q = []));
+    q.push(waiter);
+  }
+
+  // Grant as many head-of-queue waiters as the current held state allows: a head
+  // exclusive takes the lock alone; a run of head shared waiters is all granted.
   function drainQueue(name) {
     const q = queue.get(name);
     if (!q || q.length === 0) return;
+    while (q.length > 0) {
+      const first = q[0];
+      if (!canAcquire(name, first.mode)) break;
+      q.shift();
+      first.grant(); // synchronously addHolders, so canAcquire reflects it next iter
+      if (first.mode === "exclusive") break;
+    }
+    if (q.length === 0) queue.delete(name);
+  }
 
-    // Try to grant as many queued requests as possible.
-    // If the first queued is shared, grant all consecutive shared requests.
-    // If the first queued is exclusive, grant only that one.
-    const first = q[0];
-    if (canAcquire(name, first.mode)) {
-      if (first.mode === "exclusive") {
-        q.shift();
-        first.resolve();
-      } else {
-        // Grant all consecutive shared requests.
-        while (q.length > 0 && q[0].mode === "shared") {
-          const req = q.shift();
-          req.resolve();
-        }
-      }
+  // Run `cb(lock)` as a holder of (name, mode); return the promise that settles when
+  // the holder releases (cb's result/throw) — or rejects early if a steal BREAKS it.
+  // The callback is invoked one microtask later (matching Node), so a synchronously
+  // signaled abort is observed before the callback runs.
+  function runHolder(name, mode, cb) {
+    const lock = new Lock(name, mode);
+    let broken = false;
+    let rejectReleased;
+    const holder = {
+      mode,
+      break(reason) {
+        if (broken) return;
+        broken = true;
+        // Remove WITHOUT draining — the stealer takes the lock next; queued waiters
+        // stay pending until the steal's own holder releases.
+        removeHolder(name, holder);
+        rejectReleased(reason);
+      },
+    };
+    addHolder(name, mode, holder);
+    return new Promise((resolve, reject) => {
+      rejectReleased = reject;
+      Promise.resolve()
+        .then(() => cb(lock))
+        .then(
+          (value) => { if (!broken) { removeHolder(name, holder); resolve(value); drainQueue(name); } },
+          (err) => { if (!broken) { removeHolder(name, holder); reject(err); drainQueue(name); } },
+        );
+    });
+  }
+
+  // The lock engine: returns the `released` promise. `cb` receives the granted Lock
+  // (or null on an ifAvailable miss). Mirrors the grant/steal/ifAvailable/queue shape
+  // of Node's internalBinding('locks').request.
+  function engineRequest(name, mode, steal, ifAvailable, cb) {
+    if (steal) {
+      const rec = held.get(name);
+      if (rec) for (const h of [...rec.holders]) h.break(stolenError());
+      return runHolder(name, "exclusive", cb);
+    }
+    if (canGrantNow(name, mode)) {
+      return runHolder(name, mode, cb);
     }
+    if (ifAvailable) {
+      return Promise.resolve().then(() => cb(null));
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        mode,
+        settled: false,
+        grant() {
+          if (waiter.settled) return;
+          waiter.settled = true;
+          runHolder(name, mode, cb).then(resolve, reject);
+        },
+      };
+      enqueue(name, waiter);
+    });
   }
 
   class LockManager {
-    async request(name, optionsOrCallback, callback) {
-      let options = {};
-      if (typeof optionsOrCallback === "function") {
-        callback = optionsOrCallback;
-      } else {
-        options = optionsOrCallback || {};
+    async request(name, optionsOrCallback, maybeCallback) {
+      let options = optionsOrCallback;
+      let callback = maybeCallback;
+      if (callback === undefined) {
+        callback = options;
+        options = undefined;
+      }
+
+      // WebIDL DOMString coercion (throws TypeError on a Symbol, like the binding).
+      name = `${name}`;
+      if (typeof callback !== "function") {
+        throw new TypeError("Failed to execute 'request' on 'LockManager': parameter 2 is not a function.");
       }
+      if (options === undefined || typeof options === "function") options = {};
 
-      const mode = options.mode || "exclusive";
-      const ifAvailable = options.ifAvailable || false;
+      const mode = options.mode === undefined ? "exclusive" : options.mode;
+      if (mode !== "exclusive" && mode !== "shared") {
+        throw new TypeError(`Failed to execute 'request' on 'LockManager': '${mode}' is not a valid value for enumeration LockMode.`);
+      }
+      const ifAvailable = !!options.ifAvailable;
+      const steal = !!options.steal;
       const signal = options.signal;
+      if (signal !== undefined && signal !== null && !(AbortSig && signal instanceof AbortSig)) {
+        throw new TypeError("Failed to execute 'request' on 'LockManager': member signal is not of type AbortSignal.");
+      }
 
-      if (signal?.aborted) {
-        throw signal.reason || new DOMException("Lock request aborted", "AbortError");
+      // Already-aborted signal rejects with its reason BEFORE the option-combo checks
+      // (matching Node's signal.throwIfAborted() ordering).
+      if (signal && signal.aborted) {
+        throw signal.reason || abortError();
+      }
+      if (name[0] === "-") {
+        throw notSupported("Lock name may not start with hyphen '-'");
+      }
+      if (ifAvailable && steal) {
+        throw notSupported("ifAvailable and steal options cannot be used together");
+      }
+      if (mode !== "exclusive" && steal) {
+        throw notSupported("mode must be 'exclusive' when using the steal option");
+      }
+      if (signal && (steal || ifAvailable)) {
+        throw notSupported("signal cannot be used with the steal or ifAvailable options");
       }
 
-      if (!canAcquire(name, mode)) {
-        if (ifAvailable) {
-          return callback(null);
-        }
-        await new Promise((resolve, reject) => {
-          if (!queue.has(name)) queue.set(name, []);
-          queue.get(name).push({ resolve, reject, mode });
-          if (signal) {
-            signal.addEventListener("abort", () => {
-              const q = queue.get(name) || [];
-              const idx = q.findIndex((e) => e.resolve === resolve);
-              if (idx !== -1) q.splice(idx, 1);
-              reject(signal.reason || new DOMException("Lock request aborted", "AbortError"));
-            }, { once: true });
-          }
+      // Signal path: the callback is deferred and skipped if the signal aborts before
+      // it runs; the abort rejects the OUTER promise iff the callback hasn't entered
+      // (lockGranted false). Verbatim shape of Node's internal/locks.js so a queued
+      // abort releases the slot (callback skipped) and the next waiter is granted.
+      if (signal) {
+        return new Promise((resolve, reject) => {
+          let lockGranted = false;
+          const onAbort = () => {
+            if (!lockGranted) reject(signal.reason || abortError());
+          };
+          signal.addEventListener("abort", onAbort, { once: true });
+          const wrapped = (lock) =>
+            Promise.resolve().then(() => {
+              if (signal.aborted) return undefined;
+              lockGranted = true;
+              return callback(lock);
+            });
+          const released = engineRequest(name, mode, false, false, wrapped);
+          released.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
         });
       }
 
-      acquire(name, mode);
-      const lock = new Lock(name, mode);
-
-      try {
-        return await callback(lock);
-      } finally {
-        release(name);
-      }
+      return engineRequest(name, mode, steal, ifAvailable, (lock) => callback(lock));
     }
 
     async query() {
-      const heldLocks = [];
-      for (const [name, info] of held) {
-        for (let i = 0; i < info.count; i++) {
-          heldLocks.push({ name, mode: info.mode, clientId: "" });
-        }
+      // clientId is per-realm and opaque: `node-<pid>-0` (single-process; this polyfill
+      // does not coordinate across worker threads, so the threadId slot is always 0 —
+      // and we avoid importing node:worker_threads to keep this module builtin-free for a
+      // cheap bootstrap). The cross-context distinct-id WPT cases are browser-specific.
+      const clientId = `node-${process.pid}-0`;
+      const heldOut = [];
+      for (const [name, rec] of held) {
+        for (let i = 0; i < rec.holders.size; i++) heldOut.push({ name, mode: rec.mode, clientId });
       }
       const pending = [];
       for (const [name, q] of queue) {
-        for (const req of q) {
-          pending.push({ name, mode: req.mode, clientId: "" });
-        }
+        for (const w of q) if (!w.settled) pending.push({ name, mode: w.mode, clientId });
       }
-      return { held: heldLocks, pending };
+      return { held: heldOut, pending };
     }
   }
 

package/runtime/navigator-shim.mjs

@@ -0,0 +1,144 @@
+// `navigator` global backfill for Node < 21 (where the global is wholly absent).
+//
+// Node ships `globalThis.navigator` from 21.0.0. Below that it is `undefined`, so
+// any web-platform API hosted ON navigator — chiefly `navigator.locks` (Web Locks,
+// see navigator-locks.mjs) — has no object to attach to and silently does nothing.
+// nub's floor is 18.19, so to make those APIs reach the floor we synthesize the
+// `navigator` object Node 21+ would provide. Companion to navigator-locks.mjs:
+// this MUST run BEFORE it so locks has a host on 18.19–20.x.
+//
+// Shape mirrors Node's internal/navigator.js: a `Navigator` instance with the
+// enumerable prototype getters `hardwareConcurrency`, `language`, `languages`,
+// `userAgent`, `platform` (locks is added separately by navigator-locks.mjs). The
+// userAgent is `Node.js/<major>` — NEVER `Nub/…`: the user is running Node, nub is
+// the augmenter, and a `Nub/` UA would be a brand-boundary leak.
+//
+// VERSION-GATE, not a global read: installNavigatorShim() returns early on Node >= 21
+// from `process.versions.node` WITHOUT ever touching `globalThis.navigator`. That
+// matters because on Node 24.5+ the native `navigator` is a lazy getter whose first
+// access realizes ~30 internal/stream/worker-io builtins — a cold-start regression
+// (test-bootstrap-modules). The shim must never trigger that; the version check makes
+// the fast tier (>= 22.15, navigator always present) a free no-op.
+//
+// node: builtins (node:os) are fetched via `process.getBuiltinModule` when present,
+// else via a createRequire THREADED IN through `setBootstrapCreateRequire` — the same
+// brand-safe, off-the-user-loader-chain pattern worker-polyfill.mjs uses. The narrow
+// floor (18.19.x, 20.11–20.15) lacks `process.getBuiltinModule`, and the shim only
+// touches os lazily (the `hardwareConcurrency` getter), so the threaded require is
+// needed exactly there. `os` is never loaded on Node >= 21 (the early return).
+
+let _bootstrapCreateRequire = null;
+export function setBootstrapCreateRequire(fn) {
+  _bootstrapCreateRequire = fn;
+}
+
+function __getBuiltin(id) {
+  if (typeof process.getBuiltinModule === "function") return process.getBuiltinModule(id);
+  if (_bootstrapCreateRequire) return _bootstrapCreateRequire(import.meta.url)(id);
+  // Last-resort: a bare specifier require off this module's own createRequire is
+  // unavailable in ESM without node:module, which is exactly what the threading
+  // avoids importing statically. If neither path is wired, surface a clear error.
+  throw new Error("navigator-shim: no builtin accessor for " + id);
+}
+
+function deriveLanguage() {
+  // Approximate Node's ICU default locale from the POSIX locale env, falling back
+  // to "en-US" (Node's own fallback). `en_US.UTF-8` → `en-US`.
+  const raw =
+    process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || "";
+  const base = raw.split(".")[0].split("@")[0].replace("_", "-");
+  return base && base !== "C" && base !== "POSIX" ? base : "en-US";
+}
+
+function navigatorPlatform(platform, arch) {
+  // Mirror node/lib/internal/navigator.js getNavigatorPlatform.
+  if (platform === "darwin") return "MacIntel";
+  if (platform === "win32") return "Win32";
+  if (platform === "linux") {
+    if (arch === "ia32") return "Linux i686";
+    if (arch === "x64") return "Linux x86_64";
+    return `Linux ${arch}`;
+  }
+  if (platform === "freebsd") return arch === "ia32" ? "FreeBSD i386" : arch === "x64" ? "FreeBSD amd64" : `FreeBSD ${arch}`;
+  if (platform === "openbsd") return arch === "ia32" ? "OpenBSD i386" : arch === "x64" ? "OpenBSD amd64" : `OpenBSD ${arch}`;
+  if (platform === "sunos") return arch === "ia32" ? "SunOS i86pc" : `SunOS ${arch}`;
+  if (platform === "aix") return "AIX";
+  return `${platform[0].toUpperCase()}${platform.slice(1)} ${arch}`;
+}
+
+// Build the Navigator class lazily (only when actually backfilling) so loading this
+// module on the fast tier costs nothing beyond the early-return check.
+function makeNavigator() {
+  let _hw, _lang, _langs, _ua, _plat;
+  class Navigator {
+    get hardwareConcurrency() {
+      // os.availableParallelism honors cgroup CPU limits (Node 18.14+/19.4+; present
+      // on the 18.19 floor); fall back to cpus().length on the off chance it's absent.
+      if (_hw === undefined) {
+        const os = __getBuiltin("node:os");
+        _hw = typeof os.availableParallelism === "function" ? os.availableParallelism() : os.cpus().length;
+      }
+      return _hw;
+    }
+    get language() {
+      return (_lang ??= deriveLanguage());
+    }
+    get languages() {
+      return (_langs ??= Object.freeze([this.language]));
+    }
+    get userAgent() {
+      // `Node.js/<major>` — match Node exactly; never a nub-branded UA.
+      return (_ua ??= `Node.js/${process.versions.node.split(".")[0]}`);
+    }
+    get platform() {
+      return (_plat ??= navigatorPlatform(process.platform, process.arch));
+    }
+  }
+  // Match Node's instance shape: the property getters live on the prototype and are
+  // ENUMERABLE (Node sets them with kEnumerableProperty), so `for (const k in
+  // navigator)` walks them while `Object.keys(navigator)` (own enumerable) is empty.
+  // Class-body getters default to enumerable:false, so flip them in place.
+  for (const k of ["hardwareConcurrency", "language", "languages", "userAgent", "platform"]) {
+    Object.defineProperty(Navigator.prototype, k, { enumerable: true });
+  }
+  return { Navigator, instance: new Navigator() };
+}
+
+// Install the navigator backfill if and only if the running Node lacks the global
+// (i.e. Node < 21). Idempotent and side-effect-free on Node >= 21.
+export function installNavigatorShim() {
+  const major = parseInt(process.versions.node.split(".")[0], 10);
+  // Node 21+ ships navigator natively — never read the (possibly lazy) global here.
+  if (major >= 21) return;
+  // Defensive idempotency for the < 21 path (navigator is genuinely undefined there,
+  // so this read can't trigger a lazy realization).
+  if (typeof globalThis.navigator !== "undefined") return;
+
+  const { Navigator, instance } = makeNavigator();
+
+  // The binding on globalThis is NON-ENUMERABLE (invisible to Object.keys(globalThis)
+  // / for-in) — nub's additive-global contract, matching how reportError and Worker
+  // are installed. Configurable + writable so user code may still override it.
+  Object.defineProperty(globalThis, "navigator", {
+    value: instance,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  // Node also exposes the `Navigator` constructor globally; mirror it (non-enumerable).
+  if (typeof globalThis.Navigator === "undefined") {
+    Object.defineProperty(globalThis, "Navigator", {
+      value: Navigator,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+}
+
+// Fast tier / modern compat (getBuiltinModule present, Node >= 20.16): install eagerly
+// at module eval — a guaranteed no-op above Node 21 thanks to the version gate, and
+// correct on a 20.16–20.x compat run where navigator is still absent. On the narrow
+// floor below getBuiltinModule the compat entry calls setBootstrapCreateRequire(...)
+// + installNavigatorShim() explicitly (mirroring worker-polyfill's wiring).
+if (typeof process.getBuiltinModule === "function") installNavigatorShim();