@axiom-lattice/microsandbox-service 0.0.1

package/src/schemas/sandbox.ts

@@ -0,0 +1,79 @@
+import z from "zod";
+
+const bindMountSchema = z.object({
+  type: z.literal("bind"),
+  source: z.string().min(1),
+  readonly: z.boolean().optional(),
+});
+
+const namedMountSchema = z.object({
+  type: z.literal("named"),
+  name: z.string().min(1),
+  readonly: z.boolean().optional(),
+});
+
+const tmpfsMountSchema = z.object({
+  type: z.literal("tmpfs"),
+  sizeMib: z.number().int().positive().optional(),
+});
+
+export const volumeSchema = z.union([
+  bindMountSchema,
+  namedMountSchema,
+  tmpfsMountSchema,
+]);
+
+export const ensureSandboxSchema = z.object({
+  image: z.string().optional(),
+  cpus: z.number().int().positive().optional(),
+  memoryMib: z.number().int().positive().optional(),
+  env: z.record(z.string()).optional(),
+  volumes: z.record(volumeSchema).optional(),
+});
+
+const sandboxAndPathSchema = z.object({
+  sandboxName: z.string().min(1),
+  path: z.string().min(1),
+});
+
+export const readFileSchema = sandboxAndPathSchema;
+
+export const writeFileSchema = sandboxAndPathSchema.extend({
+  content: z.string(),
+});
+
+export const listPathSchema = sandboxAndPathSchema.extend({
+  recursive: z.boolean().optional(),
+});
+
+export const findFilesSchema = sandboxAndPathSchema.extend({
+  pattern: z.string().min(1),
+});
+
+export const searchInFileSchema = sandboxAndPathSchema.extend({
+  query: z.string().min(1),
+});
+
+export const replaceInFileSchema = sandboxAndPathSchema.extend({
+  search: z.string(),
+  replace: z.string(),
+});
+
+export const uploadFileSchema = sandboxAndPathSchema.and(
+  z.union([
+    z.object({ contentBase64: z.string() }),
+    z.object({ content: z.string().transform((content) => Buffer.from(content).toString("base64")) }),
+  ])
+);
+
+export const downloadFileSchema = sandboxAndPathSchema;
+
+export const shellExecSchema = z.object({
+  sandboxName: z.string().min(1),
+  command: z.string().min(1),
+  exec_dir: z.string().optional(),
+  timeout: z.number().int().positive().optional(),
+});
+
+export type EnsureSandboxInput = z.infer<typeof ensureSandboxSchema>;
+export type ShellExecInput = z.infer<typeof shellExecSchema>;

package/src/server.ts

@@ -0,0 +1,43 @@
+import type { FastifyInstance } from "fastify";
+import { buildApp } from "./app";
+import { parseServerArgs, resolveServerConfig } from "./lib/server-cli";
+
+export async function startServer({
+  argv = process.argv.slice(2),
+  env = process.env,
+  app = buildApp(),
+}: {
+  argv?: string[];
+  env?: NodeJS.ProcessEnv;
+  app?: Pick<FastifyInstance, "listen" | "close">;
+} = {}): Promise<Pick<FastifyInstance, "listen" | "close">> {
+  const config = resolveServerConfig({ args: parseServerArgs(argv), env });
+
+  const shutdown = async (code: number): Promise<void> => {
+    try {
+      await app.close();
+      process.exit(code);
+    } catch (error) {
+      console.error("Failed to shutdown microsandbox-service cleanly", error);
+      process.exit(1);
+    }
+  };
+
+  process.once("SIGINT", () => {
+    void shutdown(0);
+  });
+
+  process.once("SIGTERM", () => {
+    void shutdown(0);
+  });
+
+  await app.listen({ port: config.port, host: config.host });
+  return app;
+}
+
+if (require.main === module) {
+  void startServer().catch((error) => {
+    console.error("Failed to start microsandbox-service", error);
+    process.exit(1);
+  });
+}

package/src/services/MicrosandboxRuntimeService.ts

@@ -0,0 +1,247 @@
+import { Mount, Sandbox } from "microsandbox";
+import type { EnsureSandboxInput, ShellExecInput } from "../schemas/sandbox";
+import { SandboxRegistry } from "./SandboxRegistry";
+
+type VolumeConfig = NonNullable<EnsureSandboxInput["volumes"]>[string];
+
+type RuntimeNative = {
+  fs(): {
+    readString(path: string): Promise<string>;
+    write(path: string, data: Buffer): Promise<void>;
+    list(
+      path: string,
+      options?: { recursive?: boolean }
+    ): Promise<Array<{ path: string; kind: string; size?: number; modified?: unknown }>>;
+    read(path: string): Promise<Buffer | Uint8Array | string>;
+  };
+  execWithConfig(config: {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    timeoutMs?: number;
+  }): Promise<{
+    stdout(): string;
+    stderr?(): string;
+    code?: number;
+  }>;
+  stop(): Promise<void>;
+  kill(): Promise<void>;
+};
+
+export class MicrosandboxRuntimeService {
+  constructor(private deps: { registry?: SandboxRegistry } = {}) {}
+
+  private get registry(): SandboxRegistry {
+    return this.deps.registry ?? (this.deps.registry = new SandboxRegistry());
+  }
+
+  private buildVolumes(volumes?: EnsureSandboxInput["volumes"]): Record<string, unknown> | undefined {
+    if (!volumes) {
+      return undefined;
+    }
+
+    return Object.fromEntries(
+      Object.entries(volumes).map(([mountPath, definition]) => [mountPath, this.buildVolume(definition)])
+    );
+  }
+
+  private buildVolume(definition: VolumeConfig): unknown {
+    if (definition.type === "bind") {
+      return Mount.bind(definition.source, { readonly: definition.readonly ?? false });
+    }
+
+    if (definition.type === "named") {
+      return Mount.named(definition.name, { readonly: definition.readonly ?? false });
+    }
+
+    return Mount.tmpfs({ sizeMib: definition.sizeMib });
+  }
+
+  private getNative(name: string): RuntimeNative {
+    return this.registry.get(name) as RuntimeNative;
+  }
+
+  private async getOrEnsureNative(name: string): Promise<RuntimeNative> {
+    try {
+      return this.getNative(name);
+    } catch {
+      return (await this.registry.ensure(name)) as RuntimeNative;
+    }
+  }
+
+  async ensureSandbox(name: string, input: EnsureSandboxInput): Promise<{
+    name: string;
+    status: string;
+  }> {
+    await this.registry.ensure(name, {
+      image: input.image ?? process.env.MICROSANDBOX_IMAGE ?? "python:3.11-slim",
+      cpus: input.cpus ?? Number(process.env.MICROSANDBOX_CPUS ?? "1"),
+      memoryMib: input.memoryMib ?? Number(process.env.MICROSANDBOX_MEMORY ?? "512"),
+      env: input.env,
+      volumes: this.buildVolumes(input.volumes),
+    });
+
+    return {
+      name,
+      status: "running",
+    };
+  }
+
+  async startSandbox(name: string): Promise<{ name: string; status: string }> {
+    await Sandbox.start(name);
+    this.registry.delete(name);
+    await this.registry.ensure(name);
+    return { name, status: "running" };
+  }
+
+  async stopSandbox(name: string): Promise<{ name: string; status: string }> {
+    const native = await this.getOrEnsureNative(name);
+    await native.stop();
+    this.registry.delete(name);
+    return { name, status: "stopped" };
+  }
+
+  async killSandbox(name: string): Promise<{ name: string; status: string }> {
+    const native = await this.getOrEnsureNative(name);
+    await native.kill();
+    this.registry.delete(name);
+    return { name, status: "unknown" };
+  }
+
+  async deleteSandbox(name: string): Promise<{ name: string; status: string }> {
+    try {
+      await this.getNative(name).kill();
+    } catch {
+      // Ignore missing cached native handle before remove.
+    }
+
+    await Sandbox.remove(name);
+    this.registry.delete(name);
+
+    return { name, status: "unknown" };
+  }
+
+  async getStatus(name: string): Promise<{ name: string; status: string }> {
+    try {
+      this.getNative(name);
+      return { name, status: "running" };
+    } catch {
+      return { name, status: "unknown" };
+    }
+  }
+
+  async readFile(sandboxName: string, path: string): Promise<{ path: string; content: string }> {
+    const content = await this.getNative(sandboxName).fs().readString(path);
+    return { path, content };
+  }
+
+  async writeFile(sandboxName: string, path: string, content: string): Promise<{ path: string }> {
+    await this.getNative(sandboxName).fs().write(path, Buffer.from(content));
+    return { path };
+  }
+
+  async listPath(
+    sandboxName: string,
+    path: string,
+    recursive?: boolean
+  ): Promise<{ entries: Array<{ path: string; type: string }> }> {
+    const entries = await this.getNative(sandboxName).fs().list(path, { recursive });
+    return {
+      entries: entries.map((entry) => ({
+        path: entry.path,
+        type: entry.kind,
+      })),
+    };
+  }
+
+  async findFiles(sandboxName: string, path: string, pattern: string): Promise<{ files: string[] }> {
+    const output = await this.getNative(sandboxName).execWithConfig({
+      cmd: "sh",
+      args: ["-c", `find "${path}" -name "${pattern}" -type f`],
+    });
+    return { files: output.stdout().split("\n").filter(Boolean) };
+  }
+
+  async searchInFile(
+    sandboxName: string,
+    path: string,
+    query: string
+  ): Promise<{ matches: Array<{ line: number; content: string }> }> {
+    let stdout: string;
+
+    try {
+      const output = await this.getNative(sandboxName).execWithConfig({
+        cmd: "grep",
+        args: ["-n", "-E", query, path],
+      });
+      stdout = output.stdout();
+    } catch (error) {
+      if (typeof error === "object" && error !== null && "code" in error && error.code === 1) {
+        return { matches: [] };
+      }
+
+      throw error;
+    }
+
+    return {
+      matches: stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+          const separator = line.indexOf(":");
+          return {
+            line: Number(line.slice(0, separator)),
+            content: line.slice(separator + 1),
+          };
+        }),
+    };
+  }
+
+  async replaceInFile(
+    sandboxName: string,
+    input: { path: string; search: string; replace: string }
+  ): Promise<{ replaced: number }> {
+    const fs = this.getNative(sandboxName).fs();
+    const original = await fs.readString(input.path);
+
+    if (!input.search) {
+      return { replaced: 0 };
+    }
+
+    const occurrences = original.split(input.search).length - 1;
+    if (occurrences === 0) {
+      return { replaced: 0 };
+    }
+
+    const updated = original.split(input.search).join(input.replace);
+    await fs.write(input.path, Buffer.from(updated));
+
+    return { replaced: occurrences };
+  }
+
+  async uploadFile(sandboxName: string, path: string, contentBase64: string): Promise<{ path: string }> {
+    await this.getNative(sandboxName).fs().write(path, Buffer.from(contentBase64, "base64"));
+    return { path };
+  }
+
+  async downloadFile(sandboxName: string, path: string): Promise<{ path: string; contentBase64: string }> {
+    const data = await this.getNative(sandboxName).fs().read(path);
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    return { path, contentBase64: buffer.toString("base64") };
+  }
+
+  async execCommand(input: ShellExecInput): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const output = await this.getNative(input.sandboxName).execWithConfig({
+      cmd: "sh",
+      args: ["-c", input.command],
+      cwd: input.exec_dir,
+      timeoutMs: input.timeout ? input.timeout * 1000 : undefined,
+    });
+
+    return {
+      stdout: output.stdout(),
+      stderr: output.stderr ? output.stderr() : "",
+      exitCode: output.code ?? 0,
+    };
+  }
+}

package/src/services/SandboxRegistry.ts

@@ -0,0 +1,69 @@
+import { Sandbox } from "microsandbox";
+
+const DEFAULT_IMAGE = process.env.MICROSANDBOX_IMAGE ?? "daytonaio/sandbox:0.6.0";
+
+export class SandboxRegistry {
+  private handles = new Map<string, unknown>();
+  private creating = new Map<string, Promise<unknown>>();
+
+  async ensure(name: string, createOptions?: Record<string, unknown>): Promise<unknown> {
+    const cached = this.handles.get(name);
+    if (cached) {
+      return cached;
+    }
+
+    const inflight = this.creating.get(name);
+    if (inflight) {
+      return inflight;
+    }
+
+    const creation = (async () => {
+      let native: unknown;
+      const createConfig = {
+        name,
+        image: DEFAULT_IMAGE,
+        ...(createOptions ?? {}),
+      };
+
+      try {
+        const handle = await Sandbox.get(name);
+
+        if (handle.status === "running") {
+          native = await handle.connect();
+        } else if (handle.status === "stopped") {
+          native = await Sandbox.start(name);
+        } else if (handle.status === "crashed" || handle.status === "draining") {
+          await Sandbox.remove(name);
+        }
+      } catch {
+        native = undefined;
+      }
+
+      if (!native) {
+        native = await Sandbox.createDetached(createConfig);
+      }
+
+      this.handles.set(name, native);
+      return native;
+    })();
+
+    this.creating.set(name, creation);
+    void creation.finally(() => this.creating.delete(name));
+
+    return creation;
+  }
+
+  get(name: string): unknown {
+    const handle = this.handles.get(name);
+
+    if (!handle) {
+      throw new Error(`Sandbox ${name} not found`);
+    }
+
+    return handle;
+  }
+
+  delete(name: string): void {
+    this.handles.delete(name);
+  }
+}

package/src/types/runtime-service.ts

@@ -0,0 +1,23 @@
+import type { EnsureSandboxInput } from "../schemas/sandbox";
+import type { ShellExecInput } from "../schemas/sandbox";
+
+export interface RuntimeService {
+  ensureSandbox(name: string, input: EnsureSandboxInput): Promise<unknown>;
+  startSandbox(name: string): Promise<unknown>;
+  stopSandbox(name: string): Promise<unknown>;
+  killSandbox(name: string): Promise<unknown>;
+  deleteSandbox(name: string): Promise<unknown>;
+  getStatus(name: string): Promise<unknown>;
+  readFile(sandboxName: string, path: string): Promise<unknown>;
+  writeFile(sandboxName: string, path: string, content: string): Promise<unknown>;
+  listPath(sandboxName: string, path: string, recursive?: boolean): Promise<unknown>;
+  findFiles(sandboxName: string, path: string, pattern: string): Promise<unknown>;
+  searchInFile(sandboxName: string, path: string, query: string): Promise<unknown>;
+  replaceInFile(
+    sandboxName: string,
+    input: { path: string; search: string; replace: string }
+  ): Promise<unknown>;
+  uploadFile(sandboxName: string, path: string, contentBase64: string): Promise<unknown>;
+  downloadFile(sandboxName: string, path: string): Promise<unknown>;
+  execCommand(input: ShellExecInput): Promise<unknown>;
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "preserve",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "moduleResolution": "Bundler",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "types": ["node", "jest"],
+    "sourceMap": true,
+    "isolatedModules": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}