@flrande/browserctl 0.1.0-dev.7.1

package/apps/browserd/src/chrome-relay-extension-bridge.ts

@@ -0,0 +1,506 @@
+import { randomUUID } from "node:crypto";
+import { createServer, type Server as HttpServer } from "node:http";
+
+import { WebSocket, WebSocketServer } from "ws";
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+const BRIDGE_PATH = "/bridge";
+const JSON_VERSION_PATH = "/json/version";
+const STATUS_PATH = "/browserctl/relay/status";
+
+type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+  timer: NodeJS.Timeout;
+};
+
+export type ChromeRelayExtensionBridgeConsoleEvent = {
+  kind: "console";
+  tabId: number;
+  entry: {
+    type: string;
+    text: string;
+    location?: {
+      url?: string;
+      lineNumber?: number;
+      columnNumber?: number;
+    };
+  };
+};
+
+export type ChromeRelayExtensionBridgeNetworkEvent = {
+  kind: "response";
+  tabId: number;
+  response: {
+    requestId: string;
+    url: string;
+    status?: number;
+    method?: string;
+    resourceType?: string;
+    body?: string;
+    encoding?: "utf8" | "base64";
+  };
+};
+
+export type ChromeRelayExtensionBridgeEvent =
+  | ChromeRelayExtensionBridgeConsoleEvent
+  | ChromeRelayExtensionBridgeNetworkEvent;
+
+export type ChromeRelayExtensionBridgeConfig = {
+  relayUrl: string;
+  token?: string;
+  requestTimeoutMs?: number;
+};
+
+export type ChromeRelayExtensionBridgeStatus = {
+  connected: boolean;
+  extensionId?: string;
+  websocketUrl: string;
+  relayUrl: string;
+};
+
+export type ChromeRelayExtensionBridge = {
+  relayUrl: string;
+  websocketUrl: string;
+  isConnected(): boolean;
+  getStatus(): ChromeRelayExtensionBridgeStatus;
+  invoke(method: string, params?: Record<string, unknown>): Promise<unknown>;
+  onEvent(listener: (event: ChromeRelayExtensionBridgeEvent) => void): () => void;
+  close(): Promise<void>;
+};
+
+function resolveNonEmptyString(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length === 0 ? undefined : trimmedValue;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readObjectStringProperty(value: unknown, key: string): string | undefined {
+  if (!isObjectRecord(value)) {
+    return undefined;
+  }
+
+  const propertyValue = value[key];
+  return typeof propertyValue === "string" ? propertyValue : undefined;
+}
+
+function readObjectNumberProperty(value: unknown, key: string): number | undefined {
+  if (!isObjectRecord(value)) {
+    return undefined;
+  }
+
+  const propertyValue = value[key];
+  return typeof propertyValue === "number" ? propertyValue : undefined;
+}
+
+function parseBridgeEvent(value: unknown): ChromeRelayExtensionBridgeEvent | undefined {
+  if (!isObjectRecord(value)) {
+    return undefined;
+  }
+
+  const kind = readObjectStringProperty(value, "kind");
+  const tabId = readObjectNumberProperty(value, "tabId");
+  if (tabId === undefined || !Number.isFinite(tabId)) {
+    return undefined;
+  }
+
+  if (kind === "console") {
+    const rawEntry = isObjectRecord(value.entry) ? value.entry : undefined;
+    const type = readObjectStringProperty(rawEntry, "type") ?? "log";
+    const text = readObjectStringProperty(rawEntry, "text") ?? "";
+    const rawLocation = isObjectRecord(rawEntry?.location) ? rawEntry.location : undefined;
+    const url = readObjectStringProperty(rawLocation, "url");
+    const lineNumber = readObjectNumberProperty(rawLocation, "lineNumber");
+    const columnNumber = readObjectNumberProperty(rawLocation, "columnNumber");
+
+    return {
+      kind: "console",
+      tabId,
+      entry: {
+        type,
+        text,
+        ...((url !== undefined || lineNumber !== undefined || columnNumber !== undefined)
+          ? {
+              location: {
+                ...(url !== undefined ? { url } : {}),
+                ...(lineNumber !== undefined ? { lineNumber } : {}),
+                ...(columnNumber !== undefined ? { columnNumber } : {})
+              }
+            }
+          : {})
+      }
+    };
+  }
+
+  if (kind === "response") {
+    const rawResponse = isObjectRecord(value.response) ? value.response : undefined;
+    const requestId = readObjectStringProperty(rawResponse, "requestId");
+    const url = readObjectStringProperty(rawResponse, "url");
+    if (requestId === undefined || url === undefined) {
+      return undefined;
+    }
+
+    const status = readObjectNumberProperty(rawResponse, "status");
+    const method = readObjectStringProperty(rawResponse, "method");
+    const resourceType = readObjectStringProperty(rawResponse, "resourceType");
+    const body = readObjectStringProperty(rawResponse, "body");
+    const encodingRaw = readObjectStringProperty(rawResponse, "encoding");
+    const encoding = encodingRaw === "base64" ? "base64" : encodingRaw === "utf8" ? "utf8" : undefined;
+
+    return {
+      kind: "response",
+      tabId,
+      response: {
+        requestId,
+        url,
+        ...(status !== undefined ? { status } : {}),
+        ...(method !== undefined ? { method } : {}),
+        ...(resourceType !== undefined ? { resourceType } : {}),
+        ...(body !== undefined ? { body } : {}),
+        ...(encoding !== undefined ? { encoding } : {})
+      }
+    };
+  }
+
+  return undefined;
+}
+
+function parseRelayHttpUrl(relayUrl: string): URL {
+  const parsedRelayUrl = new URL(relayUrl);
+  if (parsedRelayUrl.protocol !== "http:") {
+    throw new Error(
+      `Chrome relay extension bridge requires http relayUrl. Received: ${relayUrl}`
+    );
+  }
+
+  return parsedRelayUrl;
+}
+
+function getRelayPort(parsedRelayUrl: URL): number {
+  if (parsedRelayUrl.port.length > 0) {
+    const parsedPort = Number.parseInt(parsedRelayUrl.port, 10);
+    if (Number.isFinite(parsedPort) && parsedPort > 0) {
+      return parsedPort;
+    }
+  }
+
+  return 80;
+}
+
+function createResponsePayload(payload: unknown): string {
+  return JSON.stringify(payload);
+}
+
+export function createChromeRelayExtensionBridge(
+  config: ChromeRelayExtensionBridgeConfig
+): ChromeRelayExtensionBridge {
+  const parsedRelayUrl = parseRelayHttpUrl(config.relayUrl);
+  const host = parsedRelayUrl.hostname;
+  const port = getRelayPort(parsedRelayUrl);
+  const expectedToken = resolveNonEmptyString(config.token);
+  if (expectedToken === undefined) {
+    throw new Error(
+      "BROWSERD_CHROME_RELAY_EXTENSION_TOKEN is required for chrome-relay extension bridge."
+    );
+  }
+
+  const requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const pendingRequests = new Map<string, PendingRequest>();
+  const eventListeners = new Set<(event: ChromeRelayExtensionBridgeEvent) => void>();
+  let extensionSocket: WebSocket | undefined;
+  let extensionId: string | undefined;
+  let extensionAuthenticated = false;
+
+  const websocketUrlBase = `ws://${host}:${port}${BRIDGE_PATH}`;
+  const websocketUrl = websocketUrlBase;
+
+  const httpServer: HttpServer = createServer((request, response) => {
+    const requestUrl = request.url ?? "/";
+    const parsedPath = requestUrl.split("?")[0];
+
+    if (parsedPath === JSON_VERSION_PATH) {
+      response.statusCode = 200;
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(
+        createResponsePayload({
+          Browser: "browserctl-extension-relay",
+          webSocketDebuggerUrl: websocketUrlBase
+        })
+      );
+      return;
+    }
+
+    if (parsedPath === STATUS_PATH) {
+      response.statusCode = 200;
+      response.setHeader("content-type", "application/json; charset=utf-8");
+      response.end(
+        createResponsePayload({
+          connected:
+            extensionSocket !== undefined && extensionSocket.readyState === WebSocket.OPEN,
+          extensionId,
+          relayUrl: config.relayUrl,
+          websocketUrl: websocketUrlBase
+        })
+      );
+      return;
+    }
+
+    response.statusCode = 404;
+    response.end();
+  });
+
+  const wsServer = new WebSocketServer({
+    noServer: true
+  });
+
+  function rejectPendingRequests(reason: string): void {
+    for (const [requestId, pending] of pendingRequests.entries()) {
+      pendingRequests.delete(requestId);
+      clearTimeout(pending.timer);
+      pending.reject(new Error(reason));
+    }
+  }
+
+  function clearExtensionConnection(reason: string): void {
+    extensionSocket = undefined;
+    extensionId = undefined;
+    extensionAuthenticated = false;
+    rejectPendingRequests(reason);
+  }
+
+  wsServer.on("connection", (socket) => {
+    if (extensionSocket !== undefined && extensionSocket.readyState === WebSocket.OPEN) {
+      extensionSocket.close(1000, "Superseded by a newer extension connection.");
+    }
+
+    extensionSocket = socket;
+    extensionId = undefined;
+    extensionAuthenticated = false;
+
+    const authDeadlineMs = Math.max(200, Math.min(requestTimeoutMs, 5_000));
+    const authTimer = setTimeout(() => {
+      if (socket.readyState === WebSocket.OPEN && !extensionAuthenticated) {
+        socket.close(1008, "Missing authentication token");
+      }
+    }, authDeadlineMs);
+
+    const clearAuthTimer = () => {
+      clearTimeout(authTimer);
+    };
+
+    socket.on("message", (message) => {
+      let parsedMessage: unknown;
+      try {
+        parsedMessage = JSON.parse(String(message));
+      } catch {
+        return;
+      }
+
+      if (!isObjectRecord(parsedMessage)) {
+        return;
+      }
+
+      if (parsedMessage.type === "hello") {
+        const providedToken = resolveNonEmptyString(parsedMessage.token as string | undefined);
+        if (providedToken !== expectedToken) {
+          socket.close(1008, "Invalid token");
+          return;
+        }
+
+        clearAuthTimer();
+        extensionAuthenticated = true;
+        extensionId = resolveNonEmptyString(parsedMessage.extensionId as string | undefined);
+        return;
+      }
+
+      if (!extensionAuthenticated) {
+        return;
+      }
+
+      if (parsedMessage.type === "event") {
+        const event = parseBridgeEvent(parsedMessage.event);
+        if (event === undefined) {
+          return;
+        }
+
+        for (const listener of eventListeners) {
+          listener(event);
+        }
+        return;
+      }
+
+      if (parsedMessage.type !== "response") {
+        return;
+      }
+
+      const requestId = resolveNonEmptyString(parsedMessage.id as string | undefined);
+      if (requestId === undefined) {
+        return;
+      }
+
+      const pending = pendingRequests.get(requestId);
+      if (pending === undefined) {
+        return;
+      }
+
+      pendingRequests.delete(requestId);
+      clearTimeout(pending.timer);
+      if (parsedMessage.ok === true) {
+        pending.resolve(parsedMessage.result);
+        return;
+      }
+
+      const errorMessage = resolveNonEmptyString(
+        isObjectRecord(parsedMessage.error) ? (parsedMessage.error.message as string | undefined) : undefined
+      );
+      pending.reject(new Error(errorMessage ?? "Extension relay request failed."));
+    });
+
+    socket.on("close", () => {
+      clearAuthTimer();
+      if (extensionSocket === socket) {
+        clearExtensionConnection("Extension websocket disconnected.");
+      }
+    });
+
+    socket.on("error", () => {
+      clearAuthTimer();
+      if (extensionSocket === socket) {
+        clearExtensionConnection("Extension websocket encountered an error.");
+      }
+    });
+  });
+
+  httpServer.on("upgrade", (request, socket, head) => {
+    const requestUrl = new URL(request.url ?? BRIDGE_PATH, parsedRelayUrl);
+    if (requestUrl.pathname !== BRIDGE_PATH) {
+      socket.destroy();
+      return;
+    }
+
+    wsServer.handleUpgrade(request, socket, head, (upgradedSocket) => {
+      wsServer.emit("connection", upgradedSocket, request);
+    });
+  });
+
+  httpServer.listen(port, host);
+
+  return {
+    relayUrl: config.relayUrl,
+    websocketUrl,
+    isConnected: () =>
+      extensionSocket !== undefined &&
+      extensionSocket.readyState === WebSocket.OPEN &&
+      extensionAuthenticated,
+    getStatus: () => ({
+      connected:
+        extensionSocket !== undefined &&
+        extensionSocket.readyState === WebSocket.OPEN &&
+        extensionAuthenticated,
+      extensionId,
+      websocketUrl: websocketUrlBase,
+      relayUrl: config.relayUrl
+    }),
+    invoke: async (method, params) => {
+      if (
+        extensionSocket === undefined ||
+        extensionSocket.readyState !== WebSocket.OPEN ||
+        !extensionAuthenticated
+      ) {
+        throw new Error("Chrome relay extension is not connected.");
+      }
+
+      const requestId = `request:extension:${randomUUID()}`;
+      const response = await new Promise<unknown>((resolvePromise, rejectPromise) => {
+        const timer = setTimeout(() => {
+          pendingRequests.delete(requestId);
+          rejectPromise(
+            new Error(
+              `Timed out waiting for extension response after ${requestTimeoutMs}ms (${method}).`
+            )
+          );
+        }, requestTimeoutMs);
+
+        pendingRequests.set(requestId, {
+          resolve: resolvePromise,
+          reject: rejectPromise,
+          timer
+        });
+
+        try {
+          extensionSocket.send(
+            JSON.stringify({
+              type: "request",
+              id: requestId,
+              method,
+              params
+            }),
+            (error) => {
+              if (error === undefined || error === null) {
+                return;
+              }
+
+              const pending = pendingRequests.get(requestId);
+              if (pending === undefined) {
+                return;
+              }
+
+              pendingRequests.delete(requestId);
+              clearTimeout(pending.timer);
+              rejectPromise(error);
+            }
+          );
+        } catch (error) {
+          const pending = pendingRequests.get(requestId);
+          if (pending !== undefined) {
+            pendingRequests.delete(requestId);
+            clearTimeout(pending.timer);
+          }
+          rejectPromise(error);
+        }
+      });
+
+      return response;
+    },
+    onEvent: (listener) => {
+      eventListeners.add(listener);
+      return () => {
+        eventListeners.delete(listener);
+      };
+    },
+    close: async () => {
+      rejectPendingRequests("Extension bridge closed.");
+      eventListeners.clear();
+      if (extensionSocket !== undefined) {
+        try {
+          extensionSocket.close(1000, "Bridge shutdown");
+        } catch {
+          // Ignore websocket close errors during shutdown.
+        }
+      }
+      extensionSocket = undefined;
+      extensionId = undefined;
+
+      await new Promise<void>((resolve) => {
+        wsServer.close(() => {
+          resolve();
+        });
+      });
+
+      if (httpServer.listening) {
+        await new Promise<void>((resolve) => {
+          httpServer.close(() => {
+            resolve();
+          });
+        });
+      }
+    }
+  };
+}