openlattice-fly 0.0.3

package/src/fly-provider.ts

@@ -0,0 +1,405 @@
+import type {
+  ComputeProvider,
+  ComputeSpec,
+  ExecOpts,
+  ExecResult,
+  ExtensionMap,
+  HealthStatus,
+  NetworkExtension,
+  ProviderCapabilities,
+  ProviderNode,
+  ProviderNodeStatus,
+} from "openlattice";
+import type { FlyProviderConfig } from "./config";
+
+/** Fly Machine state as returned by the Machines API. */
+interface FlyMachine {
+  id: string;
+  name?: string;
+  state: string;
+  region: string;
+  instance_id?: string;
+  config?: Record<string, unknown>;
+  created_at?: string;
+}
+
+/** Exec response from the Machines API. */
+interface FlyExecResponse {
+  exit_code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export class FlyProvider implements ComputeProvider {
+  readonly name = "fly";
+  readonly capabilities: ProviderCapabilities = {
+    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"],
+    },
+  };
+
+  private readonly config: FlyProviderConfig;
+  private readonly apiToken: string;
+  private readonly apiBaseUrl: string;
+
+  constructor(config: FlyProviderConfig) {
+    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: ComputeSpec): Promise<ProviderNode> {
+    const machineConfig = this.buildMachineConfig(spec);
+
+    const machine = await this.flyRequest<FlyMachine>(
+      "POST",
+      "/machines",
+      {
+        name: spec.name,
+        region: this.config.region ?? "ord",
+        config: machineConfig,
+      }
+    );
+
+    // Wait for machine to be started
+    await this.flyRequest<void>(
+      "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: string,
+    command: string[],
+    opts?: ExecOpts
+  ): Promise<ExecResult> {
+    // 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 timeout = opts?.timeoutMs ? Math.floor(opts.timeoutMs / 1000) : 60;
+
+    const result = await this.flyRequest<FlyExecResponse>(
+      "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: string): Promise<void> {
+    try {
+      await this.flyRequest<void>(
+        "DELETE",
+        `/machines/${externalId}?force=true`
+      );
+    } catch (err: unknown) {
+      if (!isNotFound(err)) {
+        throw new Error(
+          `[fly] destroy failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+
+  async inspect(externalId: string): Promise<ProviderNodeStatus> {
+    try {
+      const machine = await this.flyRequest<FlyMachine>(
+        "GET",
+        `/machines/${externalId}`
+      );
+
+      return {
+        status: mapFlyState(machine.state),
+        startedAt: machine.created_at
+          ? new Date(machine.created_at)
+          : undefined,
+      };
+    } catch (err: unknown) {
+      if (isNotFound(err)) {
+        return { status: "terminated" };
+      }
+      return { status: "unknown" };
+    }
+  }
+
+  // ── Optional: stop / start ──────────────────────────────────────
+
+  async stop(externalId: string): Promise<void> {
+    try {
+      await this.flyRequest<void>(
+        "POST",
+        `/machines/${externalId}/stop`,
+        { signal: "SIGTERM", timeout: "10s" }
+      );
+    } catch (err: unknown) {
+      if (!isNotFound(err)) {
+        throw new Error(
+          `[fly] stop failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+
+  async start(externalId: string): Promise<void> {
+    await this.flyRequest<void>(
+      "POST",
+      `/machines/${externalId}/start`
+    );
+    await this.flyRequest<void>(
+      "GET",
+      `/machines/${externalId}/wait?state=started&timeout=60`
+    );
+  }
+
+  // ── Optional: pause / resume ──────────────────────────────────
+
+  async pause(externalId: string): Promise<void> {
+    await this.flyRequest<void>(
+      "POST",
+      `/machines/${externalId}/suspend`
+    );
+  }
+
+  async resume(externalId: string): Promise<void> {
+    // start auto-detects suspended machines and resumes from snapshot
+    await this.start(externalId);
+  }
+
+  // ── Optional: healthCheck ─────────────────────────────────────
+
+  async healthCheck(): Promise<HealthStatus> {
+    const start = Date.now();
+    try {
+      await this.flyRequest<FlyMachine[]>("GET", "/machines");
+      return {
+        healthy: true,
+        latencyMs: Date.now() - start,
+      };
+    } catch (err: unknown) {
+      return {
+        healthy: false,
+        latencyMs: Date.now() - start,
+        message: `[fly] API unreachable: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  // ── Optional: extensions ──────────────────────────────────────
+
+  getExtension<K extends keyof ExtensionMap>(
+    externalId: string,
+    extension: K
+  ): ExtensionMap[K] | undefined {
+    if (extension === "network") {
+      return this.createNetworkExtension(externalId) as ExtensionMap[K];
+    }
+    return undefined;
+  }
+
+  // ── Private helpers ───────────────────────────────────────────
+
+  private async tailscaleUp(
+    machineId: string,
+    authKey: string
+  ): Promise<void> {
+    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()}`
+      );
+    }
+  }
+
+  private buildMachineConfig(spec: ComputeSpec): Record<string, unknown> {
+    const config: Record<string, unknown> = {
+      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;
+  }
+
+  private async flyRequest<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    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 as any).statusCode = response.status;
+        throw err;
+      }
+
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return undefined as T;
+      }
+
+      return response.json() as Promise<T>;
+    }
+
+    throw new Error(`[fly] ${method} ${path} failed: max retries exceeded`);
+  }
+
+  private createNetworkExtension(externalId: string): NetworkExtension {
+    const appName = this.config.appName;
+    return {
+      async getUrl(port: number): Promise<string> {
+        // 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}`;
+      },
+    };
+  }
+}
+
+// ── Utility functions ─────────────────────────────────────────────
+
+function mapFlyState(
+  state: string
+): "running" | "stopped" | "paused" | "terminated" | "unknown" {
+  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: unknown): boolean {
+  if (err && typeof err === "object") {
+    return (err as any).statusCode === 404;
+  }
+  return false;
+}

package/src/index.ts

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

package/tests/conformance.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { runProviderConformanceTests } from "openlattice/testing";
+import { FlyProvider } from "../src/fly-provider";
+
+const HAS_FLY =
+  !!process.env.FLY_API_TOKEN && !!process.env.FLY_APP_NAME;
+
+describe.skipIf(!HAS_FLY)("FlyProvider conformance", () => {
+  runProviderConformanceTests(
+    {
+      createProvider: () =>
+        new FlyProvider({
+          appName: process.env.FLY_APP_NAME!,
+          apiToken: process.env.FLY_API_TOKEN,
+          region: process.env.FLY_REGION ?? "ord",
+        }),
+      createSpec: () => ({
+        runtime: { image: "alpine:3.19" },
+      }),
+      timeoutMs: 120_000,
+    },
+    { describe, it, expect, beforeEach, afterEach }
+  );
+});