openlattice-modal 0.0.3

package/src/modal-provider.ts

@@ -0,0 +1,435 @@
+import type {
+  ComputeProvider,
+  ComputeSpec,
+  ExecOpts,
+  ExecResult,
+  ExtensionMap,
+  FileEntry,
+  FileExtension,
+  HealthStatus,
+  NetworkExtension,
+  ProviderCapabilities,
+  ProviderNode,
+  ProviderNodeStatus,
+  SnapshotRef,
+} from "openlattice";
+import type { ModalProviderConfig } from "./config";
+
+// Modal SDK types — we import dynamically to avoid ESM/CJS issues
+// and to allow mocking in tests.
+interface ModalClient {
+  apps: { fromName(name: string, opts?: { createIfMissing?: boolean }): Promise<any> };
+  images: { fromRegistry(ref: string): any };
+  sandboxes: {
+    create(app: any, image: any, opts?: Record<string, unknown>): Promise<ModalSandbox>;
+    fromId(id: string): Promise<ModalSandbox>;
+  };
+}
+
+interface ModalSandbox {
+  sandboxId: string;
+  exec(args: string[], opts?: Record<string, unknown>): Promise<ModalProcess>;
+  snapshotFilesystem(): Promise<{ imageId: string }>;
+  terminate(): Promise<void>;
+}
+
+interface ModalProcess {
+  stdout: { readText(): Promise<string> };
+  stderr: { readText(): Promise<string> };
+  wait(): Promise<number>;
+}
+
+export class ModalProvider implements ComputeProvider {
+  readonly name = "modal";
+  readonly capabilities: ProviderCapabilities = {
+    restart: false,
+    pause: false,
+    snapshot: true,
+    gpu: true,
+    logs: false,
+    tailscale: true, // userspace networking mode, no special perms needed
+    coldStartMs: 2000,
+    maxConcurrent: 0,
+    architectures: ["x86_64"],
+    persistentStorage: false,
+    constraints: {
+      maxLifetimeSeconds: 86400,
+      gpuTypes: ["T4", "A10G", "A100", "H100", "H200", "L4", "L40S", "B200"],
+    },
+  };
+
+  private readonly config: ModalProviderConfig;
+  private client: ModalClient | null = null;
+  private app: any = null;
+  private readonly sandboxes = new Map<string, ModalSandbox>();
+
+  constructor(config: ModalProviderConfig = {}) {
+    this.config = config;
+  }
+
+  // ── Required methods ────────────────────────────────────────────
+
+  async provision(spec: ComputeSpec): Promise<ProviderNode> {
+    const client = await this.getClient();
+    const app = await this.getApp(client);
+
+    const image = this.resolveImage(client, spec.runtime.image);
+
+    const createOpts: Record<string, unknown> = {};
+    if (spec.gpu?.type) {
+      createOpts.gpu = spec.gpu.type;
+    } else if (spec.gpu?.count) {
+      createOpts.gpu = "T4"; // default GPU
+    }
+    if (spec.duration?.maxSeconds) {
+      createOpts.timeout = spec.duration.maxSeconds;
+    }
+    if (spec.runtime.workdir) {
+      createOpts.workdir = spec.runtime.workdir;
+    }
+    if (spec.runtime.env) {
+      createOpts.environmentVariables = spec.runtime.env;
+    }
+
+    const sandbox = await client.sandboxes.create(app, image, createOpts);
+    this.sandboxes.set(sandbox.sandboxId, sandbox);
+
+    // Run initial command if specified
+    if (spec.runtime.command && spec.runtime.command.length > 0) {
+      await sandbox.exec(spec.runtime.command, {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+    }
+
+    // Join Tailscale network if auth key provided
+    if (spec.network?.tailscaleAuthKey) {
+      await this.tailscaleUp(sandbox, spec.network.tailscaleAuthKey);
+    }
+
+    return {
+      externalId: sandbox.sandboxId,
+      endpoints: [],
+      metadata: { appName: this.config.appName ?? "openlattice" },
+    };
+  }
+
+  async exec(
+    externalId: string,
+    command: string[],
+    opts?: ExecOpts
+  ): Promise<ExecResult> {
+    const sandbox = await this.getSandbox(externalId);
+
+    // Build command with cwd and env support
+    let cmd = command;
+    if (opts?.cwd || opts?.env) {
+      const parts: string[] = [];
+      if (opts.cwd) {
+        parts.push(`cd ${opts.cwd}`);
+      }
+      if (opts.env) {
+        for (const [k, v] of Object.entries(opts.env)) {
+          parts.push(`export ${k}='${v.replace(/'/g, "'\\''")}'`);
+        }
+      }
+      parts.push(command.join(" "));
+      cmd = ["sh", "-c", parts.join(" && ")];
+    }
+
+    const execOpts: Record<string, unknown> = {
+      stdout: "pipe",
+      stderr: "pipe",
+    };
+    if (opts?.timeoutMs) {
+      execOpts.timeout = Math.floor(opts.timeoutMs / 1000);
+    }
+
+    const proc = await sandbox.exec(cmd, execOpts);
+
+    const [stdout, stderr] = await Promise.all([
+      proc.stdout.readText(),
+      proc.stderr.readText(),
+    ]);
+
+    const exitCode = await proc.wait();
+
+    opts?.onStdout?.(stdout);
+    opts?.onStderr?.(stderr);
+
+    return { exitCode, stdout, stderr };
+  }
+
+  async destroy(externalId: string): Promise<void> {
+    const sandbox = this.sandboxes.get(externalId);
+    if (!sandbox) {
+      // Try to reconnect and terminate
+      try {
+        const client = await this.getClient();
+        const sb = await client.sandboxes.fromId(externalId);
+        await sb.terminate();
+      } catch {
+        // Already terminated or not found — idempotent
+      }
+      return;
+    }
+
+    try {
+      await sandbox.terminate();
+    } catch {
+      // Already terminated — idempotent
+    }
+    this.sandboxes.delete(externalId);
+  }
+
+  async inspect(externalId: string): Promise<ProviderNodeStatus> {
+    try {
+      const client = await this.getClient();
+      const sandbox = await client.sandboxes.fromId(externalId);
+
+      // If we can reconnect, it's running
+      this.sandboxes.set(externalId, sandbox);
+      return { status: "running" };
+    } catch {
+      this.sandboxes.delete(externalId);
+      return { status: "terminated" };
+    }
+  }
+
+  // ── Optional: snapshot / restore ──────────────────────────────
+
+  async snapshot(externalId: string): Promise<SnapshotRef> {
+    const sandbox = await this.getSandbox(externalId);
+    const image = await sandbox.snapshotFilesystem();
+
+    return {
+      provider: "modal",
+      externalId: image.imageId,
+      createdAt: new Date(),
+      type: "filesystem",
+      metadata: { originalSandboxId: externalId },
+    };
+  }
+
+  async restore(
+    snapshotRef: SnapshotRef,
+    spec?: Partial<ComputeSpec>
+  ): Promise<ProviderNode> {
+    const client = await this.getClient();
+    const app = await this.getApp(client);
+
+    // The snapshotRef.externalId is the Modal image ID
+    const image = { imageId: snapshotRef.externalId };
+
+    const createOpts: Record<string, unknown> = {};
+    if (spec?.gpu?.type) {
+      createOpts.gpu = spec.gpu.type;
+    }
+    if (spec?.duration?.maxSeconds) {
+      createOpts.timeout = spec.duration.maxSeconds;
+    }
+
+    const sandbox = await client.sandboxes.create(app, image, createOpts);
+    this.sandboxes.set(sandbox.sandboxId, sandbox);
+
+    return {
+      externalId: sandbox.sandboxId,
+      endpoints: [],
+      metadata: {
+        appName: this.config.appName ?? "openlattice",
+        restoredFrom: snapshotRef.externalId,
+      },
+    };
+  }
+
+  // ── Optional: healthCheck ─────────────────────────────────────
+
+  async healthCheck(): Promise<HealthStatus> {
+    const start = Date.now();
+    try {
+      const client = await this.getClient();
+      await client.apps.fromName(this.config.appName ?? "openlattice", {
+        createIfMissing: true,
+      });
+      return {
+        healthy: true,
+        latencyMs: Date.now() - start,
+      };
+    } catch (err: unknown) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - start,
+        message: `[modal] service unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  // ── Optional: extensions ──────────────────────────────────────
+
+  getExtension<K extends keyof ExtensionMap>(
+    externalId: string,
+    extension: K
+  ): ExtensionMap[K] | undefined {
+    if (extension === "files") {
+      return this.createFileExtension(externalId) as ExtensionMap[K];
+    }
+    if (extension === "network") {
+      return this.createNetworkExtension(externalId) as ExtensionMap[K];
+    }
+    return undefined;
+  }
+
+  // ── Private helpers ───────────────────────────────────────────
+
+  private async tailscaleUp(
+    sandbox: ModalSandbox,
+    authKey: string
+  ): Promise<void> {
+    const proc = await sandbox.exec(
+      [
+        "sh",
+        "-c",
+        `pgrep tailscaled >/dev/null 2>&1 || tailscaled --state=/var/lib/tailscale/tailscaled.state & sleep 1 && tailscale up --authkey=${authKey}`,
+      ],
+      { stdout: "pipe", stderr: "pipe" }
+    );
+    const stderr = await proc.stderr.readText();
+    const exitCode = await proc.wait();
+    if (exitCode !== 0) {
+      throw new Error(`[modal] tailscale up failed: ${stderr.trim()}`);
+    }
+  }
+
+  private async getClient(): Promise<ModalClient> {
+    if (this.client) return this.client;
+
+    // Set Modal credential env vars if provided in config
+    if (this.config.tokenId) {
+      process.env.MODAL_TOKEN_ID = this.config.tokenId;
+    }
+    if (this.config.tokenSecret) {
+      process.env.MODAL_TOKEN_SECRET = this.config.tokenSecret;
+    }
+
+    // Dynamic import to handle ESM/CJS
+    const modal = await import("modal");
+    const ModalClientClass = (modal as any).ModalClient ?? (modal as any).default?.ModalClient;
+
+    if (!ModalClientClass) {
+      throw new Error("[modal] could not import ModalClient from modal package");
+    }
+
+    this.client = new ModalClientClass() as ModalClient;
+    return this.client;
+  }
+
+  private async getApp(client: ModalClient): Promise<any> {
+    if (this.app) return this.app;
+    this.app = await client.apps.fromName(
+      this.config.appName ?? "openlattice",
+      { createIfMissing: true }
+    );
+    return this.app;
+  }
+
+  private resolveImage(client: ModalClient, image: string): any {
+    // If it looks like an OCI reference (contains / or :), use fromRegistry
+    if (image.includes("/") || image.includes(":")) {
+      return client.images.fromRegistry(image);
+    }
+    // Otherwise assume it's a Modal image ID
+    return { imageId: image };
+  }
+
+  private async getSandbox(externalId: string): Promise<ModalSandbox> {
+    const cached = this.sandboxes.get(externalId);
+    if (cached) return cached;
+
+    const client = await this.getClient();
+    const sandbox = await client.sandboxes.fromId(externalId);
+    this.sandboxes.set(externalId, sandbox);
+    return sandbox;
+  }
+
+  private createFileExtension(externalId: string): FileExtension {
+    const provider = this;
+    return {
+      async read(path: string): Promise<string | Buffer> {
+        const sb = await provider.getSandbox(externalId);
+        const proc = await sb.exec(["cat", path], { stdout: "pipe", stderr: "pipe" });
+        const content = await proc.stdout.readText();
+        await proc.wait();
+        return content;
+      },
+      async write(filePath: string, content: string | Buffer): Promise<void> {
+        const sb = await provider.getSandbox(externalId);
+        const safePath = filePath.replace(/'/g, "'\\''");
+
+        if (Buffer.isBuffer(content)) {
+          // Binary content: base64 encode, decode on remote
+          const b64 = content.toString("base64");
+          const proc = await sb.exec(
+            ["sh", "-c", `printf '%s' '${b64}' | base64 -d > '${safePath}'`],
+            { stdout: "pipe", stderr: "pipe" }
+          );
+          await proc.wait();
+        } else {
+          // Text content: write via printf with proper escaping
+          const escaped = content.replace(/\\/g, "\\\\").replace(/'/g, "'\\''");
+          const proc = await sb.exec(
+            ["sh", "-c", `printf '%s' '${escaped}' > '${safePath}'`],
+            { stdout: "pipe", stderr: "pipe" }
+          );
+          await proc.wait();
+        }
+      },
+      async list(dirPath: string): Promise<FileEntry[]> {
+        const sb = await provider.getSandbox(externalId);
+        const proc = await sb.exec(
+          ["ls", "-1apL", dirPath],
+          { stdout: "pipe", stderr: "pipe" }
+        );
+        const output = await proc.stdout.readText();
+        await proc.wait();
+        return output
+          .split("\n")
+          .filter((l) => l.length > 0 && l !== "./" && l !== "../")
+          .map((name) => {
+            const isDir = name.endsWith("/");
+            const cleanName = isDir ? name.slice(0, -1) : name;
+            return {
+              name: cleanName,
+              path: `${dirPath}/${cleanName}`.replace(/\/\//g, "/"),
+              type: isDir ? ("directory" as const) : ("file" as const),
+            };
+          });
+      },
+      async remove(path: string): Promise<void> {
+        const sb = await provider.getSandbox(externalId);
+        const proc = await sb.exec(["rm", "-rf", path], { stdout: "pipe", stderr: "pipe" });
+        await proc.wait();
+      },
+      async mkdir(path: string): Promise<void> {
+        const sb = await provider.getSandbox(externalId);
+        const proc = await sb.exec(["mkdir", "-p", path], { stdout: "pipe", stderr: "pipe" });
+        await proc.wait();
+      },
+    };
+  }
+
+  private createNetworkExtension(externalId: string): NetworkExtension {
+    const provider = this;
+    return {
+      async getUrl(port: number): Promise<string> {
+        const sb = await provider.getSandbox(externalId);
+        // Modal provides tunnel URLs via sandbox
+        const tunnelUrl = (sb as any).tunnelUrl ?? (sb as any).getTunnelUrl;
+        if (typeof tunnelUrl === "function") {
+          return tunnelUrl(port);
+        }
+        // Fallback: construct from sandbox ID
+        return `https://${externalId}--${port}.modal.run`;
+      },
+    };
+  }
+}

package/tests/conformance.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { runProviderConformanceTests } from "openlattice/testing";
+import { ModalProvider } from "../src/modal-provider";
+
+const HAS_MODAL =
+  !!process.env.MODAL_TOKEN_ID && !!process.env.MODAL_TOKEN_SECRET;
+
+describe.skipIf(!HAS_MODAL)("ModalProvider conformance", () => {
+  runProviderConformanceTests(
+    {
+      createProvider: () =>
+        new ModalProvider({
+          tokenId: process.env.MODAL_TOKEN_ID,
+          tokenSecret: process.env.MODAL_TOKEN_SECRET,
+          appName: process.env.MODAL_APP_NAME ?? "openlattice-test",
+        }),
+      createSpec: () => ({
+        runtime: { image: "python:3.12-slim" },
+      }),
+      timeoutMs: 120_000,
+    },
+    { describe, it, expect, beforeEach, afterEach }
+  );
+});

package/tests/integration.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeAll, afterEach } from "vitest";
+import { ModalProvider } from "../src/modal-provider";
+
+const HAS_MODAL =
+  !!process.env.MODAL_TOKEN_ID && !!process.env.MODAL_TOKEN_SECRET;
+
+describe.skipIf(!HAS_MODAL)("ModalProvider integration", () => {
+  let provider: ModalProvider;
+  const toCleanup: string[] = [];
+
+  beforeAll(() => {
+    provider = new ModalProvider({
+      tokenId: process.env.MODAL_TOKEN_ID,
+      tokenSecret: process.env.MODAL_TOKEN_SECRET,
+      appName: process.env.MODAL_APP_NAME ?? "openlattice-test",
+    });
+  });
+
+  afterEach(async () => {
+    for (const id of toCleanup) {
+      try {
+        await provider.destroy(id);
+      } catch {
+        /* best-effort */
+      }
+    }
+    toCleanup.length = 0;
+  });
+
+  it(
+    "provisions, execs, and destroys",
+    async () => {
+      const node = await provider.provision({
+        runtime: { image: "python:3.12-slim" },
+      });
+      toCleanup.push(node.externalId);
+
+      expect(node.externalId).toBeTruthy();
+
+      const result = await provider.exec(node.externalId, [
+        "echo",
+        "hello from modal",
+      ]);
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("hello from modal");
+
+      await provider.destroy(node.externalId);
+      toCleanup.pop();
+
+      const status = await provider.inspect(node.externalId);
+      expect(status.status).toBe("terminated");
+    },
+    120_000
+  );
+
+  it(
+    "exec captures stderr and exit codes",
+    async () => {
+      const node = await provider.provision({
+        runtime: { image: "python:3.12-slim" },
+      });
+      toCleanup.push(node.externalId);
+
+      const result = await provider.exec(node.externalId, [
+        "sh",
+        "-c",
+        "echo err >&2; exit 42",
+      ]);
+      expect(result.exitCode).toBe(42);
+      expect(result.stderr).toContain("err");
+    },
+    120_000
+  );
+
+  it(
+    "snapshot and restore",
+    async () => {
+      const node = await provider.provision({
+        runtime: { image: "python:3.12-slim" },
+      });
+      toCleanup.push(node.externalId);
+
+      // Write a file
+      await provider.exec(node.externalId, [
+        "sh",
+        "-c",
+        "echo snapshot-test > /tmp/test.txt",
+      ]);
+
+      // Snapshot
+      const snap = await provider.snapshot(node.externalId);
+      expect(snap.type).toBe("filesystem");
+
+      // Restore
+      const restored = await provider.restore(snap);
+      toCleanup.push(restored.externalId);
+
+      // Verify file persisted
+      const result = await provider.exec(restored.externalId, [
+        "cat",
+        "/tmp/test.txt",
+      ]);
+      expect(result.stdout).toContain("snapshot-test");
+    },
+    120_000
+  );
+
+  it(
+    "healthCheck returns healthy",
+    async () => {
+      const health = await provider.healthCheck();
+      expect(health.healthy).toBe(true);
+    },
+    30_000
+  );
+
+  it(
+    "destroy is idempotent",
+    async () => {
+      const node = await provider.provision({
+        runtime: { image: "python:3.12-slim" },
+      });
+
+      await provider.destroy(node.externalId);
+      await expect(
+        provider.destroy(node.externalId)
+      ).resolves.toBeUndefined();
+    },
+    120_000
+  );
+});