feat: move remote desktop (RDP/VNC/Telnet) into a first-party plugin

Relocates guacamole backend/frontend source and tests into
plugins/remote-desktop, following the ssh-terminal/docker pattern.

plugins/remote-desktop/backend/guacamole-server.ts

@@ -0,0 +1,289 @@
+import GuacamoleLite from "guacamole-lite";
+import { guacLogger } from "../../../src/backend/utils/logger.js";
+import {
+  GuacamoleTokenService,
+  type GuacamoleRecordingMetadata,
+} from "./token-service.js";
+import {
+  createCurrentSessionRecordingRepository,
+  getCurrentSettingValue,
+} from "../../../src/backend/database/repositories/factory.js";
+import { resolveGuacdOptions } from "../../../src/backend/utils/guacd-config.js";
+import fs from "fs";
+import path from "path";
+
+const tokenService = GuacamoleTokenService.getInstance();
+
+function readGuacdOptions(): { host: string; port: number } {
+  let dbUrl: string | undefined;
+  try {
+    dbUrl = getCurrentSettingValue("guac_url") ?? undefined;
+  } catch {
+    // DB not available yet, use env var defaults
+  }
+  return resolveGuacdOptions(dbUrl);
+}
+
+export const GUAC_WS_PORT = 30008;
+const DATA_DIR = process.env.DATA_DIR || "./db/data";
+const GUACAMOLE_RECORDINGS_DIR =
+  process.env.GUACD_RECORDING_BACKEND_PATH ||
+  path.join(DATA_DIR, "session_recordings", "guacamole");
+
+type GuacamoleClientConnection = {
+  guacamoleConnectionId?: string;
+  connectionSettings?: {
+    connection?: { type?: string; join?: string; readOnly?: boolean };
+    recording?: GuacamoleRecordingMetadata;
+    termixMeta?: {
+      termixConnectId: string;
+      hostId: number;
+      ownerUserId: string;
+      protocol: string;
+    };
+  };
+};
+
+export interface GuacSessionInfo {
+  guacamoleConnectionId: string;
+  hostId: number;
+  ownerUserId: string;
+  protocol: string;
+  openedAt: number;
+}
+
+// Keyed by termixConnectId (routes.ts's correlation id), populated once the
+// primary connection's guacd handshake completes.
+const guacSessionByConnectId = new Map<string, GuacSessionInfo>();
+// Keyed by guacd's own guacamoleConnectionId, for join-time lookups.
+const guacSessionByGuacamoleId = new Map<string, GuacSessionInfo>();
+export function getGuacSessionByConnectId(
+  connectId: string,
+  userId: string,
+): GuacSessionInfo | null {
+  const info = guacSessionByConnectId.get(connectId);
+  return info?.ownerUserId === userId ? info : null;
+}
+
+export function getGuacSessionInfo(
+  guacamoleConnectionId: string,
+): GuacSessionInfo | null {
+  return guacSessionByGuacamoleId.get(guacamoleConnectionId) ?? null;
+}
+
+async function persistGuacamoleRecording(
+  clientConnection: GuacamoleClientConnection,
+): Promise<void> {
+  const recording = clientConnection.connectionSettings?.recording;
+  if (!recording) return;
+
+  const resolvedPath = path.resolve(GUACAMOLE_RECORDINGS_DIR, recording.path);
+  const allowedBase = `${path.resolve(GUACAMOLE_RECORDINGS_DIR)}${path.sep}`;
+  if (!resolvedPath.startsWith(allowedBase)) return;
+
+  // guacd may flush/rename the recording just after the websocket closes.
+  for (
+    let attempt = 0;
+    attempt < 10 && !fs.existsSync(resolvedPath);
+    attempt++
+  ) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  if (!fs.existsSync(resolvedPath)) {
+    const guacdPath = recording.guacdPath ?? GUACAMOLE_RECORDINGS_DIR;
+    guacLogger.warn("Guacamole recording file was not found", {
+      operation: "guac_recording_missing",
+      hostId: recording.hostId,
+      path: resolvedPath,
+      guacdPath,
+      hint:
+        "guacd writes the recording to guacdPath, the backend reads it from path. " +
+        "When guacd runs in its own container these must be the same volume — set " +
+        "GUACD_RECORDING_PATH to guacd's mount point and GUACD_RECORDING_BACKEND_PATH to this one.",
+    });
+    return;
+  }
+
+  const endedAt = new Date();
+  const startedAt = new Date(recording.startedAt);
+  await createCurrentSessionRecordingRepository().create({
+    hostId: recording.hostId,
+    userId: recording.userId,
+    startedAt: startedAt.toISOString(),
+    endedAt: endedAt.toISOString(),
+    duration: Math.max(
+      0,
+      Math.floor((endedAt.getTime() - startedAt.getTime()) / 1000),
+    ),
+    recordingPath: resolvedPath,
+    protocol: recording.protocol,
+    format: "guacamole",
+  });
+}
+
+const websocketOptions = {
+  host: "127.0.0.1",
+  port: GUAC_WS_PORT,
+};
+
+const clientOptions = {
+  crypt: {
+    cypher: "AES-256-CBC",
+    key: tokenService.getEncryptionKey(),
+  },
+  log: {
+    level: "ERRORS",
+    stdLog: (...args: unknown[]) => {
+      guacLogger.info(args.join(" "));
+    },
+    errorLog: (...args: unknown[]) => {
+      guacLogger.error(args.join(" "));
+    },
+  },
+  allowedUnencryptedConnectionSettings: {
+    rdp: ["width", "height", "dpi"],
+    vnc: ["width", "height"],
+    telnet: ["width", "height"],
+  },
+  connectionDefaultSettings: {
+    rdp: {
+      security: "any",
+      "ignore-cert": true,
+      "enable-wallpaper": false,
+      "enable-font-smoothing": true,
+      "enable-desktop-composition": false,
+      "disable-audio": false,
+      "enable-drive": false,
+      "resize-method": "display-update",
+      width: 1280,
+      height: 720,
+      dpi: 96,
+      audio: ["audio/L16"],
+    },
+    vnc: {
+      "swap-red-blue": false,
+      cursor: "remote",
+      width: 1280,
+      height: 720,
+      // macOS Screen Sharing negotiates its VNC security type over several
+      // round trips (RFB type 30 -> 33/36/2/35) and can fail the first
+      // attempt; retrying lets guacd's VNC client re-establish instead of
+      // guacd giving up immediately (Support#1063).
+      autoretry: 2,
+    },
+    telnet: {
+      "terminal-type": "xterm-256color",
+    },
+  },
+};
+
+const _origConsoleLog = console.log;
+console.log = (...args: unknown[]) => {
+  const msg = args[0];
+  if (typeof msg === "string" && msg.startsWith("New client connection"))
+    return;
+  _origConsoleLog(...args);
+};
+
+function createGuacServer(): GuacamoleLite {
+  const guacdOptions = readGuacdOptions();
+  const server = new GuacamoleLite(
+    websocketOptions,
+    guacdOptions,
+    clientOptions,
+  );
+
+  server.on("open", (clientConnection: GuacamoleClientConnection) => {
+    guacLogger.info("Guacamole connection opened", {
+      operation: "guac_connection_open",
+      type: clientConnection.connectionSettings?.connection?.type,
+    });
+
+    const termixMeta = clientConnection.connectionSettings?.termixMeta;
+    const guacamoleConnectionId = clientConnection.guacamoleConnectionId;
+    const isJoin = !!clientConnection.connectionSettings?.connection?.join;
+
+    if (!isJoin && termixMeta && guacamoleConnectionId) {
+      const info: GuacSessionInfo = {
+        guacamoleConnectionId,
+        hostId: termixMeta.hostId,
+        ownerUserId: termixMeta.ownerUserId,
+        protocol: termixMeta.protocol,
+        openedAt: Date.now(),
+      };
+      guacSessionByConnectId.set(termixMeta.termixConnectId, info);
+      guacSessionByGuacamoleId.set(guacamoleConnectionId, info);
+    }
+  });
+
+  server.on("close", (clientConnection: GuacamoleClientConnection) => {
+    guacLogger.info("Guacamole connection closed", {
+      operation: "guac_connection_close",
+      type: clientConnection.connectionSettings?.connection?.type,
+    });
+
+    const isJoin = !!clientConnection.connectionSettings?.connection?.join;
+    const termixMeta = clientConnection.connectionSettings?.termixMeta;
+    const guacamoleConnectionId = clientConnection.guacamoleConnectionId;
+    if (!isJoin && termixMeta && guacamoleConnectionId) {
+      guacSessionByConnectId.delete(termixMeta.termixConnectId);
+      guacSessionByGuacamoleId.delete(guacamoleConnectionId);
+    }
+
+    persistGuacamoleRecording(clientConnection).catch((error) => {
+      guacLogger.error("Failed to persist Guacamole recording", error, {
+        operation: "guac_recording_persist_error",
+      });
+    });
+  });
+
+  server.on(
+    "error",
+    (clientConnection: GuacamoleClientConnection, error: Error) => {
+      guacLogger.error("Guacamole connection error", error, {
+        operation: "guac_connection_error",
+        type: clientConnection.connectionSettings?.connection?.type,
+      });
+    },
+  );
+
+  return server;
+}
+
+let guacServer: GuacamoleLite | null = null;
+
+/**
+ * Starts the guacamole-lite WebSocket server. Called from this plugin's
+ * activate() -- see plugins/remote-desktop/backend/index.mjs.
+ */
+export async function startGuacamoleService(): Promise<void> {
+  guacServer = createGuacServer();
+}
+
+/**
+ * Stops the guacamole-lite WebSocket server. Called from this plugin's
+ * deactivate().
+ */
+export async function stopGuacamoleService(): Promise<void> {
+  if (!guacServer) return;
+  try {
+    guacServer.close();
+  } catch (err) {
+    guacLogger.error("Error closing guac server during shutdown", err as Error);
+  }
+  guacServer = null;
+}
+
+export async function restartGuacServer(): Promise<void> {
+  // A no-op while the plugin is disabled: creating a new server here would
+  // silently resurrect the WS server behind deactivate()'s back.
+  if (!guacServer) return;
+  try {
+    guacServer.close();
+  } catch (err) {
+    guacLogger.error("Error closing guac server during restart", err as Error);
+  }
+  guacServer = createGuacServer();
+}
+
+export { guacServer, tokenService };