Gateway: optional canvas host

2025-12-18 11:35:21 +01:00
parent cfb36525ab
commit cd729e83b6
6 changed files with 383 additions and 0 deletions
--- a/src/canvas-host/server.test.ts
+++ b/src/canvas-host/server.test.ts
@@ -0,0 +1,71 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { WebSocket } from "ws";
+import { defaultRuntime } from "../runtime.js";
+import { injectCanvasLiveReload, startCanvasHost } from "./server.js";
+
+describe("canvas host", () => {
+  it("injects live reload script", () => {
+    const out = injectCanvasLiveReload("<html><body>Hello</body></html>");
+    expect(out).toContain("/__clawdis/ws");
+    expect(out).toContain("location.reload");
+  });
+
+  it("serves HTML with injection and broadcasts reload on file changes", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "clawdis-canvas-"));
+    const index = path.join(dir, "index.html");
+    await fs.writeFile(index, "<html><body>v1</body></html>", "utf8");
+
+    const server = await startCanvasHost({
+      runtime: defaultRuntime,
+      rootDir: dir,
+      port: 0,
+      bind: "loopback",
+      allowInTests: true,
+    });
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${server.port}/`);
+      const html = await res.text();
+      expect(res.status).toBe(200);
+      expect(html).toContain("v1");
+      expect(html).toContain("/__clawdis/ws");
+
+      const ws = new WebSocket(`ws://127.0.0.1:${server.port}/__clawdis/ws`);
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("ws open timeout")),
+          2000,
+        );
+        ws.on("open", () => {
+          clearTimeout(timer);
+          resolve();
+        });
+        ws.on("error", (err) => {
+          clearTimeout(timer);
+          reject(err);
+        });
+      });
+
+      const msg = new Promise<string>((resolve, reject) => {
+        const timer = setTimeout(
+          () => reject(new Error("reload timeout")),
+          4000,
+        );
+        ws.on("message", (data) => {
+          clearTimeout(timer);
+          resolve(String(data));
+        });
+      });
+
+      await fs.writeFile(index, "<html><body>v2</body></html>", "utf8");
+      expect(await msg).toBe("reload");
+      ws.close();
+    } finally {
+      await server.close();
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  });
+});
--- a/src/canvas-host/server.ts
+++ b/src/canvas-host/server.ts
@@ -0,0 +1,247 @@
+import fs from "node:fs/promises";
+import http, { type Server } from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+import chokidar from "chokidar";
+import express from "express";
+import { type WebSocket, WebSocketServer } from "ws";
+import type { BridgeBindMode } from "../config/config.js";
+import { pickPrimaryTailnetIPv4 } from "../infra/tailnet.js";
+import { detectMime } from "../media/mime.js";
+import type { RuntimeEnv } from "../runtime.js";
+import { ensureDir, resolveUserPath } from "../utils.js";
+
+export type CanvasHostOpts = {
+  runtime: RuntimeEnv;
+  rootDir?: string;
+  port?: number;
+  bind?: BridgeBindMode;
+  allowInTests?: boolean;
+};
+
+export type CanvasHostServer = {
+  port: number;
+  rootDir: string;
+  close: () => Promise<void>;
+};
+
+const WS_PATH = "/__clawdis/ws";
+
+export function injectCanvasLiveReload(html: string): string {
+  const snippet = `
+<script>
+(() => {
+  try {
+    const proto = location.protocol === "https:" ? "wss" : "ws";
+    const ws = new WebSocket(proto + "://" + location.host + ${JSON.stringify(WS_PATH)});
+    ws.onmessage = (ev) => {
+      if (String(ev.data || "") === "reload") location.reload();
+    };
+  } catch {}
+})();
+</script>
+`.trim();
+
+  const idx = html.toLowerCase().lastIndexOf("</body>");
+  if (idx >= 0) {
+    return `${html.slice(0, idx)}\n${snippet}\n${html.slice(idx)}`;
+  }
+  return `${html}\n${snippet}\n`;
+}
+
+function normalizeUrlPath(rawPath: string): string {
+  const decoded = decodeURIComponent(rawPath || "/");
+  const normalized = path.posix.normalize(decoded);
+  return normalized.startsWith("/") ? normalized : `/${normalized}`;
+}
+
+async function resolveFilePath(rootReal: string, urlPath: string) {
+  const normalized = normalizeUrlPath(urlPath);
+  const rel = normalized.replace(/^\/+/, "");
+  if (rel.split("/").some((p) => p === "..")) return null;
+
+  let candidate = path.join(rootReal, rel);
+  if (normalized.endsWith("/")) {
+    candidate = path.join(candidate, "index.html");
+  }
+
+  try {
+    const st = await fs.stat(candidate);
+    if (st.isDirectory()) {
+      candidate = path.join(candidate, "index.html");
+    }
+  } catch {
+    // ignore
+  }
+
+  const rootPrefix = rootReal.endsWith(path.sep)
+    ? rootReal
+    : `${rootReal}${path.sep}`;
+  try {
+    const lstat = await fs.lstat(candidate);
+    if (lstat.isSymbolicLink()) return null;
+    const real = await fs.realpath(candidate);
+    if (!real.startsWith(rootPrefix)) return null;
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+function resolveBindHost(bind: BridgeBindMode | undefined): string | null {
+  const mode = bind ?? "lan";
+  if (mode === "loopback") return "127.0.0.1";
+  if (mode === "lan") return "0.0.0.0";
+  if (mode === "auto") return "0.0.0.0";
+  if (mode === "tailnet") return pickPrimaryTailnetIPv4() ?? null;
+  return "0.0.0.0";
+}
+
+function isDisabledByEnv() {
+  if (process.env.CLAWDIS_SKIP_CANVAS_HOST === "1") return true;
+  if (process.env.NODE_ENV === "test") return true;
+  if (process.env.VITEST) return true;
+  return false;
+}
+
+export async function startCanvasHost(
+  opts: CanvasHostOpts,
+): Promise<CanvasHostServer> {
+  if (isDisabledByEnv() && opts.allowInTests !== true) {
+    return { port: 0, rootDir: "", close: async () => {} };
+  }
+
+  const rootDir = resolveUserPath(
+    opts.rootDir ?? path.join(os.homedir(), "clawd", "canvas"),
+  );
+  await ensureDir(rootDir);
+  const rootReal = await fs.realpath(rootDir);
+
+  const bindHost = resolveBindHost(opts.bind);
+  if (!bindHost) {
+    throw new Error(
+      "canvasHost.bind is tailnet, but no tailnet interface was found; refusing to start canvas host",
+    );
+  }
+
+  const app = express();
+  app.disable("x-powered-by");
+
+  app.get(/.*/, async (req, res) => {
+    try {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      if (url.pathname === WS_PATH) {
+        res.status(426).send("upgrade required");
+        return;
+      }
+
+      const filePath = await resolveFilePath(rootReal, url.pathname);
+      if (!filePath) {
+        if (url.pathname === "/" || url.pathname.endsWith("/")) {
+          res
+            .status(404)
+            .type("text/html")
+            .send(
+              `<!doctype html><meta charset="utf-8" /><title>Clawdis Canvas</title><pre>Missing file.\nCreate ${rootDir}/index.html</pre>`,
+            );
+          return;
+        }
+        res.status(404).send("not found");
+        return;
+      }
+
+      const lower = filePath.toLowerCase();
+      const mime =
+        lower.endsWith(".html") || lower.endsWith(".htm")
+          ? "text/html"
+          : (detectMime({ filePath }) ?? "application/octet-stream");
+
+      res.setHeader("Cache-Control", "no-store");
+      if (mime === "text/html") {
+        const html = await fs.readFile(filePath, "utf8");
+        res.type("text/html; charset=utf-8").send(injectCanvasLiveReload(html));
+        return;
+      }
+
+      res.type(mime).send(await fs.readFile(filePath));
+    } catch (err) {
+      opts.runtime.error(`canvasHost request failed: ${String(err)}`);
+      res.status(500).send("error");
+    }
+  });
+
+  const server: Server = http.createServer(app);
+  const wss = new WebSocketServer({ server, path: WS_PATH });
+  const sockets = new Set<WebSocket>();
+  wss.on("connection", (ws) => {
+    sockets.add(ws);
+    ws.on("close", () => sockets.delete(ws));
+  });
+
+  let debounce: NodeJS.Timeout | null = null;
+  const broadcastReload = () => {
+    for (const ws of sockets) {
+      try {
+        ws.send("reload");
+      } catch {
+        // ignore
+      }
+    }
+  };
+  const scheduleReload = () => {
+    if (debounce) clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      debounce = null;
+      broadcastReload();
+    }, 75);
+    debounce.unref?.();
+  };
+
+  const watcher = chokidar.watch(rootReal, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 75, pollInterval: 10 },
+    ignored: [
+      /(^|[\\/])\../, // dotfiles
+      /(^|[\\/])node_modules([\\/]|$)/,
+    ],
+  });
+  watcher.on("all", () => scheduleReload());
+
+  const listenPort =
+    typeof opts.port === "number" && Number.isFinite(opts.port) && opts.port > 0
+      ? opts.port
+      : 0;
+  await new Promise<void>((resolve, reject) => {
+    const onError = (err: NodeJS.ErrnoException) => {
+      server.off("listening", onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(listenPort, bindHost);
+  });
+
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : 0;
+  opts.runtime.log(
+    `canvas host listening on http://${bindHost}:${boundPort} (root ${rootDir})`,
+  );
+
+  return {
+    port: boundPort,
+    rootDir,
+    close: async () => {
+      if (debounce) clearTimeout(debounce);
+      await watcher.close().catch(() => {});
+      await new Promise<void>((resolve) => wss.close(() => resolve()));
+      await new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      );
+    },
+  };
+}
--- a/src/config/config.ts
+++ b/src/config/config.ts
@@ -93,6 +93,24 @@ export type DiscoveryConfig = {
  wideArea?: WideAreaDiscoveryConfig;
 };

+export type CanvasHostConfig = {
+  enabled?: boolean;
+  /** Directory to serve (default: ~/clawd/canvas). */
+  root?: string;
+  /** HTTP port to listen on (default: 18793). */
+  port?: number;
+  /**
+   * Bind address policy for the canvas host HTTP server.
+   * - auto: listen on all interfaces (LAN + tailnet)
+   * - lan:  0.0.0.0 (reachable on local network + any forwarded interfaces)
+   * - tailnet: bind only to the Tailscale interface IP (100.64.0.0/10)
+   * - loopback: 127.0.0.1
+   *
+   * Recommended: lan (works on LAN + tailnet when present).
+   */
+  bind?: BridgeBindMode;
+};
+
 export type ClawdisConfig = {
  identity?: {
    name?: string;
@@ -139,6 +157,7 @@ export type ClawdisConfig = {
  cron?: CronConfig;
  bridge?: BridgeConfig;
  discovery?: DiscoveryConfig;
+  canvasHost?: CanvasHostConfig;
 };

 // New branding path (preferred)
@@ -295,6 +314,21 @@ const ClawdisSchema = z.object({
        .optional(),
    })
    .optional(),
+  canvasHost: z
+    .object({
+      enabled: z.boolean().optional(),
+      root: z.string().optional(),
+      port: z.number().int().positive().optional(),
+      bind: z
+        .union([
+          z.literal("auto"),
+          z.literal("lan"),
+          z.literal("tailnet"),
+          z.literal("loopback"),
+        ])
+        .optional(),
+    })
+    .optional(),
 });

 function escapeRegExp(text: string): string {
--- a/src/gateway/server.ts
+++ b/src/gateway/server.ts
@@ -18,6 +18,10 @@ import {
  startBrowserControlServerFromConfig,
  stopBrowserControlServer,
 } from "../browser/server.js";
+import {
+  type CanvasHostServer,
+  startCanvasHost,
+} from "../canvas-host/server.js";
 import { createDefaultDeps } from "../cli/deps.js";
 import { agentCommand } from "../commands/agent.js";
 import { getHealthSnapshot, type HealthSummary } from "../commands/health.js";
@@ -533,6 +537,7 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
  const httpServer: HttpServer = createHttpServer();
  let bonjourStop: (() => Promise<void>) | null = null;
  let bridge: Awaited<ReturnType<typeof startNodeBridgeServer>> | null = null;
+  let canvasHost: CanvasHostServer | null = null;
  const bridgeNodeSubscriptions = new Map<string, Set<string>>();
  const bridgeSessionSubscribers = new Map<string, Set<string>>();
  try {
@@ -587,6 +592,19 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
  const cfgAtStart = loadConfig();
  setCommandLaneConcurrency("cron", cfgAtStart.cron?.maxConcurrentRuns ?? 1);

+  if (cfgAtStart.canvasHost?.enabled === true) {
+    try {
+      canvasHost = await startCanvasHost({
+        runtime: defaultRuntime,
+        rootDir: cfgAtStart.canvasHost.root,
+        port: cfgAtStart.canvasHost.port ?? 18793,
+        bind: cfgAtStart.canvasHost.bind ?? "lan",
+      });
+    } catch (err) {
+      logWarn(`gateway: canvas host failed to start: ${String(err)}`);
+    }
+  }
+
  const cronStorePath = resolveCronStorePath(cfgAtStart.cron?.store);
  const cronLogger = getChildLogger({
    module: "cron",
@@ -1602,6 +1620,7 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
      instanceName: formatBonjourInstanceName(machineDisplayName),
      gatewayPort: port,
      bridgePort: bridge?.port,
+      canvasPort: canvasHost?.port,
      sshPort,
      tailnetDns,
    });
@@ -3575,6 +3594,13 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
          /* ignore */
        }
      }
+      if (canvasHost) {
+        try {
+          await canvasHost.close();
+        } catch {
+          /* ignore */
+        }
+      }
      if (bridge) {
        try {
          await bridge.close();
--- a/src/infra/bonjour.ts
+++ b/src/infra/bonjour.ts
@@ -12,6 +12,7 @@ export type GatewayBonjourAdvertiseOpts = {
  gatewayPort: number;
  sshPort?: number;
  bridgePort?: number;
+  canvasPort?: number;
  tailnetDns?: string;
 };

@@ -108,6 +109,9 @@ export async function startGatewayBonjourAdvertiser(
  if (typeof opts.bridgePort === "number" && opts.bridgePort > 0) {
    txtBase.bridgePort = String(opts.bridgePort);
  }
+  if (typeof opts.canvasPort === "number" && opts.canvasPort > 0) {
+    txtBase.canvasPort = String(opts.canvasPort);
+  }
  if (typeof opts.tailnetDns === "string" && opts.tailnetDns.trim()) {
    txtBase.tailnetDns = opts.tailnetDns.trim();
  }