yuanyeex
/
openclaw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Gateway: optional canvas host

main
Peter Steinberger 2025-12-18 11:35:21 +01:00
parent cfb36525ab
commit cd729e83b6
6 changed files with 383 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
package.json
View File

@ -46,6 +46,7 @@
"ajv": "^8.17.1", "ajv": "^8.17.1",
"body-parser": "^2.2.1", "body-parser": "^2.2.1",
"chalk": "^5.6.2", "chalk": "^5.6.2",
"chokidar": "^3.6.0",
"commander": "^14.0.2", "commander": "^14.0.2",
"croner": "^9.1.0", "croner": "^9.1.0",
"detect-libc": "^2.1.2", "detect-libc": "^2.1.2",

71
src/canvas-host/server.test.ts Normal file
View File

@ -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 });
}
});
});

247
src/canvas-host/server.ts Normal file
View File

@ -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())),
);
},
};
}

34
src/config/config.ts
View File

@ -93,6 +93,24 @@ export type DiscoveryConfig = {
wideArea?: WideAreaDiscoveryConfig; 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 = { export type ClawdisConfig = {
identity?: { identity?: {
name?: string; name?: string;
@ -139,6 +157,7 @@ export type ClawdisConfig = {
cron?: CronConfig; cron?: CronConfig;
bridge?: BridgeConfig; bridge?: BridgeConfig;
discovery?: DiscoveryConfig; discovery?: DiscoveryConfig;
canvasHost?: CanvasHostConfig;
}; };
// New branding path (preferred) // New branding path (preferred)
@ -295,6 +314,21 @@ const ClawdisSchema = z.object({
.optional(), .optional(),
}) })
.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 { function escapeRegExp(text: string): string {

26
src/gateway/server.ts
View File

@ -18,6 +18,10 @@ import {
startBrowserControlServerFromConfig, startBrowserControlServerFromConfig,
stopBrowserControlServer, stopBrowserControlServer,
} from "../browser/server.js"; } from "../browser/server.js";
import {
type CanvasHostServer,
startCanvasHost,
} from "../canvas-host/server.js";
import { createDefaultDeps } from "../cli/deps.js"; import { createDefaultDeps } from "../cli/deps.js";
import { agentCommand } from "../commands/agent.js"; import { agentCommand } from "../commands/agent.js";
import { getHealthSnapshot, type HealthSummary } from "../commands/health.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(); const httpServer: HttpServer = createHttpServer();
let bonjourStop: (() => Promise<void>) | null = null; let bonjourStop: (() => Promise<void>) | null = null;
let bridge: Awaited<ReturnType<typeof startNodeBridgeServer>> | null = null; let bridge: Awaited<ReturnType<typeof startNodeBridgeServer>> | null = null;
let canvasHost: CanvasHostServer | null = null;
const bridgeNodeSubscriptions = new Map<string, Set<string>>(); const bridgeNodeSubscriptions = new Map<string, Set<string>>();
const bridgeSessionSubscribers = new Map<string, Set<string>>(); const bridgeSessionSubscribers = new Map<string, Set<string>>();
try { try {
@ -587,6 +592,19 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
const cfgAtStart = loadConfig(); const cfgAtStart = loadConfig();
setCommandLaneConcurrency("cron", cfgAtStart.cron?.maxConcurrentRuns ?? 1); 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 cronStorePath = resolveCronStorePath(cfgAtStart.cron?.store);
const cronLogger = getChildLogger({ const cronLogger = getChildLogger({
module: "cron", module: "cron",
@ -1602,6 +1620,7 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
instanceName: formatBonjourInstanceName(machineDisplayName), instanceName: formatBonjourInstanceName(machineDisplayName),
gatewayPort: port, gatewayPort: port,
bridgePort: bridge?.port, bridgePort: bridge?.port,
canvasPort: canvasHost?.port,
sshPort, sshPort,
tailnetDns, tailnetDns,
}); });
@ -3575,6 +3594,13 @@ export async function startGatewayServer(port = 18789): Promise<GatewayServer> {
/* ignore */ /* ignore */
} }
} }
if (canvasHost) {
try {
await canvasHost.close();
} catch {
/* ignore */
}
}
if (bridge) { if (bridge) {
try { try {
await bridge.close(); await bridge.close();

4
src/infra/bonjour.ts
View File

@ -12,6 +12,7 @@ export type GatewayBonjourAdvertiseOpts = {
gatewayPort: number; gatewayPort: number;
sshPort?: number; sshPort?: number;
bridgePort?: number; bridgePort?: number;
canvasPort?: number;
tailnetDns?: string; tailnetDns?: string;
}; };
@ -108,6 +109,9 @@ export async function startGatewayBonjourAdvertiser(
if (typeof opts.bridgePort === "number" && opts.bridgePort > 0) { if (typeof opts.bridgePort === "number" && opts.bridgePort > 0) {
txtBase.bridgePort = String(opts.bridgePort); 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()) { if (typeof opts.tailnetDns === "string" && opts.tailnetDns.trim()) {
txtBase.tailnetDns = opts.tailnetDns.trim(); txtBase.tailnetDns = opts.tailnetDns.trim();
} }