@axiom-lattice/microsandbox-service 0.0.1

package/src/__tests__/app.test.ts

@@ -0,0 +1,224 @@
+import { buildApp } from "../app";
+import type { RuntimeService } from "../types/runtime-service";
+
+function createRuntimeService(overrides: Partial<RuntimeService> = {}): RuntimeService {
+  return {
+    ensureSandbox: jest.fn(),
+    startSandbox: jest.fn(),
+    stopSandbox: jest.fn(),
+    killSandbox: jest.fn(),
+    deleteSandbox: jest.fn(),
+    getStatus: jest.fn(),
+    readFile: jest.fn(),
+    writeFile: jest.fn(),
+    listPath: jest.fn(),
+    findFiles: jest.fn(),
+    searchInFile: jest.fn(),
+    replaceInFile: jest.fn(),
+    uploadFile: jest.fn(),
+    downloadFile: jest.fn(),
+    execCommand: jest.fn(),
+    ...overrides,
+  };
+}
+
+describe("microsandbox-service routes", () => {
+  it("returns health status", async () => {
+    const app = buildApp({
+      runtimeService: createRuntimeService(),
+    });
+
+    const response = await app.inject({ method: "GET", url: "/health" });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toEqual({ success: true, data: { status: "ok" } });
+
+    await app.close();
+  });
+
+  it("passes create payload including volumes to the runtime service", async () => {
+    const ensureSandbox = jest.fn().mockResolvedValue({
+      name: "tenant-project",
+      status: "running",
+    });
+
+    const app = buildApp({
+      runtimeService: createRuntimeService({ ensureSandbox }),
+    });
+
+    const response = await app.inject({
+      method: "PUT",
+      url: "/api/sandboxes/tenant-project",
+      payload: {
+        image: "python:3.11-slim",
+        cpus: 1,
+        memoryMib: 512,
+        env: { PYTHONDONTWRITEBYTECODE: "1" },
+        volumes: {
+          "/home/microsandbox/project": {
+            type: "named",
+            name: "tenant-project-vol",
+          },
+        },
+      },
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(ensureSandbox).toHaveBeenCalledWith("tenant-project", {
+      image: "python:3.11-slim",
+      cpus: 1,
+      memoryMib: 512,
+      env: { PYTHONDONTWRITEBYTECODE: "1" },
+      volumes: {
+        "/home/microsandbox/project": {
+          type: "named",
+          name: "tenant-project-vol",
+        },
+      },
+    });
+
+    await app.close();
+  });
+
+  it("routes lifecycle, file, and shell requests to the runtime service", async () => {
+    const binary = Buffer.from([0, 255, 1]);
+    const runtimeService = createRuntimeService({
+      startSandbox: jest.fn().mockResolvedValue({ name: "tenant-project", status: "running" }),
+      stopSandbox: jest.fn().mockResolvedValue({ name: "tenant-project", status: "stopped" }),
+      killSandbox: jest.fn().mockResolvedValue({ name: "tenant-project", status: "unknown" }),
+      deleteSandbox: jest.fn().mockResolvedValue({ name: "tenant-project", status: "unknown" }),
+      getStatus: jest.fn().mockResolvedValue({ name: "tenant-project", status: "running" }),
+      readFile: jest.fn().mockResolvedValue({ path: "/tmp/test.txt", content: "hello" }),
+      writeFile: jest.fn().mockResolvedValue({ path: "/tmp/test.txt" }),
+      listPath: jest.fn().mockResolvedValue({ entries: [{ name: "test.txt", type: "file" }] }),
+      findFiles: jest.fn().mockResolvedValue({ files: ["/tmp/test.txt"] }),
+      searchInFile: jest.fn().mockResolvedValue({ matches: [{ line: 1, content: "hello" }] }),
+      replaceInFile: jest.fn().mockResolvedValue({ replaced: 1 }),
+      uploadFile: jest.fn().mockResolvedValue({ path: "/tmp/upload.txt" }),
+      downloadFile: jest.fn().mockResolvedValue({ path: "/tmp/download.txt", contentBase64: binary.toString("base64") }),
+      execCommand: jest.fn().mockResolvedValue({ stdout: "ok", stderr: "", exitCode: 0 }),
+    });
+
+    const app = buildApp({ runtimeService });
+
+    const startResponse = await app.inject({ method: "POST", url: "/api/sandboxes/tenant-project/start" });
+    const stopResponse = await app.inject({ method: "POST", url: "/api/sandboxes/tenant-project/stop" });
+    const killResponse = await app.inject({ method: "POST", url: "/api/sandboxes/tenant-project/kill" });
+    const deleteResponse = await app.inject({ method: "DELETE", url: "/api/sandboxes/tenant-project" });
+    const statusResponse = await app.inject({ method: "GET", url: "/api/sandboxes/tenant-project/status" });
+    const readResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/read",
+      payload: { sandboxName: "tenant-project", path: "/tmp/test.txt" },
+    });
+    const writeResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/write",
+      payload: { sandboxName: "tenant-project", path: "/tmp/test.txt", content: "hello" },
+    });
+    const listResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/list",
+      payload: { sandboxName: "tenant-project", path: "/tmp", recursive: true },
+    });
+    const findResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/find",
+      payload: { sandboxName: "tenant-project", path: "/tmp", pattern: "*.txt" },
+    });
+    const searchResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/search",
+      payload: { sandboxName: "tenant-project", path: "/tmp/test.txt", query: "hello" },
+    });
+    const replaceResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/replace",
+      payload: {
+        sandboxName: "tenant-project",
+        path: "/tmp/test.txt",
+        search: "hello",
+        replace: "world",
+      },
+    });
+    const uploadResponse = await app.inject({
+      method: "POST",
+      url: "/api/files/upload",
+      payload: {
+        sandboxName: "tenant-project",
+        path: "/tmp/upload.txt",
+        contentBase64: binary.toString("base64"),
+      },
+    });
+    const downloadResponse = await app.inject({
+      method: "GET",
+      url: "/api/files/download?sandboxName=tenant-project&path=%2Ftmp%2Fdownload.txt",
+    });
+    const execResponse = await app.inject({
+      method: "POST",
+      url: "/api/shell/exec",
+      payload: { sandboxName: "tenant-project", command: "pwd", exec_dir: "/tmp", timeout: 10 },
+    });
+
+    expect(startResponse.statusCode).toBe(200);
+    expect(stopResponse.statusCode).toBe(200);
+    expect(killResponse.statusCode).toBe(200);
+    expect(deleteResponse.statusCode).toBe(200);
+    expect(statusResponse.statusCode).toBe(200);
+    expect(readResponse.statusCode).toBe(200);
+    expect(writeResponse.statusCode).toBe(200);
+    expect(listResponse.statusCode).toBe(200);
+    expect(findResponse.statusCode).toBe(200);
+    expect(searchResponse.statusCode).toBe(200);
+    expect(replaceResponse.statusCode).toBe(200);
+    expect(uploadResponse.statusCode).toBe(200);
+    expect(downloadResponse.statusCode).toBe(200);
+    expect(execResponse.statusCode).toBe(200);
+
+    expect(runtimeService.startSandbox).toHaveBeenCalledWith("tenant-project");
+    expect(runtimeService.stopSandbox).toHaveBeenCalledWith("tenant-project");
+    expect(runtimeService.killSandbox).toHaveBeenCalledWith("tenant-project");
+    expect(runtimeService.deleteSandbox).toHaveBeenCalledWith("tenant-project");
+    expect(runtimeService.getStatus).toHaveBeenCalledWith("tenant-project");
+    expect(runtimeService.readFile).toHaveBeenCalledWith("tenant-project", "/tmp/test.txt");
+    expect(runtimeService.writeFile).toHaveBeenCalledWith("tenant-project", "/tmp/test.txt", "hello");
+    expect(runtimeService.listPath).toHaveBeenCalledWith("tenant-project", "/tmp", true);
+    expect(runtimeService.findFiles).toHaveBeenCalledWith("tenant-project", "/tmp", "*.txt");
+    expect(runtimeService.searchInFile).toHaveBeenCalledWith("tenant-project", "/tmp/test.txt", "hello");
+    expect(runtimeService.replaceInFile).toHaveBeenCalledWith("tenant-project", {
+      path: "/tmp/test.txt",
+      search: "hello",
+      replace: "world",
+    });
+    expect(runtimeService.uploadFile).toHaveBeenCalledWith(
+      "tenant-project",
+      "/tmp/upload.txt",
+      binary.toString("base64")
+    );
+    expect(runtimeService.downloadFile).toHaveBeenCalledWith("tenant-project", "/tmp/download.txt");
+    expect(runtimeService.execCommand).toHaveBeenCalledWith({
+      sandboxName: "tenant-project",
+      command: "pwd",
+      exec_dir: "/tmp",
+      timeout: 10,
+    });
+    expect(startResponse.json()).toEqual({
+      success: true,
+      data: { name: "tenant-project", status: "running" },
+    });
+    expect(readResponse.json()).toEqual({
+      success: true,
+      data: { path: "/tmp/test.txt", content: "hello" },
+    });
+    expect(downloadResponse.json()).toEqual({
+      success: true,
+      data: { path: "/tmp/download.txt", contentBase64: binary.toString("base64") },
+    });
+    expect(execResponse.json()).toEqual({
+      success: true,
+      data: { stdout: "ok", stderr: "", exitCode: 0 },
+    });
+
+    await app.close();
+  });
+});

package/src/__tests__/index.test.ts

@@ -0,0 +1,33 @@
+const buildApp = jest.fn();
+
+import packageJson from "../../package.json";
+
+jest.mock("../app", () => ({
+  buildApp,
+}));
+
+describe("package entrypoint", () => {
+  beforeEach(() => {
+    buildApp.mockReset();
+    jest.resetModules();
+  });
+
+  it("does not start the server when imported", async () => {
+    const entry = await import("../index");
+
+    expect(buildApp).not.toHaveBeenCalled();
+    expect(entry.buildApp).toBe(buildApp);
+  });
+});
+
+describe("package metadata", () => {
+  it("exposes the production CLI bin", () => {
+    expect(packageJson.bin).toEqual({
+      "lattice-microsandbox-service": "./dist/server.js",
+    });
+  });
+
+  it("uses watch-and-run dev mode", () => {
+    expect(packageJson.scripts.dev).toContain('--onSuccess "node dist/server.js"');
+  });
+});

package/src/__tests__/server-cli.test.ts

@@ -0,0 +1,26 @@
+import { parseServerArgs, resolveServerConfig } from "../lib/server-cli";
+
+describe("server CLI parsing", () => {
+  it("parses --port and --host args", () => {
+    expect(parseServerArgs(["--port", "4012", "--host", "127.0.0.1"])).toEqual({
+      port: 4012,
+      host: "127.0.0.1",
+    });
+  });
+
+  it("prefers CLI args over env and defaults", () => {
+    expect(
+      resolveServerConfig({
+        args: { port: 4012 },
+        env: { PORT: "4002", HOST: "0.0.0.0" },
+      })
+    ).toEqual({
+      port: 4012,
+      host: "0.0.0.0",
+    });
+  });
+
+  it("rejects invalid port values", () => {
+    expect(() => parseServerArgs(["--port", "abc"])).toThrow("Invalid value for --port: abc");
+  });
+});

package/src/__tests__/server.test.ts

@@ -0,0 +1,25 @@
+const listen = jest.fn();
+const close = jest.fn();
+
+jest.mock("../app", () => ({
+  buildApp: jest.fn(() => ({
+    listen,
+    close,
+  })),
+}));
+
+describe("server bootstrap", () => {
+  beforeEach(() => {
+    listen.mockReset().mockResolvedValue(undefined);
+    close.mockReset().mockResolvedValue(undefined);
+    jest.resetModules();
+  });
+
+  it("starts the app with resolved host and port", async () => {
+    const { startServer } = await import("../server");
+
+    await startServer({ argv: ["--port", "4012", "--host", "127.0.0.1"], env: {} as NodeJS.ProcessEnv });
+
+    expect(listen).toHaveBeenCalledWith({ port: 4012, host: "127.0.0.1" });
+  });
+});

package/src/app.ts

@@ -0,0 +1,31 @@
+import cors from "@fastify/cors";
+import multipart from "@fastify/multipart";
+import sensible from "@fastify/sensible";
+import fastify, { type FastifyInstance } from "fastify";
+import { toErrorResponse } from "./lib/errors";
+import { registerHealthRoutes } from "./routes/health";
+import { registerSandboxRoutes } from "./routes/sandbox";
+import { MicrosandboxRuntimeService } from "./services/MicrosandboxRuntimeService";
+import type { RuntimeService } from "./types/runtime-service";
+
+export function buildApp({
+  runtimeService = new MicrosandboxRuntimeService(),
+}: {
+  runtimeService?: RuntimeService;
+} = {}): FastifyInstance {
+  const app = fastify({ logger: false });
+
+  app.register(cors, { origin: true });
+  app.register(sensible);
+  app.register(multipart);
+
+  registerHealthRoutes(app);
+  registerSandboxRoutes(app, runtimeService);
+
+  app.setErrorHandler((error, _request, reply) => {
+    const { statusCode, body } = toErrorResponse(error);
+    reply.status(statusCode).send(body);
+  });
+
+  return app;
+}

package/src/controllers/sandbox.ts

@@ -0,0 +1,138 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import {
+  downloadFileSchema,
+  ensureSandboxSchema,
+  findFilesSchema,
+  listPathSchema,
+  readFileSchema,
+  replaceInFileSchema,
+  searchInFileSchema,
+  shellExecSchema,
+  uploadFileSchema,
+  writeFileSchema,
+} from "../schemas/sandbox";
+import { ok } from "../lib/http";
+import type { RuntimeService } from "../types/runtime-service";
+
+export function createSandboxController(runtimeService: RuntimeService): {
+  ensureSandbox(
+    request: FastifyRequest<{ Params: { name: string }; Body: unknown }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  startSandbox(
+    request: FastifyRequest<{ Params: { name: string } }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  stopSandbox(
+    request: FastifyRequest<{ Params: { name: string } }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  killSandbox(
+    request: FastifyRequest<{ Params: { name: string } }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  deleteSandbox(
+    request: FastifyRequest<{ Params: { name: string } }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  getStatus(
+    request: FastifyRequest<{ Params: { name: string } }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  readFile(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  writeFile(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  listPath(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  findFiles(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  searchInFile(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  replaceInFile(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  uploadFile(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+  downloadFile(
+    request: FastifyRequest<{ Querystring: unknown }>,
+    reply: FastifyReply
+  ): Promise<FastifyReply>;
+  execCommand(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply): Promise<FastifyReply>;
+} {
+  return {
+    ensureSandbox: async (
+      request: FastifyRequest<{ Params: { name: string }; Body: unknown }>,
+      reply: FastifyReply
+    ) => {
+      const body = ensureSandboxSchema.parse(request.body ?? {});
+      const result = await runtimeService.ensureSandbox(request.params.name, body);
+      return reply.send(ok(result));
+    },
+
+    startSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.startSandbox(request.params.name)));
+    },
+
+    stopSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.stopSandbox(request.params.name)));
+    },
+
+    killSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.killSandbox(request.params.name)));
+    },
+
+    deleteSandbox: async (request, reply) => {
+      return reply.send(ok(await runtimeService.deleteSandbox(request.params.name)));
+    },
+
+    getStatus: async (request, reply) => {
+      return reply.send(ok(await runtimeService.getStatus(request.params.name)));
+    },
+
+    readFile: async (request, reply) => {
+      const body = readFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.readFile(body.sandboxName, body.path)));
+    },
+
+    writeFile: async (request, reply) => {
+      const body = writeFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.writeFile(body.sandboxName, body.path, body.content)));
+    },
+
+    listPath: async (request, reply) => {
+      const body = listPathSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.listPath(body.sandboxName, body.path, body.recursive)));
+    },
+
+    findFiles: async (request, reply) => {
+      const body = findFilesSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.findFiles(body.sandboxName, body.path, body.pattern)));
+    },
+
+    searchInFile: async (request, reply) => {
+      const body = searchInFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.searchInFile(body.sandboxName, body.path, body.query)));
+    },
+
+    replaceInFile: async (request, reply) => {
+      const body = replaceInFileSchema.parse(request.body ?? {});
+      return reply.send(
+        ok(
+          await runtimeService.replaceInFile(body.sandboxName, {
+            path: body.path,
+            search: body.search,
+            replace: body.replace,
+          })
+        )
+      );
+    },
+
+    uploadFile: async (request, reply) => {
+      const body = uploadFileSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.uploadFile(body.sandboxName, body.path, body.contentBase64)));
+    },
+
+    downloadFile: async (request, reply) => {
+      const query = downloadFileSchema.parse(request.query ?? {});
+      return reply.send(ok(await runtimeService.downloadFile(query.sandboxName, query.path)));
+    },
+
+    execCommand: async (request, reply) => {
+      const body = shellExecSchema.parse(request.body ?? {});
+      return reply.send(ok(await runtimeService.execCommand(body)));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { buildApp } from "./app";
+export { MicrosandboxRuntimeService } from "./services/MicrosandboxRuntimeService";
+export { SandboxRegistry } from "./services/SandboxRegistry";

package/src/lib/errors.ts

@@ -0,0 +1,44 @@
+export class HttpError extends Error {
+  constructor(
+    public statusCode: number,
+    public code: string,
+    message: string
+  ) {
+    super(message);
+  }
+}
+
+export function toErrorResponse(error: unknown): {
+  statusCode: number;
+  body: {
+    success: false;
+    error: {
+      code: string;
+      message: string;
+    };
+  };
+} {
+  if (error instanceof HttpError) {
+    return {
+      statusCode: error.statusCode,
+      body: {
+        success: false,
+        error: {
+          code: error.code,
+          message: error.message,
+        },
+      },
+    };
+  }
+
+  return {
+    statusCode: 500,
+    body: {
+      success: false,
+      error: {
+        code: "INTERNAL_ERROR",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    },
+  };
+}

package/src/lib/http.ts

@@ -0,0 +1,11 @@
+export type SuccessResponse<T> = {
+  success: true;
+  data: T;
+};
+
+export function ok<T>(data: T): SuccessResponse<T> {
+  return {
+    success: true,
+    data,
+  };
+}

package/src/lib/server-cli.ts

@@ -0,0 +1,59 @@
+export interface ParsedServerArgs {
+  host?: string;
+  port?: number;
+}
+
+export interface ResolvedServerConfig {
+  host: string;
+  port: number;
+}
+
+function parsePort(raw: string, source: string): number {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`Invalid value for ${source}: ${raw}`);
+  }
+  return value;
+}
+
+export function parseServerArgs(argv: string[]): ParsedServerArgs {
+  const parsed: ParsedServerArgs = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--port") {
+      const raw = argv[index + 1];
+      if (!raw) {
+        throw new Error("Missing value for --port");
+      }
+      parsed.port = parsePort(raw, "--port");
+      index += 1;
+      continue;
+    }
+
+    if (token === "--host") {
+      const raw = argv[index + 1];
+      if (!raw) {
+        throw new Error("Missing value for --host");
+      }
+      parsed.host = raw;
+      index += 1;
+    }
+  }
+
+  return parsed;
+}
+
+export function resolveServerConfig({
+  args,
+  env,
+}: {
+  args: ParsedServerArgs;
+  env: NodeJS.ProcessEnv;
+}): ResolvedServerConfig {
+  return {
+    host: args.host ?? env.HOST ?? "0.0.0.0",
+    port: args.port ?? (env.PORT ? parsePort(env.PORT, "PORT") : 4002),
+  };
+}

package/src/routes/health.ts

@@ -0,0 +1,6 @@
+import type { FastifyInstance } from "fastify";
+import { ok } from "../lib/http";
+
+export function registerHealthRoutes(app: FastifyInstance): void {
+  app.get("/health", async () => ok({ status: "ok" }));
+}

package/src/routes/sandbox.ts

@@ -0,0 +1,28 @@
+import type { FastifyInstance } from "fastify";
+import { createSandboxController } from "../controllers/sandbox";
+import type { RuntimeService } from "../types/runtime-service";
+
+export function registerSandboxRoutes(
+  app: FastifyInstance,
+  runtimeService: RuntimeService
+): void {
+  const controller = createSandboxController(runtimeService);
+
+  app.put("/api/sandboxes/:name", controller.ensureSandbox);
+  app.post("/api/sandboxes/:name/start", controller.startSandbox);
+  app.post("/api/sandboxes/:name/stop", controller.stopSandbox);
+  app.post("/api/sandboxes/:name/kill", controller.killSandbox);
+  app.delete("/api/sandboxes/:name", controller.deleteSandbox);
+  app.get("/api/sandboxes/:name/status", controller.getStatus);
+
+  app.post("/api/files/read", controller.readFile);
+  app.post("/api/files/write", controller.writeFile);
+  app.post("/api/files/list", controller.listPath);
+  app.post("/api/files/find", controller.findFiles);
+  app.post("/api/files/search", controller.searchInFile);
+  app.post("/api/files/replace", controller.replaceInFile);
+  app.post("/api/files/upload", controller.uploadFile);
+  app.get("/api/files/download", controller.downloadFile);
+
+  app.post("/api/shell/exec", controller.execCommand);
+}