openlattice-modal 0.0.3

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface ModalProviderConfig {
+    /** Modal token ID. Default: reads MODAL_TOKEN_ID env var. */
+    tokenId?: string;
+    /** Modal token secret. Default: reads MODAL_TOKEN_SECRET env var. */
+    tokenSecret?: string;
+    /** Modal app name to use. Default: "openlattice". */
+    appName?: string;
+}

package/dist/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { ModalProvider } from "./modal-provider";
+export type { ModalProviderConfig } from "./config";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalProvider = void 0;
+var modal_provider_1 = require("./modal-provider");
+Object.defineProperty(exports, "ModalProvider", { enumerable: true, get: function () { return modal_provider_1.ModalProvider; } });

package/dist/modal-provider.d.ts

@@ -0,0 +1,26 @@
+import type { ComputeProvider, ComputeSpec, ExecOpts, ExecResult, ExtensionMap, HealthStatus, ProviderCapabilities, ProviderNode, ProviderNodeStatus, SnapshotRef } from "openlattice";
+import type { ModalProviderConfig } from "./config";
+export declare class ModalProvider implements ComputeProvider {
+    readonly name = "modal";
+    readonly capabilities: ProviderCapabilities;
+    private readonly config;
+    private client;
+    private app;
+    private readonly sandboxes;
+    constructor(config?: ModalProviderConfig);
+    provision(spec: ComputeSpec): Promise<ProviderNode>;
+    exec(externalId: string, command: string[], opts?: ExecOpts): Promise<ExecResult>;
+    destroy(externalId: string): Promise<void>;
+    inspect(externalId: string): Promise<ProviderNodeStatus>;
+    snapshot(externalId: string): Promise<SnapshotRef>;
+    restore(snapshotRef: SnapshotRef, spec?: Partial<ComputeSpec>): Promise<ProviderNode>;
+    healthCheck(): Promise<HealthStatus>;
+    getExtension<K extends keyof ExtensionMap>(externalId: string, extension: K): ExtensionMap[K] | undefined;
+    private tailscaleUp;
+    private getClient;
+    private getApp;
+    private resolveImage;
+    private getSandbox;
+    private createFileExtension;
+    private createNetworkExtension;
+}

package/dist/modal-provider.js

@@ -0,0 +1,363 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModalProvider = void 0;
+class ModalProvider {
+    constructor(config = {}) {
+        this.name = "modal";
+        this.capabilities = {
+            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"],
+            },
+        };
+        this.client = null;
+        this.app = null;
+        this.sandboxes = new Map();
+        this.config = config;
+    }
+    // ── Required methods ────────────────────────────────────────────
+    async provision(spec) {
+        const client = await this.getClient();
+        const app = await this.getApp(client);
+        const image = this.resolveImage(client, spec.runtime.image);
+        const createOpts = {};
+        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, command, opts) {
+        const sandbox = await this.getSandbox(externalId);
+        // Build command with cwd and env support
+        let cmd = command;
+        if (opts?.cwd || opts?.env) {
+            const parts = [];
+            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 = {
+            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) {
+        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) {
+        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) {
+        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, spec) {
+        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 = {};
+        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() {
+        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) {
+            return {
+                healthy: false,
+                latencyMs: Date.now() - start,
+                message: `[modal] service unreachable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // ── Optional: extensions ──────────────────────────────────────
+    getExtension(externalId, extension) {
+        if (extension === "files") {
+            return this.createFileExtension(externalId);
+        }
+        if (extension === "network") {
+            return this.createNetworkExtension(externalId);
+        }
+        return undefined;
+    }
+    // ── Private helpers ───────────────────────────────────────────
+    async tailscaleUp(sandbox, authKey) {
+        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()}`);
+        }
+    }
+    async getClient() {
+        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 Promise.resolve().then(() => __importStar(require("modal")));
+        const ModalClientClass = modal.ModalClient ?? modal.default?.ModalClient;
+        if (!ModalClientClass) {
+            throw new Error("[modal] could not import ModalClient from modal package");
+        }
+        this.client = new ModalClientClass();
+        return this.client;
+    }
+    async getApp(client) {
+        if (this.app)
+            return this.app;
+        this.app = await client.apps.fromName(this.config.appName ?? "openlattice", { createIfMissing: true });
+        return this.app;
+    }
+    resolveImage(client, image) {
+        // 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 };
+    }
+    async getSandbox(externalId) {
+        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;
+    }
+    createFileExtension(externalId) {
+        const provider = this;
+        return {
+            async read(path) {
+                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, content) {
+                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) {
+                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" : "file",
+                    };
+                });
+            },
+            async remove(path) {
+                const sb = await provider.getSandbox(externalId);
+                const proc = await sb.exec(["rm", "-rf", path], { stdout: "pipe", stderr: "pipe" });
+                await proc.wait();
+            },
+            async mkdir(path) {
+                const sb = await provider.getSandbox(externalId);
+                const proc = await sb.exec(["mkdir", "-p", path], { stdout: "pipe", stderr: "pipe" });
+                await proc.wait();
+            },
+        };
+    }
+    createNetworkExtension(externalId) {
+        const provider = this;
+        return {
+            async getUrl(port) {
+                const sb = await provider.getSandbox(externalId);
+                // Modal provides tunnel URLs via sandbox
+                const tunnelUrl = sb.tunnelUrl ?? sb.getTunnelUrl;
+                if (typeof tunnelUrl === "function") {
+                    return tunnelUrl(port);
+                }
+                // Fallback: construct from sandbox ID
+                return `https://${externalId}--${port}.modal.run`;
+            },
+        };
+    }
+}
+exports.ModalProvider = ModalProvider;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "openlattice-modal",
+  "version": "0.0.3",
+  "description": "Modal compute provider for OpenLattice",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:integration": "vitest run tests/integration.test.ts tests/conformance.test.ts"
+  },
+  "keywords": [
+    "compute",
+    "modal",
+    "openlattice",
+    "provider"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "openlattice": "^0.0.3"
+  },
+  "dependencies": {
+    "modal": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "openlattice": "^0.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/config.ts

@@ -0,0 +1,8 @@
+export interface ModalProviderConfig {
+  /** Modal token ID. Default: reads MODAL_TOKEN_ID env var. */
+  tokenId?: string;
+  /** Modal token secret. Default: reads MODAL_TOKEN_SECRET env var. */
+  tokenSecret?: string;
+  /** Modal app name to use. Default: "openlattice". */
+  appName?: string;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ModalProvider } from "./modal-provider";
+export type { ModalProviderConfig } from "./config";