@nubjs/nub-linux-arm64 0.1.14 → 0.2.0

package/package.json

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

package/runtime/preload.cjs

@@ -218,6 +218,17 @@ function installLazyEsmPolyfills() {
     return;
   }
 
+  // Main thread: install blob: worker support EAGERLY. It only wraps
+  // URL.createObjectURL + subclasses Blob (touches no node:worker_threads, so it's
+  // cold-start-cheap) and MUST be live before user code calls createObjectURL —
+  // which happens before the first `new Worker`, so it cannot wait for the lazy
+  // Worker load below. See runtime/worker-blob-url.cjs.
+  try {
+    __require("./worker-blob-url.cjs").installBlobUrlSupport();
+  } catch {
+    // blob: worker support is best-effort; never block startup on it.
+  }
+
   // Main thread: lazy Worker global. Defined NON-ENUMERABLE so it stays invisible
   // to `Object.keys(globalThis)` / for-in — the additive contract — matching how
   // worker-polyfill.mjs defines the real one.

package/runtime/version.mjs

@@ -9,4 +9,4 @@
 // previously lived as a literal inside preload.mjs, which `make version` patched,
 // while the worker carried a hand-maintained "…-compat" copy that `make version`
 // never touched — a latent staleness bug this module closes.)
-export const NUB_VERSION = "0.1.14";
+export const NUB_VERSION = "0.2.0";

package/runtime/worker-blob-url.cjs

@@ -0,0 +1,116 @@
+// Blob-URL worker source capture — the SYNC half of WHATWG `blob:` worker support.
+//
+// A `new Worker(blobUrl)` must read the Blob's source SYNCHRONOUSLY in the
+// constructor, but a Blob's bytes are only readable via the async Blob.text /
+// arrayBuffer. We close that gap by snapshotting the source at
+// `URL.createObjectURL(blob)` time — which always runs BEFORE the Worker is
+// constructed — into a registry keyed by the minted URL.
+//
+// This lives in its OWN tiny CJS module (no node:worker_threads dependency) so the
+// main-thread preload can install the wrap EAGERLY: it must be live before user
+// code calls createObjectURL, whereas worker-polyfill.mjs (which pulls
+// worker_threads + the whole streams/worker-io builtin set) is loaded LAZILY on
+// first `new Worker` to protect cold start. The Worker class imports THIS module to
+// read `blobUrlSources`. Touches only URL / Blob / Buffer — all already-realized
+// core globals — so requiring it adds nothing to the main-thread bootstrap set.
+
+// blob: URL → source text. Shared with worker-polyfill.mjs's Worker constructor.
+const blobUrlSources = new Map();
+// Blob construction parts, remembered so createObjectURL can assemble source sync.
+const blobParts = new WeakMap();
+
+function decode(parts) {
+  let src = "";
+  for (const p of parts ?? []) {
+    if (typeof p === "string") src += p;
+    else if (typeof Buffer !== "undefined" && Buffer.isBuffer(p)) src += p.toString("utf8");
+    else if (ArrayBuffer.isView(p)) src += Buffer.from(p.buffer, p.byteOffset, p.byteLength).toString("utf8");
+    else if (p instanceof ArrayBuffer) src += Buffer.from(p).toString("utf8");
+    else if (typeof p === "object" && p && typeof p.size === "number") {
+      const nested = blobParts.get(p); // a nested Blob made via our wrapper
+      if (nested) src += decode(nested);
+    }
+  }
+  return src;
+}
+
+// Wrap URL.createObjectURL/revokeObjectURL and Proxy Blob to remember parts.
+// Idempotent + transparent for every non-worker use. No-op when URL has no
+// createObjectURL (older floors) — blob: workers are then simply unavailable.
+//
+// The install-marker is a Symbol, not a string property: it sits on the native
+// Blob constructor (a shared global), so a string key would show up in
+// `Reflect.ownKeys(Blob)` / `"x" in Blob` — a (cosmetic) divergence from vanilla
+// Node. A Symbol keeps the marker invisible to those reflective surfaces.
+const INSTALLED = Symbol.for("nub.blobUrlSupport.installed");
+function installBlobUrlSupport() {
+  if (typeof URL === "undefined" || typeof URL.createObjectURL !== "function") return;
+  if (URL.createObjectURL[INSTALLED]) return;
+
+  const NativeBlob = globalThis.Blob;
+  if (typeof NativeBlob === "function" && !NativeBlob[INSTALLED]) {
+    // Record construction parts WITHOUT changing Blob's identity. The earlier
+    // approach — a `class extends NativeBlob` swapped onto globalThis.Blob — broke
+    // brand identity in two ways that a structured-clone exposes:
+    //   1. A deserialized Blob (postMessage / structuredClone) is a NATIVE Blob, so
+    //      `cloned instanceof globalThis.Blob` was FALSE (subclass.prototype is not
+    //      in a native instance's chain) — a spec violation; native Node passes.
+    //   2. WORSE, undici's webidl `is.Blob` uses the ORDINARY `[Symbol.hasInstance]`
+    //      (a prototype-chain check that ignores a custom hasInstance) against
+    //      `globalThis.Blob`, so `new Response(clonedBlob).arrayBuffer()` failed the
+    //      brand check and stringified the Blob to "[object Blob]" (13 bytes) instead
+    //      of reading its bytes. A custom `Symbol.hasInstance` can't fix this — undici
+    //      bypasses it.
+    // The ROOT cause was `globalThis.Blob !== node:buffer.Blob`. A Proxy whose target
+    // is the native Blob keeps `globalThis.Blob.prototype === NativeBlob.prototype`,
+    // so every native Blob (constructed OR deserialized) passes both `instanceof` and
+    // undici's ordinary-hasInstance check exactly as on vanilla Node — while the
+    // `construct` trap still records parts for sync blob: worker source assembly. File
+    // (which `extends` native Blob) then needs NO re-parenting: its instances already
+    // have NativeBlob.prototype in their chain.
+    const BlobProxy = new Proxy(NativeBlob, {
+      construct(target, args, newTarget) {
+        // FORWARD newTarget so a user subclass (`class X extends Blob {}`) gets ITS
+        // prototype — passing `target` here would force NativeBlob.prototype and
+        // silently break `new X() instanceof X` + the subclass's methods (an
+        // additivity violation vs vanilla Node). When `new Blob(...)` is called
+        // directly, newTarget IS this Proxy; Reflect.construct(NativeBlob, args, Proxy)
+        // resolves the new instance's proto from `Proxy.prototype`, which the Proxy
+        // forwards to NativeBlob.prototype — so a direct Blob is byte-identical to a
+        // native one (same brand, passes instanceof + undici's webidl check).
+        const inst = Reflect.construct(target, args, newTarget);
+        if (args[0] != null) blobParts.set(inst, args[0]);
+        return inst;
+      },
+    });
+    Object.defineProperty(NativeBlob, INSTALLED, { value: true });
+    Object.defineProperty(globalThis, "Blob", {
+      value: BlobProxy,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+    // File's `extends` link still points at the real NativeBlob (unchanged), so
+    // `new File(...) instanceof Blob` holds natively — no re-parenting needed.
+  }
+
+  const nativeCreate = URL.createObjectURL.bind(URL);
+  const nativeRevoke =
+    typeof URL.revokeObjectURL === "function" ? URL.revokeObjectURL.bind(URL) : null;
+  const wrappedCreate = function createObjectURL(obj) {
+    const url = nativeCreate(obj);
+    const parts = blobParts.get(obj);
+    if (parts) blobUrlSources.set(url, decode(parts));
+    return url;
+  };
+  Object.defineProperty(wrappedCreate, INSTALLED, { value: true });
+  URL.createObjectURL = wrappedCreate;
+  if (nativeRevoke) {
+    URL.revokeObjectURL = function revokeObjectURL(url) {
+      blobUrlSources.delete(url);
+      return nativeRevoke(url);
+    };
+  }
+}
+
+module.exports = { blobUrlSources, installBlobUrlSupport };

package/runtime/worker-polyfill.mjs

@@ -87,76 +87,199 @@ function getErrorEventCtor() {
 export function installWorkerPolyfill() {
   const { Worker: NodeWorker, parentPort, isMainThread } = __getBuiltin("node:worker_threads");
   const { fileURLToPath } = __getBuiltin("node:url");
+  // blob: worker source registry, shared with the eager main-thread preload that
+  // wraps URL.createObjectURL (worker-blob-url.cjs). Loaded via createRequire so
+  // both this lazily-loaded ESM module and the eager CJS preload reference the SAME
+  // module instance (Node dedupes by resolved path) — i.e. the SAME blobUrlSources.
+  const { blobUrlSources, installBlobUrlSupport } = (
+    typeof process.getBuiltinModule === "function"
+      ? __getBuiltin("node:module").createRequire(import.meta.url)
+      : _bootstrapCreateRequire(import.meta.url)
+  )("./worker-blob-url.cjs");
+
+  // Resolve a worker-error stack frame to {filename,lineno,colno} so the
+  // ErrorEvent carries real source location, per WHATWG §10.2.6 (the spec
+  // requires these fields populated from where the error was raised). Node's
+  // `error` event delivers the thrown Error; we read its first stack frame.
+  // Browser-scrubbing of cross-origin frames does not apply here (all worker
+  // sources are same-origin local), so we surface the raw location.
+  //
+  // The frame is anchored at `at ` and consumes the optional `Func (` wrapper so
+  // group 1 is JUST the path (a `file://` URL, an absolute POSIX path, or a
+  // Windows `C:\…` path — the leading `C:` is NOT mistaken for the location
+  // colon because the line:col are the LAST two `:`-segments). Without the anchor
+  // + wrapper-consumption the path captured the `at Func (` prefix verbatim.
+  const STACK_FRAME = /^at\s+(?:.+?\s+\()?(.+?):(\d+):(\d+)\)?$/;
+  function locationFromError(err) {
+    let filename = "";
+    let lineno = 0;
+    let colno = 0;
+    const stack = err && typeof err.stack === "string" ? err.stack : "";
+    for (const line of stack.split("\n")) {
+      const t = line.trim();
+      if (!t.startsWith("at ")) continue;
+      const m = STACK_FRAME.exec(t);
+      if (m) {
+        filename = m[1].startsWith("file://") ? fileURLToPath(m[1]) : m[1];
+        lineno = Number(m[2]) || 0;
+        colno = Number(m[3]) || 0;
+        break;
+      }
+    }
+    return { filename, lineno, colno };
+  }
 
   if (typeof globalThis.Worker === "undefined") {
   class Worker extends EventTarget {
     #worker;
+    #name;
 
     constructor(url, options = {}) {
       super();
 
-      let workerPath;
-      if (url instanceof URL) {
-        workerPath = fileURLToPath(url);
-      } else if (typeof url === "string") {
-        if (url.startsWith("file://")) {
-          workerPath = fileURLToPath(url);
-        } else {
-          workerPath = url;
+      // The WHATWG Worker constructor accepts a script URL. Per §10.2.6.3 the
+      // standard inline mechanisms are `blob:` and `data:` URLs (there is no
+      // inline-source-string form in the spec). We map each to a Node spawn:
+      //   - file path / file: URL  → spawn the file (transpiled by nub's preload)
+      //   - data: URL              → Node runs it directly (worker_threads v14.9)
+      //   - blob: URL              → resolve the Blob via node:buffer, spawn its
+      //                              source with eval:true (Node can't open blob:)
+      let spawnTarget;
+
+      const asUrlString =
+        url instanceof URL ? url.href : typeof url === "string" ? url : null;
+      if (asUrlString === null) {
+        throw new TypeError("Worker constructor: url must be a string or URL");
+      }
+
+      if (asUrlString.startsWith("blob:")) {
+        // A `blob:` worker (WHATWG inline mechanism). Node cannot open a blob:
+        // URL as a worker entry, and the Blob's bytes are only readable
+        // ASYNCHRONOUSLY (Blob.text/arrayBuffer) while this constructor is sync.
+        // We close that gap by snapshotting the source SYNCHRONOUSLY at
+        // `URL.createObjectURL(blob)` time (see installBlobUrlSupport) into a
+        // module-scope registry keyed by URL, then spawn the source as a `data:`
+        // URL. We use data: (NOT eval:true) deliberately: the `--import` preload
+        // that installs nub's worker-side scope (self/postMessage) does NOT run in
+        // an eval:true worker on the compat-tier FLOOR (Node 18.19 — verified), so
+        // an eval-based blob worker has no `self` there; a data: URL worker is a
+        // real module load and DOES receive the preload on every supported tier.
+        const source = blobUrlSources.get(asUrlString);
+        if (source === undefined) {
+          throw new TypeError(
+            `Worker constructor: blob URL '${asUrlString}' is not a known object URL`
+          );
         }
+        spawnTarget = new URL(
+          "data:text/javascript;base64," + Buffer.from(source, "utf8").toString("base64")
+        );
+      } else if (asUrlString.startsWith("data:")) {
+        spawnTarget = new URL(asUrlString);
+      } else if (asUrlString.startsWith("file://")) {
+        spawnTarget = fileURLToPath(asUrlString);
       } else {
-        throw new TypeError("Worker constructor: url must be a string or URL");
+        spawnTarget = asUrlString;
       }
 
-      // `type: "module" | "classic"` is accepted for web compatibility but not
-      // enforced: Node decides module-vs-CJS for the worker entry by file
-      // extension + nearest package.json "type" (the same rule nub applies to
-      // the main entry), and there is no classic/importScripts mode. Passing
-      // `type` through to NodeWorker is harmless — it ignores unknown options.
-      // See wiki/research/worker-polyfill.md.
-      // Node rejects flags in Worker execArgv that imply V8 `--harmony-*`
-      // staging flags (ERR_WORKER_INVALID_EXEC_ARGV). Two categories to strip:
-      //   1. `--harmony-*` flags themselves (V8 internals; may land in execArgv
-      //      on some Node versions when the parent injected an `--experimental-*`
-      //      that implies them).
-      //   2. `--experimental-shadow-realm` — implies `--harmony-shadow-realm`
-      //      (Node rejects it for workers even though the flag name is not
-      //      `--harmony-*`). This is the only nub-injected experimental flag
-      //      that has this property; other experimentals nub injects
-      //      (--experimental-vm-modules, --experimental-wasm-modules, etc.) are
-      //      fine in worker execArgv. Extend this filter if Node adds more.
-      this.#worker = new NodeWorker(workerPath, {
+      this.#name = typeof options.name === "string" ? options.name : "";
+
+      // `type: "module" | "classic"` selects the worker's module system per the
+      // spec. The worker-side scope exposes `importScripts` only for classic
+      // workers (WHATWG WorkerGlobalScope — classic-only) and throws for module
+      // workers. nub signals the choice to the worker via the internal
+      // NUB_WORKER_TYPE env (internal plumbing var — exempt from the brand
+      // boundary). Node still decides the entry's actual module/CJS PARSING by
+      // file extension + package.json "type"; this env governs only which
+      // importScripts surface the polyfill installs.
+      const workerType =
+        options.type === "classic" ? "classic" : "module";
+
+      // Node rejects flags in Worker execArgv that imply V8 `--harmony-*` staging
+      // flags (ERR_WORKER_INVALID_EXEC_ARGV): `--harmony-*` themselves, and
+      // `--experimental-shadow-realm` (implies `--harmony-shadow-realm`). Strip
+      // those from whatever execArgv we forward.
+      const stripHarmony = (argv) =>
+        argv.filter(
+          f => !f.startsWith("--harmony") && f !== "--experimental-shadow-realm"
+        );
+      // execArgv: forward nub's preload-carrying parent execArgv by DEFAULT (so a
+      // worker inherits nub's transpile augmentation), but if the user supplied
+      // their own execArgv, MERGE rather than clobber — parent flags first, user
+      // flags appended so the user's win on conflict.
+      const execArgv = stripHarmony(
+        Array.isArray(options.execArgv)
+          ? [...process.execArgv, ...options.execArgv]
+          : process.execArgv
+      );
+
+      const nodeOptions = {
         ...options,
         eval: false,
-        execArgv: process.execArgv.filter(
-          f => !f.startsWith("--harmony") && f !== "--experimental-shadow-realm"
-        ),
-      });
+        execArgv,
+      };
+      // Thread the worker type AND name to the worker via internal env vars
+      // (NUB_WORKER_TYPE / NUB_WORKER_NAME — internal plumbing, exempt from the
+      // brand boundary). NUB_WORKER_NAME is REQUIRED for self.name across the
+      // whole compat tier: worker_threads.threadName (the only native worker-side
+      // reader of the {name} option) lands in v24.6.0 / v22.20.0, so it is absent
+      // below that and the env is the sole portable carrier. We avoid disturbing
+      // the user's env semantics: `worker_threads.SHARE_ENV` is a Symbol
+      // (live-shared parent env) — spreading it would destroy the share — so in
+      // that case we leave env untouched (self.name then falls back to native
+      // threadName/"" and importScripts defaults to the classic form).
+      const userEnv = options.env;
+      if (typeof userEnv === "symbol") {
+        // SHARE_ENV: leave nodeOptions.env as the user gave it; can't inject.
+      } else {
+        nodeOptions.env = {
+          ...(userEnv ?? process.env),
+          NUB_WORKER_TYPE: workerType,
+          NUB_WORKER_NAME: this.#name,
+        };
+      }
+      if (this.#name) nodeOptions.name = this.#name;
+
+      this.#worker = new NodeWorker(spawnTarget, nodeOptions);
 
       this.#worker.on("message", (data) => {
         this.dispatchEvent(new MessageEvent("message", { data }));
       });
 
-      this.#worker.on("messageerror", (err) => {
-        this.dispatchEvent(new MessageEvent("messageerror", { data: err }));
+      // WHATWG: messageerror fires when an inbound message fails deserialization;
+      // it is a plain MessageEvent with `data: null` (NOT carrying the error).
+      this.#worker.on("messageerror", () => {
+        this.dispatchEvent(new MessageEvent("messageerror", { data: null }));
       });
 
       this.#worker.on("error", (err) => {
         const ErrorEventCtor = getErrorEventCtor();
-        this.dispatchEvent(new ErrorEventCtor("error", { error: err, message: err.message }));
+        const { filename, lineno, colno } = locationFromError(err);
+        this.dispatchEvent(
+          new ErrorEventCtor("error", {
+            error: err,
+            message: err.message,
+            filename,
+            lineno,
+            colno,
+          })
+        );
       });
+      // No `exit` event: WHATWG Workers have no exit event (it is a
+      // node:worker_threads concept, not part of the web Worker surface).
+    }
 
-      this.#worker.on("exit", (code) => {
-        this.dispatchEvent(new Event("exit"));
-      });
+    get name() {
+      return this.#name;
     }
 
     postMessage(data, transfer) {
       this.#worker.postMessage(data, transfer);
     }
 
+    // WHATWG terminate() returns void. Node's returns a Promise; we discard it so
+    // the surface matches the spec (the underlying termination still proceeds).
     terminate() {
-      return this.#worker.terminate();
+      this.#worker.terminate();
     }
 
     #onmessageHandler = null;
@@ -194,6 +317,11 @@ export function installWorkerPolyfill() {
     writable: true,
     configurable: true,
   });
+
+  // Enable blob: workers: wrap URL.createObjectURL so the source is captured
+  // synchronously for the constructor's blob: branch. Transparent for all other
+  // uses; installs once. Only on the main thread (where blob: URLs are minted).
+  if (isMainThread) installBlobUrlSupport();
 }
 
 // Worker-side bootstrap: emulate the DedicatedWorkerGlobalScope on top of
@@ -221,6 +349,81 @@ if (!isMainThread && parentPort) {
     });
   defineGlobal("self", scope);
 
+  // `self.name` — the worker's name from the constructor's {name} option (WHATWG
+  // DedicatedWorkerGlobalScope.name). Node only exposes a worker-side reader for
+  // the {name} option as `worker_threads.threadName` from v24.6.0 / v22.20.0 — it
+  // is ABSENT across nub's whole compat tier (18.19–22.19), so it cannot be the
+  // floor mechanism. We THREAD the name in ourselves via the internal
+  // NUB_WORKER_NAME env (internal plumbing var — exempt from the brand boundary),
+  // set by the main-side constructor.
+  //
+  // RESOLUTION ORDER — env FIRST (not native threadName): NUB_WORKER_NAME carries
+  // the user's EXACT intent including the empty string, whereas native
+  // `threadName` defaults to the literal sentinel "WorkerThread" for an UNNAMED
+  // worker (it's the thread DISPLAY name, not the WHATWG worker name) — surfacing
+  // that as self.name would be a spec divergence (an unnamed worker's name must be
+  // ""). So: the injected env wins when present; native threadName is the fallback
+  // ONLY on the SHARE_ENV path (where the ctor couldn't inject env), with the
+  // "WorkerThread" sentinel filtered to "".
+  {
+    const wt = __getBuiltin("node:worker_threads");
+    let name;
+    if (typeof process.env.NUB_WORKER_NAME === "string") {
+      name = process.env.NUB_WORKER_NAME;
+    } else {
+      const tn = wt && typeof wt.threadName === "string" ? wt.threadName : "";
+      name = tn === "WorkerThread" ? "" : tn;
+    }
+    Object.defineProperty(scope, "name", {
+      value: name,
+      enumerable: false,
+      writable: true,
+      configurable: true,
+    });
+  }
+
+  // `importScripts(...urls)` — WHATWG WorkerGlobalScope, CLASSIC workers only.
+  // Synchronously fetches + evaluates each script in the global scope, in order.
+  // A module worker MUST throw on importScripts (use `import` instead). nub learns
+  // the worker's type from NUB_WORKER_TYPE (set by the main-side constructor).
+  // Remote URLs are not supported (no sync network in Node); local file:/relative
+  // paths and data: URLs are read synchronously.
+  // Default to the classic (working) importScripts when the type is unset — this
+  // is the SHARE_ENV edge where the constructor couldn't inject NUB_WORKER_TYPE.
+  if (process.env.NUB_WORKER_TYPE !== "module") {
+    const fs = __getBuiltin("node:fs");
+    const { fileURLToPath: f2p, pathToFileURL } = __getBuiltin("node:url");
+    defineGlobal("importScripts", (...urls) => {
+      for (const u of urls) {
+        const s = String(u);
+        let code;
+        if (s.startsWith("data:")) {
+          const comma = s.indexOf(",");
+          const meta = s.slice(5, comma);
+          const body = s.slice(comma + 1);
+          code = meta.includes("base64")
+            ? Buffer.from(body, "base64").toString("utf8")
+            : decodeURIComponent(body);
+        } else if (/^https?:/.test(s)) {
+          throw new TypeError(
+            "importScripts: remote URLs are not supported (no synchronous network)"
+          );
+        } else {
+          const path = s.startsWith("file://") ? f2p(s) : s;
+          code = fs.readFileSync(path, "utf8");
+        }
+        // Indirect eval → runs in global scope, matching importScripts semantics.
+        (0, eval)(code);
+      }
+    });
+  } else {
+    // Module workers: importScripts must throw (spec). Provide the throwing form
+    // so the surface exists and the error is the spec-correct one.
+    defineGlobal("importScripts", () => {
+      throw new TypeError("importScripts is not available in module workers");
+    });
+  }
+
   // `message`/`messageerror` are DELEGATED straight onto the native `parentPort`
   // (a real Node MessagePort) so Node's own C++ event-loop ref-counting governs
   // worker lifetime: a worker that never listens leaves parentPort with no