swarmy 0.1.1 → 0.2.0

package/README.md

@@ -39,7 +39,35 @@ Provision ephemeral Docker containers across multiple nodes and interact with th
 - Docker
 - npm
 
-### Manager
+### Using npx (recommended)
+
+**Manager:**
+
+```bash
+npx --yes swarmy@latest manager start
+```
+
+This prints the token and connection instructions for workers.
+
+**Worker** (on each node):
+
+```bash
+npx --yes swarmy@latest worker start --url http://<manager-ip>:5174 --token <token>
+```
+
+**Other commands:**
+
+```bash
+npx swarmy manager status     # Show PID + token
+npx swarmy manager stop       # Stop manager
+npx swarmy manager restart    # Restart manager
+npx swarmy worker status      # Show worker PID
+npx swarmy worker stop        # Stop worker
+```
+
+### From source (development)
+
+**Manager:**
 
 ```bash
 cd manager
@@ -49,9 +77,7 @@ npm run dev
 
 The manager starts on port 5174. An auth token is auto-generated at `manager/data/token` on first run.
 
-### Worker
-
-On each node that will run containers:
+**Worker** (on each node):
 
 ```bash
 cd worker
@@ -90,7 +116,7 @@ Installs to `/opt/swarm`. Services auto-restart on failure.
 
 | Variable        | Component | Description                            |
 | --------------- | --------- | -------------------------------------- |
-| `PORT`          | Manager   | HTTP port (default: 3000)              |
+| `PORT`          | Manager   | HTTP port (default: 5174)              |
 | `SWARM_URL`     | Worker    | Manager URL to connect to              |
 | `SWARM_TOKEN`   | Worker    | Auth token for registration            |
 | `SWARM_NODE_ID` | Worker    | Node identifier (default: hostname)    |
@@ -110,6 +136,9 @@ All REST endpoints require `Authorization: Bearer <token>` header.
 | `POST`   | `/api/sessions`           | Spawn terminal session in container |
 | `DELETE` | `/api/sessions/:id`       | Kill session                        |
 | `POST`   | `/api/sessions/:id/input` | Send input to session               |
+| `PATCH`  | `/api/sessions/:id`       | Toggle interactive mode             |
+| `POST`   | `/api/containers/:id/thumbnail` | Upload VNC thumbnail (base64 JPEG) |
+| `GET`    | `/api/containers/:id/thumbnail` | Get VNC thumbnail (supports `?token=`) |
 | `GET`    | `/api/status`             | Server status                       |
 
 ## Tech Stack

package/bin/swarmy.js

@@ -139,31 +139,177 @@ const cliArgs = process.argv.slice(2);
 const role = cliArgs[0];
 const action = cliArgs[1];
 
-function usage() {
+const hasFlag = (flag) => cliArgs.includes(flag);
+
+function parseFlag(flag) {
+  const idx = cliArgs.indexOf(flag);
+  if (idx === -1 || idx + 1 >= cliArgs.length) return undefined;
+  return cliArgs[idx + 1];
+}
+
+function usageMain() {
   console.log(`
   swarmy - Distributed container management
 
   Usage:
-    swarmy manager start [--port PORT]
+    swarmy manager <command>    Manage the central server
+    swarmy worker <command>     Manage a worker node
+    swarmy --help               Show this help
+
+  Run 'swarmy manager --help' or 'swarmy worker --help' for command details.
+  `);
+  process.exit(0);
+}
+
+function usageManager() {
+  console.log(`
+  swarmy manager - Manage the central server
+
+  Commands:
+    start [--port PORT]   Start the manager (default port: 5174)
+    stop                  Stop the manager
+    restart [--port PORT] Restart the manager
+    status                Show manager status and token
+
+  Examples:
+    swarmy manager start
+    swarmy manager start --port 3000
+    swarmy manager status
+    swarmy manager stop
+  `);
+  process.exit(0);
+}
+
+function usageWorker() {
+  console.log(`
+  swarmy worker - Manage a worker node
+
+  Commands:
+    start --url URL --token TOKEN [--hostname NAME]
+                          Connect worker to a manager
+    stop                  Stop the worker
+    restart --url URL --token TOKEN [--hostname NAME]
+                          Restart the worker
+    status                Show worker status
+
+  Examples:
+    swarmy worker start --url http://192.168.1.10:5174 --token abc123
+    swarmy worker start --url http://manager:5174 --token abc123 --hostname gpu-node-01
+    swarmy worker status
+    swarmy worker stop
+  `);
+  process.exit(0);
+}
+
+// Only handle --help at top level (swarmy --help) or role level (swarmy manager --help)
+// Action-level help (swarmy manager start --help) is handled in the switch cases
+if (role === "--help" || role === "-h") usageMain();
+
+if (!role) usageMain();
+if (!action) {
+  if (role === "manager") usageManager();
+  else if (role === "worker") usageWorker();
+  else usageMain();
+}
+
+function usageManagerStart() {
+  console.log(`
+  swarmy manager start - Start the central server
+
+  Options:
+    --port PORT    HTTP port (default: 5174)
+
+  Examples:
+    swarmy manager start
+    swarmy manager start --port 3000
+  `);
+  process.exit(0);
+}
+
+function usageManagerStop() {
+  console.log(`
+  swarmy manager stop - Stop the central server
+
+  Usage:
     swarmy manager stop
-    swarmy manager restart [--port PORT]
+  `);
+  process.exit(0);
+}
+
+function usageManagerRestart() {
+  console.log(`
+  swarmy manager restart - Restart the central server
+
+  Options:
+    --port PORT    HTTP port (default: 5174)
+
+  Examples:
+    swarmy manager restart
+    swarmy manager restart --port 3000
+  `);
+  process.exit(0);
+}
+
+function usageManagerStatus() {
+  console.log(`
+  swarmy manager status - Show manager status and token
+
+  Usage:
     swarmy manager status
+  `);
+  process.exit(0);
+}
+
+function usageWorkerStart() {
+  console.log(`
+  swarmy worker start - Connect worker to a manager
+
+  Options:
+    --url URL          Manager URL (required)
+    --token TOKEN      Auth token (required)
+    --hostname NAME    Custom hostname identifier
+
+  Examples:
+    swarmy worker start --url http://192.168.1.10:5174 --token abc123
+    swarmy worker start --url http://manager:5174 --token abc123 --hostname gpu-node-01
+  `);
+  process.exit(0);
+}
 
-    swarmy worker start --url URL --token TOKEN [--hostname NAME]
+function usageWorkerStop() {
+  console.log(`
+  swarmy worker stop - Stop the worker
+
+  Usage:
     swarmy worker stop
-    swarmy worker restart --url URL --token TOKEN [--hostname NAME]
-    swarmy worker status
   `);
-  process.exit(1);
+  process.exit(0);
 }
 
-function parseFlag(flag) {
-  const idx = cliArgs.indexOf(flag);
-  if (idx === -1 || idx + 1 >= cliArgs.length) return undefined;
-  return cliArgs[idx + 1];
+function usageWorkerRestart() {
+  console.log(`
+  swarmy worker restart - Restart the worker
+
+  Options:
+    --url URL          Manager URL (required)
+    --token TOKEN      Auth token (required)
+    --hostname NAME    Custom hostname identifier
+
+  Examples:
+    swarmy worker restart --url http://192.168.1.10:5174 --token abc123
+  `);
+  process.exit(0);
 }
 
-if (!role || !action) usage();
+function usageWorkerStatus() {
+  console.log(`
+  swarmy worker status - Show worker status
+
+  Usage:
+    swarmy worker status
+  `);
+  process.exit(0);
+}
 
 function startManager() {
   const port = parseFlag("--port") ?? "5174";
@@ -189,44 +335,54 @@ function startWorker() {
 }
 
 if (role === "manager") {
+  if (action === "--help" || action === "-h") usageManager();
   switch (action) {
     case "start":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStart();
       startManager();
       break;
     case "stop":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStop();
       stopProcess("manager");
       break;
     case "restart":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerRestart();
       stopProcess("manager");
       setTimeout(startManager, 1000);
       break;
     case "status":
+      if (hasFlag("--help") || hasFlag("-h")) usageManagerStatus();
       showStatus("manager");
       if (getStatus("manager").running) {
         console.log(`Token: ${ensureToken()}`);
       }
       break;
     default:
-      usage();
+      usageManager();
   }
 } else if (role === "worker") {
+  if (action === "--help" || action === "-h") usageWorker();
   switch (action) {
     case "start":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStart();
       startWorker();
       break;
     case "stop":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStop();
       stopProcess("worker");
       break;
     case "restart":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerRestart();
       stopProcess("worker");
       setTimeout(startWorker, 1000);
       break;
     case "status":
+      if (hasFlag("--help") || hasFlag("-h")) usageWorkerStatus();
       showStatus("worker");
       break;
     default:
-      usage();
+      usageWorker();
   }
 } else {
-  usage();
+  usageMain();
 }

package/manager/src/server/auth.ts

@@ -0,0 +1,52 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import type { Request, Response, NextFunction } from "express";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOKEN_PATH = path.join(__dirname, "../../data/token");
+
+let cachedToken: string | null = null;
+
+export function getToken(): string {
+  if (cachedToken) return cachedToken;
+
+  // Allow env var override
+  if (process.env.SWARM_TOKEN) {
+    cachedToken = process.env.SWARM_TOKEN;
+    return cachedToken;
+  }
+
+  const tokenDir = path.dirname(TOKEN_PATH);
+  fs.mkdirSync(tokenDir, { recursive: true });
+
+  if (fs.existsSync(TOKEN_PATH)) {
+    cachedToken = fs.readFileSync(TOKEN_PATH, "utf-8").trim();
+  } else {
+    cachedToken = crypto.randomBytes(32).toString("hex");
+    fs.writeFileSync(TOKEN_PATH, cachedToken, { mode: 0o600 });
+  }
+
+  return cachedToken;
+}
+
+export function validateToken(token: string): boolean {
+  return token === getToken();
+}
+
+export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
+  const header = req.headers.authorization;
+  if (!header || !header.startsWith("Bearer ")) {
+    res.status(401).json({ error: "Missing or invalid Authorization header" });
+    return;
+  }
+
+  const token = header.slice(7);
+  if (!validateToken(token)) {
+    res.status(403).json({ error: "Invalid token" });
+    return;
+  }
+
+  next();
+}

package/manager/src/server/db.ts

@@ -0,0 +1,251 @@
+import Database from "better-sqlite3";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DB_PATH = path.join(__dirname, "../../data/swarm.db");
+
+let db: Database.Database;
+
+export function getDb(): Database.Database {
+  if (!db) {
+    fs.mkdirSync(path.dirname(DB_PATH), { recursive: true });
+    db = new Database(DB_PATH);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    initSchema(db);
+  }
+  return db;
+}
+
+function initSchema(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS nodes (
+      id              TEXT PRIMARY KEY,
+      hostname        TEXT,
+      ip              TEXT,
+      status          TEXT DEFAULT 'offline',
+      max_containers  INTEGER DEFAULT 5,
+      last_heartbeat  INTEGER,
+      created_at      INTEGER DEFAULT (unixepoch()),
+      updated_at      INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE TABLE IF NOT EXISTS containers (
+      id              TEXT PRIMARY KEY,
+      node_id         TEXT REFERENCES nodes(id),
+      docker_id       TEXT,
+      image           TEXT DEFAULT 'swarm-base',
+      status          TEXT DEFAULT 'running',
+      vnc_port        INTEGER,
+      max_sessions    INTEGER DEFAULT 10,
+      created_at      INTEGER DEFAULT (unixepoch()),
+      updated_at      INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id              TEXT PRIMARY KEY,
+      container_id    TEXT REFERENCES containers(id),
+      command         TEXT DEFAULT 'bash',
+      status          TEXT DEFAULT 'running',
+      exit_code       INTEGER,
+      interactive     INTEGER DEFAULT 1,
+      scrollback      TEXT DEFAULT '',
+      created_at      INTEGER DEFAULT (unixepoch()),
+      updated_at      INTEGER DEFAULT (unixepoch())
+    );
+  `);
+}
+
+// --- Node queries ---
+
+export function upsertNode(
+  id: string,
+  hostname: string,
+  ip: string,
+  maxContainers: number
+): void {
+  getDb()
+    .prepare(
+      `INSERT INTO nodes (id, hostname, ip, status, max_containers, last_heartbeat, updated_at)
+       VALUES (?, ?, ?, 'online', ?, unixepoch(), unixepoch())
+       ON CONFLICT(id) DO UPDATE SET
+         hostname = excluded.hostname,
+         ip = excluded.ip,
+         status = 'online',
+         max_containers = excluded.max_containers,
+         last_heartbeat = unixepoch(),
+         updated_at = unixepoch()`
+    )
+    .run(id, hostname, ip, maxContainers);
+}
+
+export function updateNodeHeartbeat(id: string): void {
+  getDb()
+    .prepare(
+      `UPDATE nodes SET last_heartbeat = unixepoch(), status = 'online', updated_at = unixepoch() WHERE id = ?`
+    )
+    .run(id);
+}
+
+export function markNodeStatus(id: string, status: string): void {
+  getDb()
+    .prepare(`UPDATE nodes SET status = ?, updated_at = unixepoch() WHERE id = ?`)
+    .run(status, id);
+}
+
+export function getAllNodes(): any[] {
+  return getDb().prepare(`SELECT * FROM nodes ORDER BY created_at`).all();
+}
+
+export function getNode(id: string): any {
+  return getDb().prepare(`SELECT * FROM nodes WHERE id = ?`).get(id);
+}
+
+export function getStaleNodes(thresholdSeconds: number): any[] {
+  return getDb()
+    .prepare(
+      `SELECT * FROM nodes WHERE status = 'online' AND last_heartbeat < unixepoch() - ?`
+    )
+    .all(thresholdSeconds);
+}
+
+export function markReconnectingNodes(): void {
+  getDb()
+    .prepare(
+      `UPDATE nodes SET status = 'reconnecting', updated_at = unixepoch() WHERE status = 'online'`
+    )
+    .run();
+}
+
+export function removeNode(id: string): void {
+  const containers = getContainersByNode(id);
+  for (const c of containers) {
+    getDb().prepare(`DELETE FROM sessions WHERE container_id = ?`).run(c.id);
+  }
+  getDb().prepare(`DELETE FROM containers WHERE node_id = ?`).run(id);
+  getDb().prepare(`DELETE FROM nodes WHERE id = ?`).run(id);
+}
+
+export function markStaleReconnectingOffline(thresholdSeconds: number): number {
+  return getDb()
+    .prepare(
+      `UPDATE nodes SET status = 'offline', updated_at = unixepoch()
+       WHERE status = 'reconnecting' AND updated_at < unixepoch() - ?`
+    )
+    .run(thresholdSeconds).changes;
+}
+
+// --- Container queries ---
+
+export function insertContainer(
+  id: string,
+  nodeId: string,
+  dockerId: string,
+  image: string,
+  vncPort: number
+): void {
+  getDb()
+    .prepare(
+      `INSERT INTO containers (id, node_id, docker_id, image, vnc_port) VALUES (?, ?, ?, ?, ?)`
+    )
+    .run(id, nodeId, dockerId, image, vncPort);
+}
+
+export function updateContainerDocker(id: string, dockerId: string, vncPort: number): void {
+  getDb()
+    .prepare(
+      `UPDATE containers SET docker_id = ?, vnc_port = ?, status = 'running', updated_at = unixepoch() WHERE id = ?`
+    )
+    .run(dockerId, vncPort, id);
+}
+
+export function removeContainer(id: string): void {
+  getDb().prepare(`DELETE FROM sessions WHERE container_id = ?`).run(id);
+  getDb().prepare(`DELETE FROM containers WHERE id = ?`).run(id);
+}
+
+export function getContainersByNode(nodeId: string): any[] {
+  return getDb()
+    .prepare(`SELECT * FROM containers WHERE node_id = ? ORDER BY created_at`)
+    .all(nodeId);
+}
+
+export function getContainer(id: string): any {
+  return getDb().prepare(`SELECT * FROM containers WHERE id = ?`).get(id);
+}
+
+export function countContainersByNode(nodeId: string): number {
+  const row = getDb()
+    .prepare(`SELECT COUNT(*) as count FROM containers WHERE node_id = ? AND status = 'running'`)
+    .get(nodeId) as any;
+  return row.count;
+}
+
+// --- Session queries ---
+
+export function insertSession(id: string, containerId: string, command: string): void {
+  getDb()
+    .prepare(`INSERT INTO sessions (id, container_id, command) VALUES (?, ?, ?)`)
+    .run(id, containerId, command);
+}
+
+export function markSessionExited(id: string, exitCode: number): void {
+  getDb()
+    .prepare(
+      `UPDATE sessions SET status = 'exited', exit_code = ?, updated_at = unixepoch() WHERE id = ?`
+    )
+    .run(exitCode, id);
+}
+
+export function removeSession(id: string): void {
+  getDb().prepare(`DELETE FROM sessions WHERE id = ?`).run(id);
+}
+
+export function getSessionsByContainer(containerId: string): any[] {
+  return getDb()
+    .prepare(`SELECT * FROM sessions WHERE container_id = ? ORDER BY created_at`)
+    .all(containerId);
+}
+
+export function getSession(id: string): any {
+  return getDb().prepare(`SELECT * FROM sessions WHERE id = ?`).get(id);
+}
+
+export function countSessionsByContainer(containerId: string): number {
+  const row = getDb()
+    .prepare(
+      `SELECT COUNT(*) as count FROM sessions WHERE container_id = ? AND status = 'running'`
+    )
+    .get(containerId) as any;
+  return row.count;
+}
+
+export function updateScrollback(id: string, scrollback: string): void {
+  getDb()
+    .prepare(`UPDATE sessions SET scrollback = ?, updated_at = unixepoch() WHERE id = ?`)
+    .run(scrollback, id);
+}
+
+export function updateSessionInteractive(id: string, interactive: boolean): void {
+  getDb()
+    .prepare(`UPDATE sessions SET interactive = ?, updated_at = unixepoch() WHERE id = ?`)
+    .run(interactive ? 1 : 0, id);
+}
+
+// --- Full state (for UI snapshot) ---
+
+export function getFullState(): {
+  nodes: any[];
+  containers: any[];
+  sessions: any[];
+} {
+  return {
+    nodes: getDb().prepare(`SELECT * FROM nodes ORDER BY created_at`).all(),
+    containers: getDb().prepare(`SELECT * FROM containers ORDER BY created_at`).all(),
+    sessions: getDb()
+      .prepare(`SELECT id, container_id, command, status, exit_code, interactive, created_at, updated_at FROM sessions ORDER BY created_at`)
+      .all(),
+  };
+}

package/manager/src/server/index.ts

@@ -0,0 +1,85 @@
+import express from "express";
+import { createServer } from "http";
+import { createServer as createViteServer } from "vite";
+import path from "path";
+import { fileURLToPath } from "url";
+import { authMiddleware, getToken, validateToken } from "./auth.js";
+import { ensureThumbnailDir, getThumbnailPath } from "./thumbnails.js";
+import { markReconnectingNodes, markStaleReconnectingOffline, getStaleNodes, markNodeStatus } from "./db.js";
+import { setupWorkerWs } from "./ws/worker.js";
+import { setupUiWs } from "./ws/ui.js";
+import { setupSessionWs, startScrollbackFlush } from "./ws/session.js";
+import { setupVncWs } from "./ws/vnc.js";
+import nodesRouter from "./routes/nodes.js";
+import containersRouter from "./routes/containers.js";
+import sessionsRouter from "./routes/sessions.js";
+import statusRouter from "./routes/status.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PORT = parseInt(process.env.PORT ?? "5174", 10);
+
+async function main() {
+  ensureThumbnailDir();
+  markReconnectingNodes();
+  const app = express();
+  app.use(express.json());
+
+  app.get("/api/containers/:id/thumbnail", (req, res) => {
+    const token = (req.query.token as string) ?? req.headers.authorization?.slice(7);
+    if (!token || !validateToken(token)) { res.status(403).json({ error: "Invalid token" }); return; }
+    const thumbPath = getThumbnailPath(req.params.id);
+    if (!thumbPath) { res.status(404).json({ error: "No thumbnail" }); return; }
+    res.set("Cache-Control", "no-cache");
+    res.sendFile(thumbPath);
+  });
+
+  app.use("/api/nodes", authMiddleware, nodesRouter);
+  app.use("/api/containers", authMiddleware, containersRouter);
+  app.use("/api/sessions", authMiddleware, sessionsRouter);
+  app.use("/api/status", authMiddleware, statusRouter);
+
+  const httpServer = createServer(app);
+
+  const workerWss = setupWorkerWs();
+  const uiWss = setupUiWs();
+  const sessionWss = setupSessionWs();
+  const vncWss = setupVncWs();
+  startScrollbackFlush();
+
+  httpServer.on("upgrade", (req, socket, head) => {
+    const url = new URL(req.url ?? "", `http://${req.headers.host}`);
+    const p = url.pathname;
+    if (p === "/ws/worker") {
+      workerWss.handleUpgrade(req, socket, head, (ws) => workerWss.emit("connection", ws, req));
+    } else if (p === "/ws/ui") {
+      uiWss.handleUpgrade(req, socket, head, (ws) => uiWss.emit("connection", ws, req));
+    } else if (p.startsWith("/ws/session/")) {
+      sessionWss.handleUpgrade(req, socket, head, (ws) => sessionWss.emit("connection", ws, req));
+    } else if (p.startsWith("/ws/vnc/")) {
+      vncWss.handleUpgrade(req, socket, head, (ws) => vncWss.emit("connection", ws, req));
+    }
+    // else: let Vite HMR handle its own upgrades
+  });
+
+  const vite = await createViteServer({
+    configFile: path.join(__dirname, "../../vite.config.ts"),
+    server: {
+      middlewareMode: true,
+      hmr: { server: httpServer },
+    },
+  });
+  app.use(vite.middlewares);
+
+  setInterval(() => {
+    const stale = getStaleNodes(30);
+    for (const node of stale) { markNodeStatus(node.id, "offline"); }
+    markStaleReconnectingOffline(60);
+  }, 10_000);
+
+  httpServer.listen(PORT, () => {
+    console.log(`Swarm Manager running on http://localhost:${PORT}`);
+    console.log(`Token: ${getToken()}`);
+  });
+}
+
+main().catch(console.error);