B3：macOS 原生接入 Runtime（立在 B1 上，包含 #427）

api/agent/src/client.js

@@ -17,16 +17,17 @@ export const BACKEND = /^(backend|runtime)\./;
 
 /** Runs one operation once and returns its value or throws its refusal;
  * `options` are the client's settings, whose `trace` selects its trace file;
- * `transport` is the client's binding (default: the one a new client would use). */
-export async function invoke(op, args, options, transport = binding()) {
+ * `transport` is the client's binding (default: the one a new client of
+ * `args.project` would use). */
+export async function invoke(op, args, options, transport = binding(args.project)) {
   return outcome(await traced(options, op, args, (scope) => {
     if (BACKEND.test(op)) throw new LayerFSError("UnknownMethod", "backend and runtime methods are @layerfs/backend's and @layerfs/runtime's", null);
     return transport.call(op, observed(args, scope));
   }));
 }
 
 /** One call on the binding's backend table (`backend.*`, `runtime.*`). */
-export async function invokeBackend(op, args, options, transport = binding()) {
+export async function invokeBackend(op, args, options, transport = binding(args?.project)) {
   return outcome(await traced(options, op, args, (scope) => transport.backendCall(op, observed(args, scope))));
 }
 
@@ -60,9 +61,19 @@ export function sandboxArg(sandbox) {
 
 /** Deployment settings from the client options, else the environment
  * (LAYERFS_<NAME>). A Workspace's Sandbox needs
- * every one but the container prefix and daemon host. */
+ * every one but the container prefix and daemon host. With `sandbox`
+ * (LAYERFS_SANDBOX) `native` (Linux or macOS), a Sandbox is a host daemon:
+ * Linux uses FUSE with a root daemon and nonroot commands (501:20);
+ * macOS uses loopback NFS and this user. It needs the daemon and
+ * `localDir` (LAYERFS_LOCAL_DIR) and no Docker setting. Unset or `docker` is
+ * Docker; any other value is refused. */
 export function deployment(options = {}) {
   const env = (name) => process.env[`LAYERFS_${name}`] || undefined;
+  const sandbox = options.sandbox ?? env("SANDBOX");
+  if (sandbox === "native") return nativeDeployment(options, env, sandbox);
+  if (sandbox !== undefined && sandbox !== "docker") {
+    throw new LayerFSError("InvalidInput", `deploy.sandbox (LAYERFS_SANDBOX) is docker or native (Linux or macOS), not ${sandbox}`, null);
+  }
   const deploy = {
     docker: options.docker ?? env("DOCKER") ?? "/var/run/docker.sock",
     image: options.image ?? env("IMAGE"),
@@ -80,6 +91,35 @@ export function deployment(options = {}) {
   return deploy;
 }
 
+/** A native Sandbox's settings: the daemon, the directory its Sandboxes
+ * live in, the optional name prefix, and the backend inside that directory
+ * (`sandboxBackend`, LAYERFS_SANDBOX_BACKEND: `native` when unset, or
+ * `namespaces` on Linux). The namespaces backend gives each Sandbox a root
+ * filesystem from an image, so it also needs `image` (LAYERFS_IMAGE, the
+ * same digest Docker deploys) and `imageArchive` (LAYERFS_IMAGE_ARCHIVE, the
+ * docker-archive the bundle carries). */
+function nativeDeployment(options, env, sandbox) {
+  const deploy = {
+    sandbox,
+    daemon: options.daemon ?? env("DAEMON"),
+    localDir: options.localDir ?? env("LOCAL_DIR"),
+    containerPrefix: options.containerPrefix ?? env("CONTAINER_PREFIX"),
+  };
+  const backend = options.sandboxBackend ?? env("SANDBOX_BACKEND");
+  if (backend !== undefined) deploy.sandboxBackend = backend;
+  const required = [["daemon", "DAEMON"], ["localDir", "LOCAL_DIR"]];
+  if (backend === "namespaces") {
+    deploy.image = options.image ?? env("IMAGE");
+    deploy.imageArchive = options.imageArchive ?? env("IMAGE_ARCHIVE");
+    required.push(["image", "IMAGE"], ["imageArchive", "IMAGE_ARCHIVE"]);
+  }
+  for (const [name, setting] of required) {
+    if (!deploy[name]) throw new LayerFSError("InvalidInput", `deploy.${name} is not configured (LAYERFS_${setting})`, null);
+  }
+  if (!deploy.containerPrefix) delete deploy.containerPrefix;
+  return deploy;
+}
+
 /** Refuses every call on a closed client (or one no factory opened). */
 export function live(client) {
   if (client?.[STATE]?.closed !== false) {

api/agent/src/index.js

@@ -100,7 +100,15 @@ export class LayerFS {
    * settings read LAYERFS_HOME, _DOCKER, _IMAGE, _VOLUME and _DAEMON; a
    * Sandbox this client starts runs _IMAGE
    * on _VOLUME. LAYERFS_CONTAINER_PREFIX (default `layerfs-`) names every
-   * container it starts `<prefix><project>-<n>`.
+   * container it starts `<prefix><project>-<n>`. On Linux or macOS,
+   * LAYERFS_SANDBOX=native starts each Sandbox as a host daemon in a directory
+   * under LAYERFS_LOCAL_DIR. Linux requires root for FUSE and runs commands
+   * as 501:20; macOS uses loopback NFS and the caller's identity. No Docker
+   * setting is read; native provides no isolation from the host.
+   * LAYERFS_SANDBOX_BACKEND picks the backend inside that directory: `native`
+   * (unset) or, on Linux, `namespaces` (namespaces, cgroups, nonroot commands).
+   * It is read for every call, so a Sandbox made with one backend is never
+   * reopened as another.
    * LAYERFS_DAEMON_HOST is the host this process
    * dials for a daemon's port, published on the Docker host's 127.0.0.1 only;
    * set it when the client runs in a container (`host.docker.internal` on
@@ -129,13 +137,18 @@ export class LayerFS {
         volume: env("VOLUME"),
         daemon: env("DAEMON"),
         ...(env("CONTAINER_PREFIX") ? { containerPrefix: env("CONTAINER_PREFIX") } : {}),
+        ...(env("SANDBOX") ? { sandbox: env("SANDBOX") } : {}),
+        ...(env("SANDBOX_BACKEND") ? { sandboxBackend: env("SANDBOX_BACKEND") } : {}),
+        ...(env("LOCAL_DIR") ? { localDir: env("LOCAL_DIR") } : {}),
+        ...(env("IMAGE_ARCHIVE") ? { imageArchive: env("IMAGE_ARCHIVE") } : {}),
         ...(env("DAEMON_HOST") ? { daemonHost: env("DAEMON_HOST") } : {}),
       },
       storePolicy: env("STORE_POLICY"),
       storePath: env("STORE_PATH"),
     };
-    // not open until a factory has opened its Store; the binding is chosen now, once
-    this[STATE] = { closed: null, transport: binding() };
+    // not open until a factory has opened its Store; the binding is chosen now, once,
+    // for this client's project (a VM placement has one worker per project)
+    this[STATE] = { closed: null, transport: binding(this.projectName) };
     this.fs = bind(this, fsMethods);
     this.project = bind(this, { list_branches, list_sandboxes });
     this.branch = bind(this, { list_commits, diff_commits, diff_branches, fork, merge, publish });

api/agent/test/native_deployment.mjs

@@ -0,0 +1,143 @@
+// Which runtime a Sandbox uses. No real addon, Store or Docker (the
+// stand-in binding answers the client's calls):
+//   node api/agent/test/native_deployment.mjs
+// LAYERFS_SANDBOX unset or `docker` gives exactly the Docker deployment it
+// always gave; `native` (macOS) needs only the daemon and LAYERFS_LOCAL_DIR
+// (no Docker setting); any other value, the former `local` included, is
+// refused rather than taken as either.
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { deployment } from "../src/client.js";
+
+const FAKE = fileURLToPath(new URL("./fixture/fake-native.cjs", import.meta.url));
+const native = createRequire(import.meta.url)(FAKE);
+
+const clear = () => {
+  for (const name of Object.keys(process.env)) {
+    if (name.startsWith("LAYERFS_") || name.startsWith("DSH_LAYERFS_")) delete process.env[name];
+  }
+  process.env.LAYERFS_NATIVE = FAKE;
+};
+const docker = { docker: "/run/docker.sock", image: `sha256:${"a".repeat(64)}`, volume: "lfs-v", daemon: "/opt/layerfs-daemon" };
+const setDocker = () => {
+  process.env.LAYERFS_DOCKER = docker.docker;
+  process.env.LAYERFS_IMAGE = docker.image;
+  process.env.LAYERFS_VOLUME = docker.volume;
+  process.env.LAYERFS_DAEMON = docker.daemon;
+};
+const store = () => {
+  process.env.LAYERFS_HOME = "/private/local-home";
+  process.env.LAYERFS_STORE_PATH = "/fake/store.sqlite";
+};
+
+// unset: the Docker deployment, field for field
+clear();
+setDocker();
+assert.deepEqual(deployment(), docker);
+// `docker` is the same deployment
+process.env.LAYERFS_SANDBOX = "docker";
+assert.deepEqual(deployment(), docker);
+// the Docker settings are still required there
+delete process.env.LAYERFS_IMAGE;
+assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && /LAYERFS_IMAGE/.test(e.message));
+
+// native: daemon + localDir, no Docker setting read or required
+clear();
+process.env.LAYERFS_SANDBOX = "native";
+process.env.LAYERFS_DAEMON = "/opt/layerfs-daemon";
+process.env.LAYERFS_LOCAL_DIR = "/Users/me/lfs";
+assert.deepEqual(deployment(), { sandbox: "native", daemon: "/opt/layerfs-daemon", localDir: "/Users/me/lfs" });
+// an image (sandbox.create's option) does not change a native deployment
+assert.deepEqual(deployment({ image: docker.image }), { sandbox: "native", daemon: "/opt/layerfs-daemon", localDir: "/Users/me/lfs" });
+// the backend inside the directory is native unless named; namespaces is
+// passed through (the binding refuses it off Linux, and an unknown value)
+assert.equal(deployment().sandboxBackend, undefined);
+const archive = `/bundle/images/${"a".repeat(64)}.tar`;
+process.env.LAYERFS_SANDBOX_BACKEND = "namespaces";
+process.env.LAYERFS_IMAGE = docker.image;
+process.env.LAYERFS_IMAGE_ARCHIVE = archive;
+// a namespaces Sandbox's root is an image: the same digest Docker deploys
+// and the docker-archive the bundle carries
+assert.deepEqual(deployment(), {
+  sandbox: "native",
+  daemon: "/opt/layerfs-daemon",
+  localDir: "/Users/me/lfs",
+  sandboxBackend: "namespaces",
+  image: docker.image,
+  imageArchive: archive,
+});
+// each of those is named when it is missing
+delete process.env.LAYERFS_IMAGE;
+assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && /\(LAYERFS_IMAGE\)/.test(e.message));
+process.env.LAYERFS_IMAGE = docker.image;
+delete process.env.LAYERFS_IMAGE_ARCHIVE;
+assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && /\(LAYERFS_IMAGE_ARCHIVE\)/.test(e.message));
+process.env.LAYERFS_IMAGE_ARCHIVE = archive;
+// the native backend inside the same directory reads neither of them
+assert.deepEqual(deployment({ sandboxBackend: "native" }), {
+  sandbox: "native",
+  daemon: "/opt/layerfs-daemon",
+  localDir: "/Users/me/lfs",
+  sandboxBackend: "native",
+});
+delete process.env.LAYERFS_SANDBOX_BACKEND;
+delete process.env.LAYERFS_IMAGE;
+delete process.env.LAYERFS_IMAGE_ARCHIVE;
+// the container prefix names native Sandbox directories too
+process.env.LAYERFS_CONTAINER_PREFIX = "ci-";
+assert.equal(deployment().containerPrefix, "ci-");
+delete process.env.LAYERFS_CONTAINER_PREFIX;
+// each required setting is named when missing
+delete process.env.LAYERFS_LOCAL_DIR;
+assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && /LAYERFS_LOCAL_DIR/.test(e.message));
+process.env.LAYERFS_LOCAL_DIR = "/Users/me/lfs";
+delete process.env.LAYERFS_DAEMON;
+assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && /LAYERFS_DAEMON/.test(e.message));
+process.env.LAYERFS_DAEMON = "/opt/layerfs-daemon";
+// a DSH_LAYERFS_NFS_ name is not mapped (an integration maps its own names)
+process.env.DSH_LAYERFS_NFS_MOUNT = "/bin/true";
+deployment();
+assert.equal(process.env.LAYERFS_NFS_MOUNT, undefined);
+// since #428 the SDK reads LAYERFS_ names only: a DSH_LAYERFS_ twin selects nothing
+clear();
+setDocker();
+process.env.DSH_LAYERFS_SANDBOX = "native";
+process.env.DSH_LAYERFS_LOCAL_DIR = "/l";
+assert.deepEqual(deployment(), docker);
+
+// anything else, the former `local` included, is refused, never silently Docker
+for (const typo of ["local", "Native", "nativ", "NATIVE", "podman"]) {
+  clear();
+  setDocker();
+  process.env.LAYERFS_SANDBOX = typo;
+  assert.throws(() => deployment(), (e) => e.code === "InvalidInput" && e.message.includes(`not ${typo}`));
+}
+
+// a client reads LAYERFS_SANDBOX and LAYERFS_LOCAL_DIR once, and
+// sandbox.create sends the native deployment (no Docker setting)
+clear();
+store();
+process.env.LAYERFS_SANDBOX = "native";
+process.env.LAYERFS_DAEMON = "/opt/layerfs-daemon";
+process.env.LAYERFS_LOCAL_DIR = "/Users/me/lfs";
+const { LayerFS } = await import("../src/index.js");
+const client = await LayerFS.open("website");
+assert.equal(client.options.deploy.sandbox, "native");
+assert.equal(client.options.deploy.localDir, "/Users/me/lfs");
+const before = native.deploys.length;
+await client.sandbox.create();
+assert.deepEqual(native.deploys.slice(before), [{ sandbox: "native", daemon: "/opt/layerfs-daemon", localDir: "/Users/me/lfs" }]);
+// an image given to sandbox.create does not turn it into a Docker deployment
+await client.sandbox.create({ image: docker.image });
+assert.deepEqual(native.deploys.at(-1), { sandbox: "native", daemon: "/opt/layerfs-daemon", localDir: "/Users/me/lfs" });
+await client.close();
+// unset: the client carries no new key
+clear();
+store();
+setDocker();
+const plain = await LayerFS.open("website");
+assert.equal("sandbox" in plain.options.deploy, false);
+assert.equal("localDir" in plain.options.deploy, false);
+await plain.close();
+console.log("native_deployment: ok");