relaxnative 0.1.1 → 0.1.2

package/README.md

@@ -55,6 +55,65 @@ Requirements:
 
 ## Quickstart
 
+### 0) Full end-to-end example (new folder → run)
+
+This is the fastest way to try Relaxnative in a clean folder.
+
+```bash
+mkdir -p my-relaxnative-app/native
+cd my-relaxnative-app
+npm init -y
+npm i relaxnative
+```
+
+Optional `package.json` (ESM + a run script):
+
+```json
+{
+  "name": "my-relaxnative-app",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "relaxnative": "^0.1.0"
+  }
+}
+```
+
+Create `native/add.c`:
+
+```c
+// @sync
+int add(int a, int b) {
+  return a + b;
+}
+```
+
+Create `index.js`:
+
+```js
+import { loadNative } from 'relaxnative';
+
+const mod = await loadNative('native/add.c', { isolation: 'worker' });
+console.log('add(1,2)=', mod.add(1, 2));
+```
+
+Run it:
+
+```bash
+npm start
+```
+
+If something goes wrong, re-run with tracing:
+
+```bash
+RELAXNATIVE_TRACE=1 npm start
+```
+
+---
+
 ### 1) Create a native file
 
 `native/add.c`
@@ -77,6 +136,30 @@ console.log(mod.add(1, 2));
 
 ---
 
+## Tracing (RELAXNATIVE_TRACE)
+
+When native code crashes or a worker/process boundary hides the real error, enable tracing.
+
+```bash
+RELAXNATIVE_TRACE=1 node index.js
+```
+
+More control:
+
+- `RELAXNATIVE_TRACE=1` enables trace events.
+- `RELAXNATIVE_TRACE_LEVEL=info|debug` controls verbosity (default: `info`).
+
+What you’ll see (examples):
+
+- Load lifecycle: `loadNative.begin`, `loadNative.build.begin`, `loadNative.build.done`, `loadNative.done`
+- Parsed signatures (debug): `loadNative.bindings`
+- Dispatch decisions: `dispatch`, `isolation.worker.dispatch`, `isolation.process.call`
+- Process helper lifecycle: `isolation.process.helper.start|exit|error`
+
+Tip: `RELAXNATIVE_TRACE_LEVEL=debug` will print parsed function signatures.
+
+---
+
 ## API
 
 ### `loadNative(sourcePath, options?)`
@@ -119,16 +202,56 @@ console.log(buf.address); // numeric pointer
 - fastest
 - unsafe: native crashes take down your Node process
 
+Example:
+
+```js
+import { loadNative } from 'relaxnative';
+
+const mod = await loadNative('native/add.c', { isolation: 'in-process' });
+console.log(mod.add(1, 2));
+```
+
 ### `worker`
 - worker-thread dispatch for async calls
 - sync calls may execute directly for low overhead
 
+Example (async heavy work):
+
+```c
+// native/heavy.c
+// @async
+int heavy(int n) {
+  long x = 0;
+  for (int i = 0; i < n * 10000000; i++) x += i;
+  return (int)x;
+}
+```
+
+```js
+import { loadNative } from 'relaxnative';
+
+const mod = await loadNative('native/heavy.c', { isolation: 'worker' });
+const result = await mod.heavy(5);
+console.log(result);
+```
+
 ### `process`
 - forked helper process
 - crash containment
 - best-effort Node runtime guards (module import denial for fs/network/spawn)
 - call timeout enforcement (kills helper)
 
+Example:
+
+```js
+import { loadNative } from 'relaxnative';
+
+// Process isolation always returns async wrappers.
+const mod = await loadNative('native/heavy.c', { isolation: 'process' });
+const result = await mod.heavy(5);
+console.log(result);
+```
+
 ---
 
 ## Annotations
@@ -140,6 +263,13 @@ Supported:
 - `@async`
 - `@cost low|medium|high`
 
+### Annotation + isolation quick rules
+
+- `@sync` + `in-process`: fastest, but a crash kills your app.
+- `@sync` + `worker`: may execute directly (fast) unless the binding is marked async/high-cost.
+- `@async` + `worker`: always goes through the worker thread and returns a Promise.
+- `process` isolation: **always async**, regardless of annotations (IPC boundary).
+
 ### What annotations mean
 
 - `@sync`

package/dist/chunk-CRQZJC5B.js

@@ -0,0 +1,397 @@
+// src/worker/workerPool.ts
+import { Worker } from "worker_threads";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+var WORKER_ENTRY_TS_URL = new URL(
+  "./workerEntry.vitest.ts",
+  import.meta.url
+);
+var WORKER_ENTRY_JS_URL = new URL("./workerEntry.js", import.meta.url);
+var worker = null;
+var seq = 0;
+var pending = /* @__PURE__ */ new Map();
+function getWorker() {
+  if (!worker) {
+    if (existsSync(fileURLToPath(WORKER_ENTRY_JS_URL))) {
+      worker = new Worker(WORKER_ENTRY_JS_URL, {
+        env: { ...process.env }
+      });
+    } else {
+      const entryHref = WORKER_ENTRY_TS_URL.href;
+      const bootstrap = `import(${JSON.stringify(entryHref)});`;
+      worker = new Worker(bootstrap, {
+        eval: true,
+        env: { ...process.env }
+      });
+    }
+    worker.on("message", (msg) => {
+      const resolve = pending.get(msg.id);
+      if (resolve) {
+        resolve(msg);
+        pending.delete(msg.id);
+      }
+    });
+  }
+  return worker;
+}
+function runInWorker(req) {
+  const id = ++seq;
+  const w = getWorker();
+  return new Promise((resolve, reject) => {
+    pending.set(id, (res) => {
+      if (res.error) {
+        const err = new Error(res.error + (res.errorCallsite ? `
+--- remote callsite ---
+${res.errorCallsite}` : ""));
+        reject(err);
+      } else resolve(res.result);
+    });
+    w.postMessage({ ...req, id });
+  });
+}
+
+// src/dx/logger.ts
+var enabled = false;
+function isDebugEnabled() {
+  return enabled || process.env.RELAXNATIVE_DEBUG === "1";
+}
+function logDebug(...args) {
+  if (!isDebugEnabled()) return;
+  console.log("[relaxnative]", ...args);
+}
+
+// src/utils/callsite.ts
+function captureCallsite() {
+  const err = new Error();
+  if (!err.stack) return void 0;
+  const parts = err.stack.split("\n");
+  if (parts.length <= 2) return err.stack;
+  return parts.slice(2).join("\n");
+}
+
+// src/dx/trace.ts
+import { performance } from "perf_hooks";
+function envTraceEnabled() {
+  const v = process.env.RELAXNATIVE_TRACE;
+  return v === "1" || v === "true" || v === "yes";
+}
+function envTraceLevel() {
+  const v = (process.env.RELAXNATIVE_TRACE_LEVEL ?? "").toLowerCase();
+  if (v === "error" || v === "warn" || v === "info" || v === "debug") return v;
+  return "info";
+}
+var order = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+function shouldTrace(level) {
+  if (!envTraceEnabled()) return false;
+  return order[level] <= order[envTraceLevel()];
+}
+function trace(level, event, data) {
+  if (!shouldTrace(level)) return;
+  const payload = {
+    t: Number(performance.now().toFixed(3)),
+    pid: process.pid,
+    level,
+    event
+  };
+  if (data !== void 0) payload.data = data;
+  console.log("[relaxnative:trace]", JSON.stringify(payload));
+}
+function traceError(event, data) {
+  trace("error", event, data);
+}
+function traceInfo(event, data) {
+  trace("info", event, data);
+}
+function traceDebug(event, data) {
+  trace("debug", event, data);
+}
+function formatBindingSignature(binding) {
+  if (!binding) return "";
+  const name = binding?.name ?? "<anonymous>";
+  const returns = binding?.returns ?? "void";
+  const args = Array.isArray(binding?.args) ? binding.args : [];
+  return `${returns} ${name}(${args.join(", ")})`;
+}
+
+// src/worker/workerClient.ts
+function callAsync(libPath, bindings, fn, args) {
+  const callsite = captureCallsite();
+  logDebug("worker dispatch", { fn, callsite: !!callsite });
+  traceDebug("isolation.worker.dispatch", {
+    fn,
+    libPath,
+    argc: args?.length ?? 0,
+    argTypes: Array.isArray(args) ? args.map((a) => {
+      if (a == null) return String(a);
+      if (ArrayBuffer.isView(a)) return a.constructor?.name ?? "TypedArray";
+      return typeof a;
+    }) : [],
+    hasCallsite: !!callsite
+  });
+  return runInWorker({ libPath, bindings, fn, args, callsite });
+}
+
+// src/worker/processClient.ts
+import { fork } from "child_process";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { dirname, join } from "path";
+import { existsSync as existsSync2 } from "fs";
+var ProcessIsolationError = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+};
+var child = null;
+var seq2 = 0;
+var pending2 = /* @__PURE__ */ new Map();
+function helperEntryPath() {
+  const here = dirname(fileURLToPath2(import.meta.url));
+  let cur = here;
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(cur, "package.json");
+    if (existsSync2(candidate)) {
+      const pkgRoot2 = cur;
+      const distEntry2 = join(pkgRoot2, "dist", "worker", "processEntry.js");
+      return { distEntry: distEntry2, pkgRoot: pkgRoot2 };
+    }
+    const parent = join(cur, "..");
+    if (parent === cur) break;
+    cur = parent;
+  }
+  const pkgRoot = join(here, "..", "..");
+  const distEntry = join(pkgRoot, "dist", "worker", "processEntry.js");
+  return { distEntry, pkgRoot };
+}
+function startChild() {
+  if (child && child.connected) return child;
+  const { distEntry } = helperEntryPath();
+  if (!existsSync2(distEntry)) {
+    traceError("isolation.process.helper.missing", { distEntry });
+    throw new ProcessIsolationError(
+      "ISOLATED_PROCESS_START_FAILED",
+      `Process isolation helper was not found at: ${distEntry}. This usually means the package was published without dist/worker/processEntry.js`,
+      { distEntry }
+    );
+  }
+  const entry = distEntry;
+  traceInfo("isolation.process.helper.start", { entry });
+  const cp = fork(entry, {
+    stdio: ["ignore", "inherit", "inherit", "ipc"],
+    env: {
+      ...process.env,
+      RELAXNATIVE_PROCESS_ISOLATION: "1"
+    }
+  });
+  cp.on("message", (msg) => {
+    if (!msg || typeof msg.id !== "number") return;
+    const p = pending2.get(msg.id);
+    if (!p) return;
+    if (p.cp !== cp) return;
+    pending2.delete(msg.id);
+    const res = msg;
+    if (res.ok) p.resolve(res.result);
+    else {
+      const details = [res.error.message];
+      if (res.error.callsite) details.push("\n--- remote callsite ---\n" + res.error.callsite);
+      const err = new Error(details.join("\n"));
+      err.name = res.error.name;
+      err.stack = res.error.stack;
+      p.reject(err);
+    }
+  });
+  const rejectAll = (reason) => {
+    for (const [id, p] of pending2) {
+      if (p.cp !== cp) continue;
+      pending2.delete(id);
+      p.reject(reason);
+    }
+  };
+  cp.on("exit", (code, signal) => {
+    if (child === cp) child = null;
+    const reason = new ProcessIsolationError(
+      signal ? "ISOLATED_PROCESS_CRASH" : "ISOLATED_PROCESS_EXIT",
+      `Isolated runtime exited (code=${code}, signal=${signal ?? "none"})`,
+      { code, signal }
+    );
+    traceError("isolation.process.helper.exit", { code, signal });
+    rejectAll(reason);
+  });
+  cp.on("error", (err) => {
+    const reason = new ProcessIsolationError(
+      "ISOLATED_PROCESS_START_FAILED",
+      `Failed to start isolated runtime: ${String(err)}`,
+      { err }
+    );
+    traceError("isolation.process.helper.error", { message: String(err) });
+    child = null;
+    rejectAll(reason);
+  });
+  child = cp;
+  return cp;
+}
+async function ping(cp) {
+  const id = ++seq2;
+  const req = { id, type: "ping" };
+  traceDebug("isolation.process.ping", { id });
+  return new Promise((resolve, reject) => {
+    pending2.set(id, { resolve, reject, cp });
+    cp.send(req);
+  });
+}
+async function callIsolated(libPath, bindings, fn, args, safety, callsite) {
+  const cp = startChild();
+  await ping(cp);
+  const id = ++seq2;
+  traceDebug("isolation.process.call", {
+    id,
+    fn,
+    argc: args?.length ?? 0,
+    hasSafety: !!safety,
+    hasCallsite: !!callsite
+  });
+  const req = {
+    id,
+    type: "call",
+    libPath,
+    bindings,
+    safety,
+    fn,
+    args,
+    // forward the captured JS callsite for richer crash diagnostics
+    ...callsite ? { callsite } : {}
+  };
+  const timeoutMs = safety?.limits?.timeoutMs;
+  const baseCall = new Promise((resolve, reject) => {
+    let t = null;
+    let timedOut = false;
+    const wrappedResolve = (v) => {
+      if (timedOut) return;
+      if (t) clearTimeout(t);
+      resolve(v);
+    };
+    const wrappedReject = (e) => {
+      if (timedOut) return;
+      if (t) clearTimeout(t);
+      reject(e);
+    };
+    if (typeof timeoutMs === "number" && timeoutMs > 0) {
+      t = setTimeout(() => {
+        timedOut = true;
+        pending2.delete(id);
+        try {
+          cp.kill();
+        } catch {
+        }
+        wrappedReject(
+          new ProcessIsolationError(
+            "ISOLATED_PROCESS_CRASH",
+            `Isolated runtime exceeded timeout (${timeoutMs}ms)`,
+            { timeoutMs }
+          )
+        );
+      }, timeoutMs);
+    }
+    pending2.set(id, { resolve: wrappedResolve, reject: wrappedReject, cp });
+    cp.send(req);
+  });
+  if (typeof timeoutMs === "number" && timeoutMs > 0) {
+    return Promise.race([
+      baseCall,
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(
+            new ProcessIsolationError(
+              "ISOLATED_PROCESS_CRASH",
+              `Isolated runtime exceeded timeout (${timeoutMs}ms)`,
+              { timeoutMs }
+            )
+          );
+        }, timeoutMs + 25);
+      })
+    ]);
+  }
+  return baseCall;
+}
+
+// src/worker/wrapFunctions.ts
+function wrapFunctions(api, libPath, bindings, opts) {
+  const wrapped = {};
+  const isolation = opts?.isolation ?? "worker";
+  const safety = bindings?.__safety ?? { trust: "local" };
+  const bindingNames = Object.keys(bindings?.functions ?? {});
+  const apiNames = Object.keys(api ?? {});
+  const names = Array.from(/* @__PURE__ */ new Set([...bindingNames, ...apiNames]));
+  for (const name of names) {
+    const fn = api?.[name];
+    const binding = bindings?.functions?.[name];
+    const isAsync = binding?.mode === "async" || binding?.async === true || binding?.thread === "worker" || binding?.cost === "high";
+    wrapped[name] = (...args) => {
+      traceDebug("dispatch", {
+        isolation,
+        fn: name,
+        argc: args?.length ?? 0,
+        mode: binding?.mode,
+        cost: binding?.cost
+      });
+      if (isolation === "process") {
+        return callIsolated(libPath, bindings, name, args, safety);
+      }
+      if (isolation === "worker") {
+        if (typeof fn === "function" && !isAsync) {
+          return fn(...args);
+        }
+        return callAsync(libPath, bindings, name, args);
+      }
+      if (typeof fn !== "function") {
+        const available = Object.keys(api ?? {});
+        const sig = binding ? formatBindingSignature(binding) : void 0;
+        const detail = [
+          `Function not found: ${name}`,
+          sig ? `Signature (from parser): ${sig}` : void 0,
+          available.length ? `Available exports: ${available.join(", ")}` : void 0
+        ].filter(Boolean);
+        throw new Error(detail.join("\n"));
+      }
+      return fn(...args);
+    };
+  }
+  if (isolation === "process") {
+    wrapped.__call = (fn, ...args) => callIsolated(libPath, bindings, fn, args, safety, captureCallsite());
+    return new Proxy(wrapped, {
+      get(target, prop) {
+        if (typeof prop !== "string") return target[prop];
+        if (prop === "then") return void 0;
+        if (prop in target) return target[prop];
+        return (...args) => callIsolated(libPath, bindings, prop, args, safety, captureCallsite());
+      }
+    });
+  }
+  if (isolation === "worker") {
+    return new Proxy(wrapped, {
+      get(target, prop) {
+        if (typeof prop !== "string") return target[prop];
+        if (prop === "then") return void 0;
+        if (prop in target) return target[prop];
+        return (...args) => callAsync(libPath, bindings, prop, args);
+      }
+    });
+  }
+  return wrapped;
+}
+
+export {
+  logDebug,
+  traceInfo,
+  traceDebug,
+  formatBindingSignature,
+  wrapFunctions
+};