@supermachine/core 0.4.25

package/index.js

@@ -0,0 +1,290 @@
+// @supermachine/core — entry point.
+//
+// 1. Locates the platform-specific .node addon (shipped in
+//    @supermachine/core-<platform>-<arch>, installed via npm's
+//    optionalDependencies + os/cpu filter).
+// 2. Sets SUPERMACHINE_WORKER_BIN in process.env so the underlying
+//    Rust crate finds the pre-signed worker binary that ships
+//    alongside the .node file. Done BEFORE require()'ing the
+//    addon so the Rust module_init picks it up.
+// 3. Re-exports the napi classes (Image, Pool, Vm).
+
+const { existsSync } = require("node:fs");
+const { join, dirname } = require("node:path");
+
+// Map (process.platform, process.arch) → npm package name + binary
+// filename. napi-rs's CLI auto-generates these names per platform;
+// keep this table in sync with the matrix in the release workflow.
+const TARGETS = {
+  "darwin-arm64": {
+    pkg: "@supermachine/core-darwin-arm64",
+    nodeFile: "supermachine-core.darwin-arm64.node",
+    workerFile: "supermachine-worker",
+  },
+  // Future targets — add when KVM/WHP backends land:
+  // "linux-arm64-gnu":  { pkg: "@supermachine/core-linux-arm64-gnu",
+  //                       nodeFile: "supermachine-core.linux-arm64-gnu.node",
+  //                       workerFile: "supermachine-worker" },
+  // "linux-x64-gnu":    { ... },
+  // "win32-x64-msvc":   { ... },
+};
+
+function platformKey() {
+  // libc detection (musl vs glibc) goes here when we add linux
+  // targets; for now darwin-arm64 is the only supported combo.
+  return `${process.platform}-${process.arch}`;
+}
+
+function resolvePlatformPackage() {
+  const key = platformKey();
+  const target = TARGETS[key];
+  if (!target) {
+    const supported = Object.keys(TARGETS).join(", ");
+    throw new Error(
+      `@supermachine/core: no prebuilt binary for ${key}. ` +
+        `Supported: ${supported}. ` +
+        `Linux KVM and Windows WHP support are on the roadmap; ` +
+        `for now use macOS on Apple Silicon, or call the Rust crate ` +
+        `directly via FFI.`,
+    );
+  }
+
+  // Two resolution strategies, in order:
+  //   1. Sibling node_modules — production install: the platform
+  //      package was installed as an optionalDependency.
+  //   2. Local dev path — when working in this monorepo, the
+  //      .node file sits in npm/<platform>/ next to this index.js.
+  let pkgDir;
+  try {
+    // require.resolve points at the package.json; dirname is the
+    // package root.
+    pkgDir = dirname(require.resolve(`${target.pkg}/package.json`));
+  } catch (_) {
+    pkgDir = join(__dirname, "npm", key);
+  }
+
+  const nodePath = join(pkgDir, target.nodeFile);
+  if (!existsSync(nodePath)) {
+    throw new Error(
+      `@supermachine/core: native addon not found at ${nodePath}. ` +
+        `If you installed via npm, this is a bug — please report it. ` +
+        `If you're running from source, build it first: ` +
+        `\`cd npm/supermachine-core && npm run build\`.`,
+    );
+  }
+
+  const workerPath = join(pkgDir, target.workerFile);
+  return { nodePath, workerPath };
+}
+
+const { nodePath, workerPath } = resolvePlatformPackage();
+
+// Point the Rust crate's worker-locator at the bundled binary.
+// Must happen BEFORE require()'ing the addon — the addon's
+// module_init reads SUPERMACHINE_WORKER_BIN on first call.
+//
+// Don't clobber an explicit user-set value (devs running against
+// a custom-built worker need that to win).
+if (!process.env.SUPERMACHINE_WORKER_BIN && existsSync(workerPath)) {
+  process.env.SUPERMACHINE_WORKER_BIN = workerPath;
+}
+
+const addon = require(nodePath);
+
+// Wrap addon.Image.build to massage the JS-friendly API into the
+// Rust signature:
+//   - JS user writes:   `Image.build({ ref: "...", warmup: async (vm) => ... })`
+//   - Rust expects:     `Image.build(options, warmup?)` (two args, warmup
+//                       can't be inside the options object because
+//                       JsFunction isn't Send)
+//   - Inside the warmup callback, JS user calls `vm.exec(...)`. The
+//     Rust side passes us a string (the exec-socket path); we wrap
+//     it into a Vm-like object that delegates to addon._execAtPath.
+//
+// This is invisible to JS users — they see the documented API:
+//
+//   Image.build({
+//     ref: "rust:1-slim",
+//     warmup: async (vm) => { await vm.exec({ argv: [...] }) },
+//   })
+class Image {
+  static async build(options = {}) {
+    const { warmup, ...rest } = options;
+    if (warmup === undefined) {
+      return wrapImageInstance(await addon.Image.build(rest, null));
+    }
+    // Wrap user's warmup with a Vm-like adapter. Rust passes the
+    // exec-socket path as the callback arg; we build a Vm object
+    // whose .exec delegates to _execAtPath. The Rust side awaits
+    // the Promise we return.
+    const wrappedWarmup = async (execPath) => {
+      const warmupVm = makeWarmupVm(execPath);
+      try {
+        await warmup(warmupVm);
+      } finally {
+        warmupVm._invalidate();
+      }
+    };
+    return wrapImageInstance(await addon.Image.build(rest, wrappedWarmup));
+  }
+  static async fromSnapshot(path) {
+    return wrapImageInstance(await addon.Image.fromSnapshot(path));
+  }
+}
+
+// Wrap a native Image instance with our prototype-extending shim so
+// `image.pool(...)` returns Pool (instead of the raw addon Pool).
+// Image getters (snapshotPath / memoryMib / vcpus) are read-once at
+// wrap time — they're stable for the lifetime of the snapshot, and
+// re-reading on every access would burn an unnecessary napi
+// roundtrip per property read.
+function wrapImageInstance(native) {
+  return {
+    async pool(options) {
+      return wrapPoolInstance(await native.pool(options ?? null));
+    },
+    get snapshotPath() {
+      return native.snapshotPath;
+    },
+    get memoryMib() {
+      return native.memoryMib;
+    },
+    get vcpus() {
+      return native.vcpus;
+    },
+  };
+}
+
+function wrapPoolInstance(native) {
+  return {
+    async acquire() {
+      return wrapVmInstance(await native.acquire());
+    },
+    async shutdown() {
+      return native.shutdown();
+    },
+    // Sync — fast (~1 µs, just a mutex lock under the hood).
+    stats() {
+      return native.stats();
+    },
+  };
+}
+
+function wrapVmInstance(native) {
+  const handle = {
+    async exec(options) {
+      return native.exec(options);
+    },
+    async spawn(options) {
+      return wrapExecChild(await native.spawn(options));
+    },
+    async writeFile(path, bytes) {
+      return native.writeFile(path, bytes);
+    },
+    async readFile(path) {
+      return native.readFile(path);
+    },
+    async snapshot(destDir) {
+      return wrapImageInstance(await native.snapshot(destDir));
+    },
+    async workloadSignal(signum) {
+      return native.workloadSignal(signum);
+    },
+    async exposeTcp(hostPort, guestPort) {
+      return wrapTcpForwarder(await native.exposeTcp(hostPort, guestPort));
+    },
+    // Path accessors are sync — they're just String getters on the
+    // native side. Throw if the Vm has been released (the native
+    // getter rejects with a descriptive Error).
+    get vsockPath() {
+      return native.vsockPath;
+    },
+    get execPath() {
+      return native.execPath;
+    },
+    async release() {
+      return native.release();
+    },
+    async dispose() {
+      return native.dispose();
+    },
+  };
+  // Symbol.asyncDispose support (Node 20+ disposer pattern).
+  if (typeof Symbol.asyncDispose === "symbol") {
+    handle[Symbol.asyncDispose] = () => handle.release();
+  }
+  return handle;
+}
+
+function wrapExecChild(native) {
+  return {
+    async writeStdin(bytes) {
+      return native.writeStdin(bytes);
+    },
+    async closeStdin() {
+      return native.closeStdin();
+    },
+    async readStdout(maxBytes) {
+      return native.readStdout(maxBytes ?? null);
+    },
+    async readStderr(maxBytes) {
+      return native.readStderr(maxBytes ?? null);
+    },
+    async signal(signum) {
+      return native.signal(signum);
+    },
+    async resize(cols, rows) {
+      return native.resize(cols, rows);
+    },
+    async wait() {
+      return native.wait();
+    },
+  };
+}
+
+// Thin wrapper around the napi TcpForwarder class. We could return
+// the raw instance, but the shim approach keeps the JS API
+// consistent (everything else is a plain object) and lets us add
+// JS-only behavior (e.g. a `Symbol.dispose` future) without
+// reaching into the napi class.
+function wrapTcpForwarder(native) {
+  return {
+    get localAddr() {
+      return native.localAddr;
+    },
+    async stop() {
+      return native.stop();
+    },
+  };
+}
+
+// Build a Vm-like object backed by an exec-socket path. Used inside
+// the warmup callback — the Rust side passes us the path string,
+// JS code uses this object as if it were a normal Vm.
+function makeWarmupVm(execPath) {
+  let valid = true;
+  const vm = {
+    async exec(options) {
+      if (!valid) {
+        throw new Error(
+          "warmup Vm is no longer valid — the warmup callback returned. " +
+            "Don't hold references to the Vm past the callback; do all " +
+            "your exec calls inside it.",
+        );
+      }
+      return addon.execAtPath(execPath, options);
+    },
+    _invalidate() {
+      valid = false;
+    },
+  };
+  // Disallow `using vm` on warmup vms — they're not regular pool
+  // entries and don't have a release-to-pool semantics.
+  return vm;
+}
+
+module.exports = {
+  Image,
+  Pool: addon.Pool,
+  Vm: addon.Vm,
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@supermachine/core",
+  "version": "0.4.25",
+  "description": "Run any OCI/Docker image as a hardware-isolated microVM. Node/Bun/Deno binding for the supermachine Rust crate.",
+  "license": "Apache-2.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE",
+    "examples/"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "optionalDependencies": {
+    "@supermachine/core-darwin-arm64": "0.4.25"
+  },
+  "scripts": {
+    "build:rust": "TYPE_DEF_TMP_PATH=$(pwd)/scripts/.napi_type_defs.tmp cargo build --release -p supermachine-napi && cargo build --release --bin supermachine-worker -p supermachine",
+    "build:dts": "node ./scripts/gen-dts.js ./scripts/.napi_type_defs.tmp ./index.d.ts",
+    "build": "rm -f ./scripts/.napi_type_defs.tmp && npm run build:rust && npm run build:dts && node ./scripts/postbuild.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.6.2",
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/supercorp/supermachine"
+  },
+  "homepage": "https://github.com/supercorp/supermachine/tree/main/npm/supermachine-core#readme",
+  "bugs": {
+    "url": "https://github.com/supercorp/supermachine/issues"
+  },
+  "keywords": [
+    "microvm",
+    "hypervisor",
+    "oci",
+    "docker",
+    "snapshot",
+    "sandbox",
+    "vm",
+    "macos",
+    "hvf",
+    "apple-silicon"
+  ]
+}