From cd729e83b6ed7d1878cb0008e79800356010cad2 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 18 Dec 2025 11:35:21 +0100 Subject: [PATCH] Gateway: optional canvas host --- package.json | 1 + src/canvas-host/server.test.ts | 71 ++++++++++ src/canvas-host/server.ts | 247 +++++++++++++++++++++++++++++++++ src/config/config.ts | 34 +++++ src/gateway/server.ts | 26 ++++ src/infra/bonjour.ts | 4 + 6 files changed, 383 insertions(+) create mode 100644 src/canvas-host/server.test.ts create mode 100644 src/canvas-host/server.ts diff --git a/package.json b/package.json index a12b7b627..2d10db5c3 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,7 @@ "ajv": "^8.17.1", "body-parser": "^2.2.1", "chalk": "^5.6.2", + "chokidar": "^3.6.0", "commander": "^14.0.2", "croner": "^9.1.0", "detect-libc": "^2.1.2", diff --git a/src/canvas-host/server.test.ts b/src/canvas-host/server.test.ts new file mode 100644 index 000000000..a159ca376 --- /dev/null +++ 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("Hello"); + 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, "v1", "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((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((resolve, reject) => { + const timer = setTimeout( + () => reject(new Error("reload timeout")), + 4000, + ); + ws.on("message", (data) => { + clearTimeout(timer); + resolve(String(data)); + }); + }); + + await fs.writeFile(index, "v2", "utf8"); + expect(await msg).toBe("reload"); + ws.close(); + } finally { + await server.close(); + await fs.rm(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/src/canvas-host/server.ts b/src/canvas-host/server.ts new file mode 100644 index 000000000..2a8582b16 --- /dev/null +++ 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; +}; + +const WS_PATH = "/__clawdis/ws"; + +export function injectCanvasLiveReload(html: string): string { + const snippet = ` + +`.trim(); + + const idx = html.toLowerCase().lastIndexOf(""); + 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 { + 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( + `Clawdis Canvas
Missing file.\nCreate ${rootDir}/index.html
`, + ); + 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(); + 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((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((resolve) => wss.close(() => resolve())); + await new Promise((resolve, reject) => + server.close((err) => (err ? reject(err) : resolve())), + ); + }, + }; +} diff --git a/src/config/config.ts b/src/config/config.ts index 2a65c911d..5984ca648 100644 --- 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 { diff --git a/src/gateway/server.ts b/src/gateway/server.ts index dc6384c8f..8943eeec9 100644 --- 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 { const httpServer: HttpServer = createHttpServer(); let bonjourStop: (() => Promise) | null = null; let bridge: Awaited> | null = null; + let canvasHost: CanvasHostServer | null = null; const bridgeNodeSubscriptions = new Map>(); const bridgeSessionSubscribers = new Map>(); try { @@ -587,6 +592,19 @@ export async function startGatewayServer(port = 18789): Promise { 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 { instanceName: formatBonjourInstanceName(machineDisplayName), gatewayPort: port, bridgePort: bridge?.port, + canvasPort: canvasHost?.port, sshPort, tailnetDns, }); @@ -3575,6 +3594,13 @@ export async function startGatewayServer(port = 18789): Promise { /* ignore */ } } + if (canvasHost) { + try { + await canvasHost.close(); + } catch { + /* ignore */ + } + } if (bridge) { try { await bridge.close(); diff --git a/src/infra/bonjour.ts b/src/infra/bonjour.ts index 8776aa096..7e41eeca4 100644 --- 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(); }