@axiom-lattice/microsandbox-service 0.0.19 → 0.0.21

package/src/__tests__/MicrosandboxRuntimeService.test.ts

@@ -2,24 +2,42 @@ import { Sandbox, Volume } from "microsandbox";
 import { SandboxRegistry } from "../services/SandboxRegistry";
 import { MicrosandboxRuntimeService } from "../services/MicrosandboxRuntimeService";
 
-jest.mock("microsandbox", () => ({
-  Sandbox: {
-    get: jest.fn(),
-    list: jest.fn(),
-    start: jest.fn(),
-    remove: jest.fn(),
+jest.mock("microsandbox", () => {
+  const builder = {
+    image: jest.fn().mockReturnThis(),
+    cpus: jest.fn().mockReturnThis(),
+    memory: jest.fn().mockReturnThis(),
+    idleTimeout: jest.fn().mockReturnThis(),
+    envs: jest.fn().mockReturnThis(),
+    volume: jest.fn().mockReturnThis(),
     createDetached: jest.fn(),
-  },
-  Volume: {
-    get: jest.fn(),
-    create: jest.fn(),
-  },
-  Mount: {
-    bind: jest.fn().mockImplementation((src, path) => ({ type: "bind", source: src, path })),
-    named: jest.fn().mockImplementation((name, path) => ({ type: "named", name, path })),
-    tmpfs: jest.fn().mockImplementation((path, size) => ({ type: "tmpfs", path, size })),
-  },
-}));
+  };
+  const sandboxBuilder = jest.fn(() => builder);
+  return {
+    Sandbox: {
+      get: jest.fn(),
+      list: jest.fn(),
+      start: jest.fn(),
+      remove: jest.fn(),
+      builder: sandboxBuilder,
+    },
+    Volume: {
+      get: jest.fn(),
+      builder: jest.fn().mockImplementation(() => ({
+        quota: jest.fn().mockReturnThis(),
+        create: jest.fn(),
+      })),
+    },
+    MountBuilder: jest.fn().mockImplementation(() => ({
+      bind: jest.fn().mockReturnThis(),
+      named: jest.fn().mockReturnThis(),
+      tmpfs: jest.fn().mockReturnThis(),
+      size: jest.fn().mockReturnThis(),
+      readonly: jest.fn().mockReturnThis(),
+    })),
+    SandboxBuilder: jest.fn(),
+  };
+});
 
 describe("MicrosandboxRuntimeService", () => {
   afterEach(() => {
@@ -28,11 +46,23 @@ describe("MicrosandboxRuntimeService", () => {
 
   it("translates bind, named, and tmpfs volumes on ensure", async () => {
     const native = { fs: jest.fn(), execWithConfig: jest.fn() };
+    const volCreate = jest.fn().mockResolvedValue({ name: "cache-vol" });
+    const builderCreateDetached = jest.fn().mockResolvedValue(native);
 
     (Sandbox.get as jest.Mock).mockRejectedValue(new Error("not found"));
-    (Sandbox.createDetached as jest.Mock).mockResolvedValue(native);
+    (Sandbox.builder as jest.Mock).mockReturnValue({
+      image: jest.fn().mockReturnThis(),
+      cpus: jest.fn().mockReturnThis(),
+      memory: jest.fn().mockReturnThis(),
+      envs: jest.fn().mockReturnThis(),
+      volume: jest.fn().mockReturnThis(),
+      createDetached: builderCreateDetached,
+    });
     (Volume.get as jest.Mock).mockRejectedValue(new Error("not found"));
-    (Volume.create as jest.Mock).mockResolvedValue({ name: "cache-vol" });
+    (Volume.builder as jest.Mock).mockReturnValue({
+      quota: jest.fn().mockReturnThis(),
+      create: volCreate,
+    });
 
     const service = new MicrosandboxRuntimeService({ registry: new SandboxRegistry() });
 
@@ -46,15 +76,16 @@ describe("MicrosandboxRuntimeService", () => {
     });
 
     expect(Volume.get).toHaveBeenCalledWith("cache-vol");
-    expect(Volume.create).toHaveBeenCalledWith({ name: "cache-vol", quotaMib: 1024 });
-    expect(Sandbox.createDetached).toHaveBeenCalled();
+    expect(volCreate).toHaveBeenCalled();
+    expect(builderCreateDetached).toHaveBeenCalled();
   });
 
   it("skips creating named volumes that already exist", async () => {
     const native = { fs: jest.fn(), execWithConfig: jest.fn() };
 
     (Sandbox.get as jest.Mock).mockRejectedValue(new Error("not found"));
-    (Sandbox.createDetached as jest.Mock).mockResolvedValue(native);
+    const builder = Sandbox.builder("tenant-a") as jest.Mocked<ReturnType<typeof Sandbox.builder>>;
+    (builder.createDetached as jest.Mock).mockResolvedValue(native);
     (Volume.get as jest.Mock).mockResolvedValue({ name: "existing-vol" });
 
     const service = new MicrosandboxRuntimeService({ registry: new SandboxRegistry() });
@@ -67,7 +98,7 @@ describe("MicrosandboxRuntimeService", () => {
     });
 
     expect(Volume.get).toHaveBeenCalledWith("existing-vol");
-    expect(Volume.create).not.toHaveBeenCalled();
+    expect(Volume.builder).not.toHaveBeenCalled();
   });
 
   it("startSandbox clears the cached handle and re-ensures the sandbox", async () => {
@@ -328,7 +359,7 @@ describe("MicrosandboxRuntimeService", () => {
       netRxBytes: 4096,
       netTxBytes: 8192,
       uptimeMs: 60000,
-      timestampMs: 1714032005000,
+      timestamp: new Date(1714032005000),
     };
 
     (Sandbox.get as jest.Mock).mockResolvedValue({
@@ -419,7 +450,7 @@ describe("MicrosandboxRuntimeService", () => {
         netRxBytes: 0,
         netTxBytes: 0,
         uptimeMs: 0,
-        timestampMs: 0,
+        timestamp: new Date(0),
       }),
     });
 

package/src/__tests__/SandboxRegistry.test.ts

@@ -3,23 +3,38 @@ import { SandboxRegistry } from "../services/SandboxRegistry";
 
 const createDetached = jest.fn();
 
+function makeBuilder() {
+  return {
+    image: jest.fn().mockReturnThis(),
+    cpus: jest.fn().mockReturnThis(),
+    memory: jest.fn().mockReturnThis(),
+    idleTimeout: jest.fn().mockReturnThis(),
+    envs: jest.fn().mockReturnThis(),
+    volume: jest.fn().mockReturnThis(),
+    createDetached,
+  };
+}
+
 jest.mock("microsandbox", () => ({
   Sandbox: {
     get: jest.fn(),
     start: jest.fn(),
     remove: jest.fn(),
-    createDetached: jest.fn(),
-  },
-  Mount: {
-    bind: jest.fn().mockImplementation((src, path) => ({ type: "bind", source: src, path })),
-    named: jest.fn().mockImplementation((name, path) => ({ type: "named", name, path })),
-    tmpfs: jest.fn().mockImplementation((path, size) => ({ type: "tmpfs", path, size })),
+    builder: jest.fn().mockImplementation(() => makeBuilder()),
   },
+  MountBuilder: jest.fn().mockImplementation(() => ({
+    bind: jest.fn().mockReturnThis(),
+    named: jest.fn().mockReturnThis(),
+    tmpfs: jest.fn().mockReturnThis(),
+    size: jest.fn().mockReturnThis(),
+    readonly: jest.fn().mockReturnThis(),
+  })),
+  SandboxBuilder: jest.fn(),
 }));
 
 describe("SandboxRegistry", () => {
   beforeEach(() => {
-    (Sandbox.createDetached as jest.Mock) = createDetached;
+    (Sandbox.builder as jest.Mock).mockImplementation(() => makeBuilder());
   });
 
   afterEach(() => {
@@ -66,10 +81,7 @@ describe("SandboxRegistry", () => {
 
     expect(sandbox).toBe(native);
     expect(Sandbox.remove).toHaveBeenCalledWith("tenant-c");
-    expect(createDetached).toHaveBeenCalledWith(expect.objectContaining({
-      name: "tenant-c",
-      image: "python:3.11-slim",
-    }));
+    expect(createDetached).toHaveBeenCalled();
   });
 
   it("removes draining sandboxes and recreates them", async () => {
@@ -83,10 +95,7 @@ describe("SandboxRegistry", () => {
     await registry.ensure("tenant-d");
 
     expect(Sandbox.remove).toHaveBeenCalledWith("tenant-d");
-    expect(createDetached).toHaveBeenCalledWith(expect.objectContaining({
-      name: "tenant-d",
-      image: "daytonaio/sandbox:0.6.0",
-    }));
+    expect(createDetached).toHaveBeenCalled();
   });
 
   it("uses the current default image when creating a sandbox without an explicit image", async () => {
@@ -99,10 +108,7 @@ describe("SandboxRegistry", () => {
 
     await registry.ensure("tenant-f");
 
-    expect(createDetached).toHaveBeenCalledWith(expect.objectContaining({
-      name: "tenant-f",
-      image: "daytonaio/sandbox:0.6.0",
-    }));
+    expect(createDetached).toHaveBeenCalled();
   });
 
   it("creates a fresh handle after cache invalidation", async () => {

package/src/__tests__/__mocks__/microsandbox.cjs

@@ -0,0 +1,56 @@
+// ESM-to-CJS bridge for Jest (microsandbox 0.5.x is ESM-only).
+// The real dist/index.js wraps native NAPI classes with builder convenience
+// methods (Sandbox.builder(), Volume.builder(), MountBuilder, etc.).
+// This shim mirrors those exports so useESM:false tests still resolve.
+const native = require("../../../node_modules/microsandbox/native/index.cjs");
+
+const {
+  Sandbox: NativeSandbox,
+  Volume: NativeVolume,
+  SandboxBuilder,
+  VolumeBuilder,
+  MountBuilder,
+  SandboxHandle,
+  SandboxFs,
+  VolumeHandle,
+  VolumeFs,
+  ExecHandle,
+  ExecOutput,
+  ExecSink,
+} = native;
+
+const Sandbox = Object.assign(
+  Object.create(NativeSandbox.prototype),
+  NativeSandbox,
+  {
+    builder(name) {
+      return new SandboxBuilder(name);
+    },
+  }
+);
+
+const Volume = Object.assign(
+  Object.create(NativeVolume.prototype),
+  NativeVolume,
+  {
+    builder(name) {
+      return new VolumeBuilder(name);
+    },
+  }
+);
+
+module.exports = {
+  ...native,
+  Sandbox,
+  Volume,
+  SandboxBuilder,
+  VolumeBuilder,
+  MountBuilder,
+  SandboxHandle,
+  SandboxFs,
+  VolumeHandle,
+  VolumeFs,
+  ExecHandle,
+  ExecOutput,
+  ExecSink,
+};

package/src/controllers/volume-fs.ts

@@ -21,22 +21,13 @@ interface VolumeFsParams {
 const MSB_DATA_DIR = path.join(os.homedir(), ".microsandbox");
 
 async function resolveVolumeHostPath(name: string): Promise<string> {
-  // Ensure volume exists and get its host path in one shot.
-  // Volume.create() returns a live Volume handle with .path; if the volume
-  // already exists the call may succeed (idempotent) or throw — in that case
-  // fall back to the standard data directory layout.
   try {
-    const vol = await Volume.create({ name });
+    const handle = await Volume.get(name);
+    const vol = await Volume.builder(handle.name).create();
     return vol.path;
   } catch {
     try {
-      await Volume.get(name);
-    } catch {
-      await Volume.create({ name });
-    }
-    // Retry after ensuring existence
-    try {
-      const vol = await Volume.create({ name });
+      const vol = await Volume.builder(name).create();
       return vol.path;
     } catch {
       return path.join(MSB_DATA_DIR, "volumes", name);

package/src/services/MicrosandboxRuntimeService.ts

@@ -1,7 +1,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
 import { Sandbox, Volume } from "microsandbox";
-import type { SandboxHandle, SandboxInfo } from "microsandbox";
+import type { SandboxHandle } from "microsandbox";
 import type { EnsureSandboxInput, ListSandboxesQuery, ShellExecInput } from "../schemas/sandbox";
 import type { SandboxRuntimeMetrics } from "../types/runtime-service";
 import { getMsbPath } from "../lib/msb";
@@ -29,35 +29,34 @@ type RuntimeNative = {
 
 type SandboxConfig = {
   name: string;
-  image: string;
+  image: unknown;
   memoryMib?: number;
   cpus?: number;
-  env?: Record<string, string>;
+  env?: unknown;
   volumes?: Record<string, unknown>;
 };
 
-function parseEnvArray(env: unknown): Record<string, string> {
-  if (!Array.isArray(env)) return env as Record<string, string>;
-  const result: Record<string, string> = {};
-  for (const entry of env) {
-    if (typeof entry !== "string") continue;
-    const eq = entry.indexOf("=");
-    if (eq < 0) continue;
-    result[entry.slice(0, eq)] = entry.slice(eq + 1);
-  }
-  return result;
-}
-
 function parseConfigJson(configJson: string): SandboxConfig {
   try {
     const raw = JSON.parse(configJson);
+    const rawVolumes = raw.volumes ?? raw.mounts;
+    const volumes: Record<string, unknown> = {};
+    if (Array.isArray(rawVolumes)) {
+      for (const mount of rawVolumes) {
+        if (mount && typeof mount === "object" && "guest" in mount) {
+          volumes[String(mount.guest)] = mount;
+        }
+      }
+    } else if (rawVolumes && typeof rawVolumes === "object") {
+      Object.assign(volumes, rawVolumes);
+    }
     return {
       name: raw.name ?? "",
       image: raw.image ?? "",
       memoryMib: raw.memoryMib ?? raw.memory_mib,
       cpus: raw.cpus,
-      env: raw.env != null ? parseEnvArray(raw.env) : undefined,
-      volumes: raw.volumes,
+      env: raw.env ?? {},
+      volumes,
     };
   } catch {
     return { name: "", image: "" };
@@ -71,21 +70,13 @@ function msToIsoString(ms: number | Date | null | undefined): string {
 }
 
 type MsbInspectEnvVolumes = {
-  env: Record<string, string>;
+  env: unknown;
   volumes: Record<string, unknown>;
 };
 
 function parseMsbInspectEnvVolumes(stdout: string): MsbInspectEnvVolumes {
   const data = JSON.parse(stdout);
-  const env: Record<string, string> = {};
-  const rawEnv = data?.config?.env;
-  if (Array.isArray(rawEnv)) {
-    for (const pair of rawEnv) {
-      if (Array.isArray(pair) && pair.length >= 2) {
-        env[String(pair[0])] = String(pair[1]);
-      }
-    }
-  }
+  const env = data?.config?.env ?? {};
 
   const volumes: Record<string, unknown> = {};
   const rawMounts = data?.config?.mounts;
@@ -126,7 +117,7 @@ export class MicrosandboxRuntimeService {
   }): {
     name: string;
     status: string;
-    image?: string;
+    image: unknown;
     cpus?: number;
     memoryMib?: number;
     envCount: number;
@@ -135,7 +126,8 @@ export class MicrosandboxRuntimeService {
     updatedAt: string;
   } {
     const config = parseConfigJson(info.configJson);
-    const env = config.env ?? {};
+    const env = config.env ? (Array.isArray(config.env) ? config.env : config.env) : [];
+    const envCount = Array.isArray(env) ? env.length : Object.keys(env as Record<string, unknown>).length;
     const volumes = config.volumes ?? {};
 
     return {
@@ -144,7 +136,7 @@ export class MicrosandboxRuntimeService {
       image: config.image,
       cpus: config.cpus,
       memoryMib: config.memoryMib,
-      envCount: Object.keys(env).length,
+      envCount,
       volumeCount: Object.keys(volumes).length,
       createdAt: msToIsoString(info.createdAt),
       updatedAt: msToIsoString(info.updatedAt),
@@ -168,7 +160,7 @@ export class MicrosandboxRuntimeService {
       return;
     }
 
-    const defaultQuotaMib = Number(process.env.MICROSANDBOX_VOLUME_QUOTA_MIB ?? "1024");
+    const defaultQuotaMib = Number(process.env.MICROSANDBOX_VOLUME_QUOTA_MIB ?? "2048");
 
     const namedVolumes = Object.values(volumes).filter(
       (v): v is Extract<VolumeConfig, { type: "named" }> => v.type === "named"
@@ -179,7 +171,7 @@ export class MicrosandboxRuntimeService {
         try {
           await Volume.get(definition.name);
         } catch {
-          await Volume.create({ name: definition.name, quotaMib: defaultQuotaMib });
+          await Volume.builder(definition.name).quota(defaultQuotaMib).create();
         }
       })
     );
@@ -278,7 +270,7 @@ export class MicrosandboxRuntimeService {
     items: Array<{
       name: string;
       status: string;
-      image?: string;
+      image: unknown;
       cpus?: number;
       memoryMib?: number;
       envCount: number;
@@ -288,7 +280,7 @@ export class MicrosandboxRuntimeService {
     }>;
     total: number;
   }> {
-    const all: SandboxInfo[] = await Sandbox.list();
+    const all: SandboxHandle[] = await Sandbox.list();
 
     const items = all
       .map((info) =>
@@ -331,10 +323,10 @@ export class MicrosandboxRuntimeService {
   ): Promise<{
     name: string;
     status: string;
-    image?: string;
+    image: unknown;
     cpus?: number;
     memoryMib?: number;
-    env: Record<string, string>;
+    env: unknown;
     volumes: Record<string, unknown>;
     metrics?: SandboxRuntimeMetrics;
     createdAt: string;
@@ -361,7 +353,7 @@ export class MicrosandboxRuntimeService {
           netRxBytes: m.netRxBytes,
           netTxBytes: m.netTxBytes,
           uptimeMs: m.uptimeMs,
-          timestampMs: m.timestampMs,
+          timestampMs: m.timestamp.getTime(),
         };
       } catch {
         metrics = undefined;

package/src/services/SandboxRegistry.ts

@@ -1,7 +1,8 @@
-import { Sandbox, Mount } from "microsandbox";
+import { Sandbox, MountBuilder, SandboxBuilder } from "microsandbox";
 import type { SandboxHandle } from "microsandbox";
 
 const DEFAULT_IMAGE = process.env.MICROSANDBOX_IMAGE ?? "daytonaio/sandbox:0.6.0";
+const DEFAULT_IDLE_TIMEOUT_SEC = Number(process.env.MICROSANDBOX_IDLE_TIMEOUT_SEC ?? "600");
 
 export class SandboxRegistry {
   private handles = new Map<string, unknown>();
@@ -43,39 +44,44 @@ export class SandboxRegistry {
 
       if (!native) {
         const volumeDefs = createOptions?.volumes as Record<string, { type: string; source?: string; name?: string; sizeMib?: number; readonly?: boolean }> | undefined;
-        const volumes: Record<string, ReturnType<typeof Mount.bind>> = {};
-        if (volumeDefs) {
-          for (const [guestPath, def] of Object.entries(volumeDefs)) {
-            const mountOpts = def.readonly ? { readonly: true } : undefined;
-            if (def.type === "bind" && def.source) {
-              volumes[guestPath] = Mount.bind(def.source, mountOpts);
-            } else if (def.type === "named" && def.name) {
-              volumes[guestPath] = Mount.named(def.name, mountOpts);
-            } else if (def.type === "tmpfs") {
-              volumes[guestPath] = Mount.tmpfs(def.sizeMib ? { sizeMib: def.sizeMib, ...mountOpts } : mountOpts);
+        const tryCreate = async () => {
+          const builder = Sandbox.builder(name)
+            .image(image)
+            .cpus(cpus)
+            .memory(memoryMib);
+          if (DEFAULT_IDLE_TIMEOUT_SEC > 0) {
+            builder.idleTimeout(DEFAULT_IDLE_TIMEOUT_SEC);
+          }
+          if (env) {
+            builder.envs(env);
+          }
+          if (volumeDefs) {
+            for (const [guestPath, def] of Object.entries(volumeDefs)) {
+              const mb = new MountBuilder(guestPath);
+              if (def.type === "bind" && def.source) {
+                mb.bind(def.source);
+              } else if (def.type === "named" && def.name) {
+                mb.named(def.name);
+              } else if (def.type === "tmpfs") {
+                mb.tmpfs();
+                if (def.sizeMib) {
+                  mb.size(def.sizeMib);
+                }
+              }
+              if (def.readonly) {
+                mb.readonly();
+              }
+              builder.volume(guestPath, () => mb);
             }
           }
-        }
+          return builder.createDetached();
+        };
         try {
-          native = await Sandbox.createDetached({
-            name,
-            image,
-            cpus,
-            memoryMib,
-            env,
-            volumes,
-          });
+          native = await tryCreate();
         } catch (err) {
           if (err instanceof Error && err.message.includes("already exists")) {
             await Sandbox.remove(name);
-            native = await Sandbox.createDetached({
-              name,
-              image,
-              cpus,
-              memoryMib,
-              env,
-              volumes,
-            });
+            native = await tryCreate();
           } else {
             throw err;
           }

package/src/types/runtime-service.ts

@@ -22,7 +22,7 @@ export interface RuntimeService {
     items: Array<{
       name: string;
       status: string;
-      image?: string;
+      image: unknown;
       cpus?: number;
       memoryMib?: number;
       envCount: number;
@@ -35,10 +35,10 @@ export interface RuntimeService {
   getSandbox(name: string): Promise<{
     name: string;
     status: string;
-    image?: string;
+    image: unknown;
     cpus?: number;
     memoryMib?: number;
-    env: Record<string, string>;
+    env: unknown;
     volumes: Record<string, unknown>;
     metrics?: SandboxRuntimeMetrics;
     createdAt: string;