openlattice-ssh 0.0.3

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+export interface SSHProviderConfig {
+    /** SSH connection targets. At least one required. */
+    hosts: SSHHostConfig[];
+    /** Default user for SSH connections. */
+    defaultUser?: string;
+    /** Default private key content (string or Buffer). */
+    defaultPrivateKey?: string | Buffer;
+    /** Path to default private key file. Used if defaultPrivateKey is not set. */
+    defaultKeyPath?: string;
+    /** Connection timeout in ms. Default: 20_000. */
+    connectTimeoutMs?: number;
+    /** Keepalive interval in ms. Default: 10_000. */
+    keepaliveIntervalMs?: number;
+}
+export interface SSHHostConfig {
+    /** Hostname or IP address. */
+    host: string;
+    /** SSH port. Default: 22. */
+    port?: number;
+    /** Username. Overrides defaultUser. */
+    username?: string;
+    /** Private key (content or path). Overrides defaultPrivateKey. */
+    privateKey?: string | Buffer;
+    /** Password (not recommended). */
+    password?: string;
+    /** Labels for host selection. */
+    labels?: Record<string, string>;
+    /** Whether this host has GPU. */
+    gpuAvailable?: boolean;
+}

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 { SSHProvider } from "./ssh-provider";
+export type { SSHProviderConfig, SSHHostConfig } from "./config";

package/dist/index.js

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

package/dist/ssh-provider.d.ts

@@ -0,0 +1,30 @@
+import type { ComputeProvider, ComputeSpec, ExecOpts, ExecResult, ExtensionMap, HealthStatus, ProviderCapabilities, ProviderNode, ProviderNodeStatus } from "openlattice";
+import type { SSHProviderConfig } from "./config";
+export declare class SSHProvider implements ComputeProvider {
+    readonly name = "ssh";
+    readonly capabilities: ProviderCapabilities;
+    private readonly config;
+    private readonly connections;
+    private readonly nodes;
+    private roundRobinIdx;
+    constructor(config: SSHProviderConfig);
+    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>;
+    healthCheck(): Promise<HealthStatus>;
+    getExtension<K extends keyof ExtensionMap>(externalId: string, extension: K): ExtensionMap[K] | undefined;
+    /** Close all SSH connections. Call when shutting down the provider. */
+    close(): Promise<void>;
+    private createNetworkExtension;
+    private selectHost;
+    private getNodeState;
+    private getConnection;
+    private ensureTailscale;
+    private tailscaleUp;
+    private sshExec;
+    private getSftp;
+    private createFileExtension;
+}

package/dist/ssh-provider.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSHProvider = void 0;
+const fs_1 = require("fs");
+const ssh2_1 = require("ssh2");
+let nextSessionId = 1;
+class SSHProvider {
+    constructor(config) {
+        this.name = "ssh";
+        this.connections = new Map();
+        this.nodes = new Map();
+        this.roundRobinIdx = 0;
+        if (!config.hosts || config.hosts.length === 0) {
+            throw new Error("[ssh] at least one host must be configured");
+        }
+        // Load private key from file path if defaultKeyPath is set and no key content
+        if (config.defaultKeyPath && !config.defaultPrivateKey) {
+            config.defaultPrivateKey = (0, fs_1.readFileSync)(config.defaultKeyPath);
+        }
+        this.config = config;
+        const hasGpu = config.hosts.some((h) => h.gpuAvailable);
+        this.capabilities = {
+            restart: true,
+            pause: false, // SIGSTOP unreliable via SSH
+            snapshot: false,
+            gpu: hasGpu,
+            logs: false,
+            tailscale: true,
+            coldStartMs: 1000,
+            maxConcurrent: 0,
+            architectures: ["x86_64", "arm64"],
+            persistentStorage: true,
+        };
+    }
+    // ── Required methods ────────────────────────────────────────────
+    async provision(spec) {
+        const host = this.selectHost(spec);
+        const conn = await this.getConnection(host);
+        const sessionId = `ssh-${nextSessionId++}`;
+        const hostKey = hostKeyOf(host);
+        const externalId = `${hostKey}/${sessionId}`;
+        const workdir = `/tmp/openlattice/${sessionId}`;
+        // Create working directory and validate connectivity
+        await this.sshExec(conn, `mkdir -p ${workdir}`);
+        // Store node state
+        const state = {
+            host,
+            workdir,
+            startedAt: new Date(),
+        };
+        this.nodes.set(externalId, state);
+        // Ensure Tailscale is installed and running if requested (authKey implies tailscale)
+        if (spec.network?.tailscale || spec.network?.tailscaleAuthKey) {
+            await this.ensureTailscale(conn);
+            if (spec.network?.tailscaleAuthKey) {
+                await this.tailscaleUp(conn, spec.network.tailscaleAuthKey);
+            }
+        }
+        // Run initial command in background if specified
+        if (spec.runtime.command && spec.runtime.command.length > 0) {
+            const cmd = spec.runtime.command.join(" ");
+            const envPrefix = buildEnvPrefix(spec.runtime.env);
+            state.command = cmd;
+            state.envPrefix = envPrefix;
+            const result = await this.sshExec(conn, `cd ${workdir} && ${envPrefix}nohup ${cmd} > ${workdir}/.stdout 2> ${workdir}/.stderr & echo $!`);
+            const pid = parseInt(result.stdout.trim(), 10);
+            if (!isNaN(pid)) {
+                state.pid = pid;
+            }
+        }
+        return {
+            externalId,
+            endpoints: [
+                {
+                    type: "ssh",
+                    host: host.host,
+                    port: host.port ?? 22,
+                },
+            ],
+            metadata: { hostKey, sessionId, workdir },
+        };
+    }
+    async exec(externalId, command, opts) {
+        const state = this.getNodeState(externalId);
+        const conn = await this.getConnection(state.host);
+        const cmdStr = command.join(" ");
+        const cwd = opts?.cwd ?? state.workdir;
+        const envPrefix = buildEnvPrefix(opts?.env);
+        const fullCmd = `cd ${cwd} && ${envPrefix}${cmdStr}`;
+        return this.sshExec(conn, fullCmd, opts);
+    }
+    async destroy(externalId) {
+        const state = this.nodes.get(externalId);
+        if (!state)
+            return; // idempotent
+        try {
+            const conn = await this.getConnection(state.host);
+            // Kill managed process if any
+            if (state.pid) {
+                await this.sshExec(conn, `kill ${state.pid} 2>/dev/null || true`);
+            }
+            // Remove working directory
+            await this.sshExec(conn, `rm -rf ${state.workdir}`);
+        }
+        catch {
+            // Best-effort cleanup
+        }
+        this.nodes.delete(externalId);
+    }
+    async inspect(externalId) {
+        const state = this.nodes.get(externalId);
+        if (!state) {
+            return { status: "terminated" };
+        }
+        try {
+            const conn = await this.getConnection(state.host);
+            if (state.pid) {
+                // Check if process is still running
+                const result = await this.sshExec(conn, `kill -0 ${state.pid} 2>/dev/null && echo running || echo stopped`);
+                const status = result.stdout.trim() === "running" ? "running" : "stopped";
+                return {
+                    status,
+                    startedAt: state.startedAt,
+                };
+            }
+            // No PID tracked — just check SSH connectivity
+            await this.sshExec(conn, "echo ok");
+            return {
+                status: "running",
+                startedAt: state.startedAt,
+            };
+        }
+        catch {
+            return { status: "unknown" };
+        }
+    }
+    // ── Optional: stop / start ──────────────────────────────────────
+    async stop(externalId) {
+        const state = this.getNodeState(externalId);
+        if (!state.pid)
+            return;
+        const conn = await this.getConnection(state.host);
+        await this.sshExec(conn, `kill ${state.pid} 2>/dev/null || true`);
+        state.pid = undefined;
+    }
+    async start(externalId) {
+        const state = this.getNodeState(externalId);
+        const conn = await this.getConnection(state.host);
+        // Re-run the original command if one was stored
+        if (state.command) {
+            const envPrefix = state.envPrefix ?? "";
+            const result = await this.sshExec(conn, `cd ${state.workdir} && ${envPrefix}nohup ${state.command} > ${state.workdir}/.stdout 2> ${state.workdir}/.stderr & echo $!`);
+            const pid = parseInt(result.stdout.trim(), 10);
+            if (!isNaN(pid)) {
+                state.pid = pid;
+            }
+        }
+        else {
+            // No command to restart, just verify connectivity
+            await this.sshExec(conn, "echo ok");
+        }
+    }
+    // ── Optional: healthCheck ───────────────────────────────────────
+    async healthCheck() {
+        const start = Date.now();
+        const results = [];
+        for (const host of this.config.hosts) {
+            try {
+                const conn = await this.getConnection(host);
+                await this.sshExec(conn, "echo ok");
+                results.push({ host: host.host, ok: true });
+            }
+            catch (err) {
+                results.push({
+                    host: host.host,
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const allHealthy = results.every((r) => r.ok);
+        const unhealthy = results.filter((r) => !r.ok);
+        return {
+            healthy: allHealthy,
+            latencyMs: Date.now() - start,
+            message: allHealthy
+                ? undefined
+                : `Unhealthy hosts: ${unhealthy.map((r) => `${r.host} (${r.error})`).join(", ")}`,
+        };
+    }
+    // ── Optional: extensions ────────────────────────────────────────
+    getExtension(externalId, extension) {
+        if (extension === "files") {
+            return this.createFileExtension(externalId);
+        }
+        if (extension === "network") {
+            return this.createNetworkExtension(externalId);
+        }
+        return undefined;
+    }
+    /** Close all SSH connections. Call when shutting down the provider. */
+    async close() {
+        for (const conn of this.connections.values()) {
+            conn.end();
+        }
+        this.connections.clear();
+        this.nodes.clear();
+    }
+    // ── Private helpers ─────────────────────────────────────────────
+    createNetworkExtension(externalId) {
+        const state = this.getNodeState(externalId);
+        const host = state.host.host;
+        return {
+            async getUrl(port) {
+                return `http://${host}:${port}`;
+            },
+        };
+    }
+    selectHost(spec) {
+        let candidates = [...this.config.hosts];
+        // Filter by GPU if requested
+        if (spec.gpu && spec.gpu.count > 0) {
+            candidates = candidates.filter((h) => h.gpuAvailable);
+            if (candidates.length === 0) {
+                throw new Error("[ssh] no hosts with GPU available");
+            }
+        }
+        // Filter by labels if specified
+        if (spec.labels) {
+            candidates = candidates.filter((h) => {
+                if (!h.labels)
+                    return false;
+                return Object.entries(spec.labels).every(([k, v]) => h.labels[k] === v);
+            });
+            if (candidates.length === 0) {
+                throw new Error("[ssh] no hosts matching labels");
+            }
+        }
+        if (candidates.length === 0) {
+            throw new Error("[ssh] no hosts available");
+        }
+        // Round-robin selection
+        const host = candidates[this.roundRobinIdx % candidates.length];
+        this.roundRobinIdx++;
+        return host;
+    }
+    getNodeState(externalId) {
+        const state = this.nodes.get(externalId);
+        if (!state) {
+            throw new Error(`[ssh] node not found: ${externalId}`);
+        }
+        return state;
+    }
+    async getConnection(host) {
+        const key = hostKeyOf(host);
+        const existing = this.connections.get(key);
+        if (existing)
+            return existing;
+        const conn = new ssh2_1.Client();
+        return new Promise((resolve, reject) => {
+            conn.on("ready", () => {
+                this.connections.set(key, conn);
+                resolve(conn);
+            });
+            conn.on("error", (err) => {
+                this.connections.delete(key);
+                reject(new Error(`[ssh] connection error (${key}): ${err.message}`));
+            });
+            conn.on("close", () => {
+                this.connections.delete(key);
+            });
+            conn.connect({
+                host: host.host,
+                port: host.port ?? 22,
+                username: host.username ?? this.config.defaultUser,
+                privateKey: host.privateKey ?? this.config.defaultPrivateKey,
+                password: host.password,
+                readyTimeout: this.config.connectTimeoutMs ?? 20000,
+                keepaliveInterval: this.config.keepaliveIntervalMs ?? 10000,
+                keepaliveCountMax: 3,
+            });
+        });
+    }
+    async ensureTailscale(conn) {
+        // Check if tailscale is installed
+        const check = await this.sshExec(conn, "which tailscale 2>/dev/null");
+        if (check.exitCode !== 0) {
+            // Install Tailscale via official install script
+            const install = await this.sshExec(conn, "curl -fsSL https://tailscale.com/install.sh | sh", { timeoutMs: 120000 });
+            if (install.exitCode !== 0) {
+                throw new Error(`[ssh] failed to install tailscale: ${install.stderr.trim()}`);
+            }
+        }
+        // Ensure tailscaled is running
+        const daemonCheck = await this.sshExec(conn, "pgrep tailscaled >/dev/null 2>&1 || sudo tailscaled --state=/var/lib/tailscale/tailscaled.state &", { timeoutMs: 10000 });
+        if (daemonCheck.exitCode !== 0) {
+            // Try systemd as fallback
+            await this.sshExec(conn, "sudo systemctl start tailscaled 2>/dev/null || true", {
+                timeoutMs: 10000,
+            });
+        }
+    }
+    async tailscaleUp(conn, authKey) {
+        const result = await this.sshExec(conn, `sudo tailscale up --authkey=${authKey}`, { timeoutMs: 30000 });
+        if (result.exitCode !== 0) {
+            throw new Error(`[ssh] tailscale up failed: ${result.stderr.trim()}`);
+        }
+    }
+    sshExec(conn, command, opts) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                fn();
+            };
+            conn.exec(command, (err, stream) => {
+                if (err) {
+                    return settle(() => reject(new Error(`[ssh] exec failed: ${err.message}`)));
+                }
+                let stdout = "";
+                let stderr = "";
+                // Enforce timeout
+                if (opts?.timeoutMs && opts.timeoutMs > 0) {
+                    timer = setTimeout(() => {
+                        stream.close();
+                        settle(() => resolve({
+                            exitCode: 124, // Conventional timeout exit code
+                            stdout,
+                            stderr: stderr + `\n[ssh] command timed out after ${opts.timeoutMs}ms`,
+                        }));
+                    }, opts.timeoutMs);
+                }
+                stream.on("data", (data) => {
+                    const str = data.toString();
+                    stdout += str;
+                    opts?.onStdout?.(str);
+                });
+                stream.stderr.on("data", (data) => {
+                    const str = data.toString();
+                    stderr += str;
+                    opts?.onStderr?.(str);
+                });
+                stream.on("close", (code) => {
+                    settle(() => resolve({ exitCode: code ?? 1, stdout, stderr }));
+                });
+            });
+        });
+    }
+    getSftp(conn) {
+        return new Promise((resolve, reject) => {
+            conn.sftp((err, sftp) => {
+                if (err)
+                    return reject(new Error(`[ssh] SFTP failed: ${err.message}`));
+                resolve(sftp);
+            });
+        });
+    }
+    createFileExtension(externalId) {
+        const provider = this;
+        return {
+            async read(path) {
+                const state = provider.getNodeState(externalId);
+                const conn = await provider.getConnection(state.host);
+                const sftp = await provider.getSftp(conn);
+                return new Promise((resolve, reject) => {
+                    sftp.readFile(path, (err, data) => {
+                        if (err)
+                            return reject(err);
+                        resolve(data.toString());
+                    });
+                });
+            },
+            async write(path, content) {
+                const state = provider.getNodeState(externalId);
+                const conn = await provider.getConnection(state.host);
+                const sftp = await provider.getSftp(conn);
+                return new Promise((resolve, reject) => {
+                    sftp.writeFile(path, typeof content === "string" ? content : content, (err) => {
+                        if (err)
+                            return reject(err);
+                        resolve();
+                    });
+                });
+            },
+            async list(dirPath) {
+                const state = provider.getNodeState(externalId);
+                const conn = await provider.getConnection(state.host);
+                const sftp = await provider.getSftp(conn);
+                return new Promise((resolve, reject) => {
+                    sftp.readdir(dirPath, (err, list) => {
+                        if (err)
+                            return reject(err);
+                        resolve(list.map((entry) => ({
+                            name: entry.filename,
+                            path: `${dirPath}/${entry.filename}`,
+                            type: (entry.longname.startsWith("d")
+                                ? "directory"
+                                : "file"),
+                            size: entry.attrs.size,
+                        })));
+                    });
+                });
+            },
+            async remove(path) {
+                const state = provider.getNodeState(externalId);
+                const conn = await provider.getConnection(state.host);
+                const sftp = await provider.getSftp(conn);
+                return new Promise((resolve, reject) => {
+                    sftp.unlink(path, (err) => {
+                        if (err)
+                            return reject(err);
+                        resolve();
+                    });
+                });
+            },
+            async mkdir(dirPath) {
+                const state = provider.getNodeState(externalId);
+                const conn = await provider.getConnection(state.host);
+                // Use exec with mkdir -p for recursive directory creation
+                await provider.sshExec(conn, `mkdir -p '${dirPath.replace(/'/g, "'\\''")}'`);
+            },
+        };
+    }
+}
+exports.SSHProvider = SSHProvider;
+// ── Utility functions ───────────────────────────────────────────────
+function hostKeyOf(host) {
+    return `${host.host}:${host.port ?? 22}`;
+}
+function buildEnvPrefix(env) {
+    if (!env)
+        return "";
+    return (Object.entries(env)
+        .map(([k, v]) => `${k}='${v.replace(/'/g, "'\\''")}'`)
+        .join(" ") + " ");
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "openlattice-ssh",
+  "version": "0.0.3",
+  "description": "SSH 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": "TEST_SSH=1 vitest run tests/integration.test.ts tests/conformance.test.ts"
+  },
+  "keywords": [
+    "compute",
+    "ssh",
+    "openlattice",
+    "provider"
+  ],
+  "license": "ISC",
+  "peerDependencies": {
+    "openlattice": "^0.0.3"
+  },
+  "dependencies": {
+    "ssh2": "^1.16.0"
+  },
+  "devDependencies": {
+    "@types/ssh2": "^1.15.5",
+    "@types/node": "^25.2.2",
+    "openlattice": "^0.0.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/src/config.ts

@@ -0,0 +1,42 @@
+export interface SSHProviderConfig {
+  /** SSH connection targets. At least one required. */
+  hosts: SSHHostConfig[];
+
+  /** Default user for SSH connections. */
+  defaultUser?: string;
+
+  /** Default private key content (string or Buffer). */
+  defaultPrivateKey?: string | Buffer;
+
+  /** Path to default private key file. Used if defaultPrivateKey is not set. */
+  defaultKeyPath?: string;
+
+  /** Connection timeout in ms. Default: 20_000. */
+  connectTimeoutMs?: number;
+
+  /** Keepalive interval in ms. Default: 10_000. */
+  keepaliveIntervalMs?: number;
+}
+
+export interface SSHHostConfig {
+  /** Hostname or IP address. */
+  host: string;
+
+  /** SSH port. Default: 22. */
+  port?: number;
+
+  /** Username. Overrides defaultUser. */
+  username?: string;
+
+  /** Private key (content or path). Overrides defaultPrivateKey. */
+  privateKey?: string | Buffer;
+
+  /** Password (not recommended). */
+  password?: string;
+
+  /** Labels for host selection. */
+  labels?: Record<string, string>;
+
+  /** Whether this host has GPU. */
+  gpuAvailable?: boolean;
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { SSHProvider } from "./ssh-provider";
+export type { SSHProviderConfig, SSHHostConfig } from "./config";