openlattice-fly 0.0.3

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface FlyProviderConfig {
+    /** Fly.io API token. Default: reads FLY_API_TOKEN env var. */
+    apiToken?: string;
+    /** Fly.io app name. Required. */
+    appName: string;
+    /** API base URL. Default: "https://api.machines.dev". */
+    apiBaseUrl?: string;
+    /** Default region. Default: "ord". */
+    region?: string;
+}

package/dist/config.js

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

package/dist/fly-provider.d.ts

@@ -0,0 +1,24 @@
+import type { ComputeProvider, ComputeSpec, ExecOpts, ExecResult, ExtensionMap, HealthStatus, ProviderCapabilities, ProviderNode, ProviderNodeStatus } from "openlattice";
+import type { FlyProviderConfig } from "./config";
+export declare class FlyProvider implements ComputeProvider {
+    readonly name = "fly";
+    readonly capabilities: ProviderCapabilities;
+    private readonly config;
+    private readonly apiToken;
+    private readonly apiBaseUrl;
+    constructor(config: FlyProviderConfig);
+    provision(spec: ComputeSpec): Promise<ProviderNode>;
+    exec(externalId: string, command: string[], opts?: ExecOpts): Promise<ExecResult>;
+    destroy(externalId: string): Promise<void>;
+    inspect(externalId: string): Promise<ProviderNodeStatus>;
+    stop(externalId: string): Promise<void>;
+    start(externalId: string): Promise<void>;
+    pause(externalId: string): Promise<void>;
+    resume(externalId: string): Promise<void>;
+    healthCheck(): Promise<HealthStatus>;
+    getExtension<K extends keyof ExtensionMap>(externalId: string, extension: K): ExtensionMap[K] | undefined;
+    private tailscaleUp;
+    private buildMachineConfig;
+    private flyRequest;
+    private createNetworkExtension;
+}

package/dist/fly-provider.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlyProvider = void 0;
+class FlyProvider {
+    constructor(config) {
+        this.name = "fly";
+        this.capabilities = {
+            restart: true,
+            pause: true,
+            snapshot: false,
+            gpu: true,
+            logs: false,
+            tailscale: true,
+            coldStartMs: 500,
+            maxConcurrent: 0,
+            architectures: ["x86_64"],
+            persistentStorage: true,
+            constraints: {
+                maxPauseMemoryMiB: 2048,
+                pauseExcludesGpu: true,
+                gpuTypes: ["a10", "l40s", "a100-40gb", "a100-80gb"],
+            },
+        };
+        if (!config.appName) {
+            throw new Error("[fly] appName is required");
+        }
+        this.config = config;
+        this.apiToken = config.apiToken ?? process.env.FLY_API_TOKEN ?? "";
+        this.apiBaseUrl = config.apiBaseUrl ?? "https://api.machines.dev";
+        if (!this.apiToken) {
+            throw new Error("[fly] API token is required (set FLY_API_TOKEN or pass apiToken)");
+        }
+    }
+    // ── Required methods ────────────────────────────────────────────
+    async provision(spec) {
+        const machineConfig = this.buildMachineConfig(spec);
+        const machine = await this.flyRequest("POST", "/machines", {
+            name: spec.name,
+            region: this.config.region ?? "ord",
+            config: machineConfig,
+        });
+        // Wait for machine to be started
+        await this.flyRequest("GET", `/machines/${machine.id}/wait?state=started&timeout=60`);
+        // Join Tailscale network if auth key provided
+        if (spec.network?.tailscaleAuthKey) {
+            await this.tailscaleUp(machine.id, spec.network.tailscaleAuthKey);
+        }
+        const endpoints = [];
+        if (spec.network?.ports) {
+            for (const p of spec.network.ports) {
+                endpoints.push({
+                    type: "fly",
+                    host: `${machine.id}.fly.dev`,
+                    port: p.port,
+                    url: `https://${this.config.appName}.fly.dev`,
+                });
+            }
+        }
+        return {
+            externalId: machine.id,
+            endpoints,
+            metadata: {
+                appName: this.config.appName,
+                region: machine.region,
+                machineName: machine.name,
+            },
+        };
+    }
+    async exec(externalId, command, opts) {
+        // 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 timeout = opts?.timeoutMs ? Math.floor(opts.timeoutMs / 1000) : 60;
+        const result = await this.flyRequest("POST", `/machines/${externalId}/exec`, { cmd, timeout });
+        const stdout = result.stdout ?? "";
+        const stderr = result.stderr ?? "";
+        opts?.onStdout?.(stdout);
+        opts?.onStderr?.(stderr);
+        return {
+            exitCode: result.exit_code ?? 0,
+            stdout,
+            stderr,
+        };
+    }
+    async destroy(externalId) {
+        try {
+            await this.flyRequest("DELETE", `/machines/${externalId}?force=true`);
+        }
+        catch (err) {
+            if (!isNotFound(err)) {
+                throw new Error(`[fly] destroy failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    async inspect(externalId) {
+        try {
+            const machine = await this.flyRequest("GET", `/machines/${externalId}`);
+            return {
+                status: mapFlyState(machine.state),
+                startedAt: machine.created_at
+                    ? new Date(machine.created_at)
+                    : undefined,
+            };
+        }
+        catch (err) {
+            if (isNotFound(err)) {
+                return { status: "terminated" };
+            }
+            return { status: "unknown" };
+        }
+    }
+    // ── Optional: stop / start ──────────────────────────────────────
+    async stop(externalId) {
+        try {
+            await this.flyRequest("POST", `/machines/${externalId}/stop`, { signal: "SIGTERM", timeout: "10s" });
+        }
+        catch (err) {
+            if (!isNotFound(err)) {
+                throw new Error(`[fly] stop failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    async start(externalId) {
+        await this.flyRequest("POST", `/machines/${externalId}/start`);
+        await this.flyRequest("GET", `/machines/${externalId}/wait?state=started&timeout=60`);
+    }
+    // ── Optional: pause / resume ──────────────────────────────────
+    async pause(externalId) {
+        await this.flyRequest("POST", `/machines/${externalId}/suspend`);
+    }
+    async resume(externalId) {
+        // start auto-detects suspended machines and resumes from snapshot
+        await this.start(externalId);
+    }
+    // ── Optional: healthCheck ─────────────────────────────────────
+    async healthCheck() {
+        const start = Date.now();
+        try {
+            await this.flyRequest("GET", "/machines");
+            return {
+                healthy: true,
+                latencyMs: Date.now() - start,
+            };
+        }
+        catch (err) {
+            return {
+                healthy: false,
+                latencyMs: Date.now() - start,
+                message: `[fly] API unreachable: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // ── Optional: extensions ──────────────────────────────────────
+    getExtension(externalId, extension) {
+        if (extension === "network") {
+            return this.createNetworkExtension(externalId);
+        }
+        return undefined;
+    }
+    // ── Private helpers ───────────────────────────────────────────
+    async tailscaleUp(machineId, authKey) {
+        const result = await this.exec(machineId, [
+            "sh",
+            "-c",
+            `pgrep tailscaled >/dev/null 2>&1 || tailscaled --state=/var/lib/tailscale/tailscaled.state & sleep 1 && tailscale up --authkey=${authKey}`,
+        ]);
+        if (result.exitCode !== 0) {
+            throw new Error(`[fly] tailscale up failed: ${result.stderr.trim()}`);
+        }
+    }
+    buildMachineConfig(spec) {
+        const config = {
+            image: spec.runtime.image,
+            env: spec.runtime.env,
+            init: spec.runtime.command
+                ? { exec: spec.runtime.command }
+                : { exec: ["/bin/sleep", "inf"] },
+            guest: {
+                cpus: spec.cpu?.cores ?? 1,
+                memory_mb: spec.memory ? spec.memory.sizeGiB * 1024 : 256,
+                cpu_kind: "shared",
+                ...(spec.gpu?.type ? { gpu_kind: spec.gpu.type } : {}),
+            },
+            auto_destroy: false,
+            restart: { policy: "no" },
+        };
+        if (spec.network?.ports && spec.network.ports.length > 0) {
+            config.services = spec.network.ports.map((p) => ({
+                ports: [{ port: p.port, handlers: ["tls", "http"] }],
+                protocol: "tcp",
+                internal_port: p.port,
+            }));
+        }
+        return config;
+    }
+    async flyRequest(method, path, body) {
+        const url = `${this.apiBaseUrl}/v1/apps/${this.config.appName}${path}`;
+        const maxRetries = 3;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: body ? JSON.stringify(body) : undefined,
+            });
+            // Retry on 429 with exponential backoff
+            if (response.status === 429 && attempt < maxRetries) {
+                const backoffMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
+                await new Promise((r) => setTimeout(r, backoffMs));
+                continue;
+            }
+            if (!response.ok) {
+                const text = await response.text();
+                const err = new Error(`[fly] ${method} ${path} failed (${response.status}): ${text}`);
+                err.statusCode = response.status;
+                throw err;
+            }
+            if (response.status === 204 || response.headers.get("content-length") === "0") {
+                return undefined;
+            }
+            return response.json();
+        }
+        throw new Error(`[fly] ${method} ${path} failed: max retries exceeded`);
+    }
+    createNetworkExtension(externalId) {
+        const appName = this.config.appName;
+        return {
+            async getUrl(port) {
+                // Fly.io routes HTTPS traffic through its proxy on port 443.
+                // Internal ports are mapped via fly.toml [[services]] config.
+                // Standard HTTPS (443) omits the port for a clean URL.
+                if (port === 443 || port === 80) {
+                    return `https://${appName}.fly.dev`;
+                }
+                // For non-standard ports, use Fly's internal DNS with .flycast
+                // which supports direct port access within the private network.
+                return `http://${appName}.flycast:${port}`;
+            },
+        };
+    }
+}
+exports.FlyProvider = FlyProvider;
+// ── Utility functions ─────────────────────────────────────────────
+function mapFlyState(state) {
+    switch (state) {
+        case "started":
+        case "replacing":
+            return "running";
+        case "stopped":
+            return "stopped";
+        case "suspended":
+            return "paused";
+        case "destroyed":
+        case "destroying":
+            return "terminated";
+        default:
+            return "unknown";
+    }
+}
+function isNotFound(err) {
+    if (err && typeof err === "object") {
+        return err.statusCode === 404;
+    }
+    return false;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { FlyProvider } from "./fly-provider";
+export type { FlyProviderConfig } from "./config";

package/dist/index.js

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "openlattice-fly",
+  "version": "0.0.3",
+  "description": "Fly.io 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",
+    "fly",
+    "fly.io",
+    "openlattice",
+    "provider"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "openlattice": "^0.0.3"
+  },
+  "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,10 @@
+export interface FlyProviderConfig {
+  /** Fly.io API token. Default: reads FLY_API_TOKEN env var. */
+  apiToken?: string;
+  /** Fly.io app name. Required. */
+  appName: string;
+  /** API base URL. Default: "https://api.machines.dev". */
+  apiBaseUrl?: string;
+  /** Default region. Default: "ord". */
+  region?: string;
+}