@flrande/browserctl 0.1.0-dev.7.1

package/apps/browserd/src/bootstrap.ts

@@ -0,0 +1,432 @@
+import { createContainer, loadBrowserdConfig, type BrowserdContainer } from "./container";
+import { createMcpSdkServer } from "../../../packages/transport-mcp-stdio/src";
+import { createServer, Socket } from "node:net";
+import { Readable, Writable } from "node:stream";
+
+const UNKNOWN_TRACE_ID = "trace:unknown";
+const UNKNOWN_SESSION_ID = "session:unknown";
+const INVALID_REQUEST_CODE = "E_INVALID_ARG";
+const DEFAULT_TCP_HOST = "127.0.0.1";
+const DEFAULT_TCP_PORT = 41337;
+const DEFAULT_SERVER_VERSION = "0.1.0";
+
+type StdioToolRequest = {
+  name: string;
+  arguments?: unknown;
+  traceId?: string;
+  id?: unknown;
+};
+
+type StdioTransport = {
+  input: Readable;
+  output: Writable;
+};
+
+type StdioProtocol = "mcp" | "legacy";
+
+type TcpTransport = {
+  host: string;
+  port: number;
+};
+
+type ErrorEnvelope = {
+  id?: unknown;
+  ok: false;
+  traceId: string;
+  sessionId: string;
+  error: {
+    code: string;
+    message: string;
+  };
+};
+
+type RequestMetadata = {
+  id?: unknown;
+  traceId?: string;
+  sessionId?: string;
+};
+
+class ProcessLineError extends Error {
+  readonly metadata: RequestMetadata;
+
+  constructor(message: string, metadata: RequestMetadata) {
+    super(message);
+    this.metadata = metadata;
+  }
+}
+
+function resolveNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmedValue = value.trim();
+  return trimmedValue.length === 0 ? undefined : trimmedValue;
+}
+
+function extractRequestMetadata(value: unknown): RequestMetadata {
+  if (!isObjectRecord(value)) {
+    return {};
+  }
+
+  const metadata: RequestMetadata = {};
+  if (Object.prototype.hasOwnProperty.call(value, "id")) {
+    metadata.id = value.id;
+  }
+
+  const traceId = resolveNonEmptyString(value.traceId);
+  if (traceId !== undefined) {
+    metadata.traceId = traceId;
+  }
+
+  const args = value.arguments;
+  if (isObjectRecord(args)) {
+    const sessionId = resolveNonEmptyString(args.sessionId);
+    if (sessionId !== undefined) {
+      metadata.sessionId = sessionId;
+    }
+  }
+
+  return metadata;
+}
+
+function toErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : "Unexpected request handling failure.";
+}
+
+function createInvalidRequestEnvelope(
+  message: string,
+  metadata: RequestMetadata = {}
+): ErrorEnvelope {
+  const envelope: ErrorEnvelope = {
+    ok: false,
+    traceId: metadata.traceId ?? UNKNOWN_TRACE_ID,
+    sessionId: metadata.sessionId ?? UNKNOWN_SESSION_ID,
+    error: {
+      code: INVALID_REQUEST_CODE,
+      message
+    }
+  };
+
+  if (metadata.id !== undefined) {
+    envelope.id = metadata.id;
+  }
+
+  return envelope;
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeToolRequest(value: unknown): ToolRequestParseResult {
+  if (!isObjectRecord(value)) {
+    return {
+      ok: false,
+      error: createInvalidRequestEnvelope("Request must be a JSON object.")
+    };
+  }
+
+  const metadata = extractRequestMetadata(value);
+  const { id, name, arguments: args, traceId } = value;
+  if (typeof name !== "string" || name.trim().length === 0) {
+    return {
+      ok: false,
+      error: createInvalidRequestEnvelope(
+        'Request field "name" must be a non-empty string.',
+        metadata
+      )
+    };
+  }
+
+  const request: StdioToolRequest = {
+    name: name.trim(),
+    arguments: args
+  };
+
+  if (typeof traceId === "string") {
+    request.traceId = traceId;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, "id")) {
+    request.id = id;
+  }
+
+  return {
+    ok: true,
+    request
+  };
+}
+
+type ToolRequestParseResult =
+  | {
+      ok: true;
+      request: StdioToolRequest;
+    }
+  | {
+      ok: false;
+      error: ErrorEnvelope;
+    };
+
+function writeJsonLine(output: Writable, payload: unknown): void {
+  output.write(`${JSON.stringify(payload)}\n`);
+}
+
+export type BrowserdRuntime = {
+  container: BrowserdContainer;
+  transport: "stdio" | "tcp";
+  listening?: TcpTransport;
+  mcpStdioStarted: true;
+  close(): void;
+};
+
+type LineWriter = (payload: unknown) => void;
+
+function createLineProcessor(container: BrowserdContainer, writer: LineWriter) {
+  return async (line: string): Promise<void> => {
+    const trimmedLine = line.trim();
+    if (trimmedLine.length === 0) {
+      return;
+    }
+
+    let parsedRequest: unknown;
+    try {
+      parsedRequest = JSON.parse(trimmedLine);
+    } catch {
+      writer(createInvalidRequestEnvelope("Invalid JSON request."));
+      return;
+    }
+
+    const requestMetadata = extractRequestMetadata(parsedRequest);
+    try {
+      const normalizedRequest = normalizeToolRequest(parsedRequest);
+      if (!normalizedRequest.ok) {
+        writer(normalizedRequest.error);
+        return;
+      }
+
+      const request = normalizedRequest.request;
+      const response = await container.mcpServer.callTool({
+        name: request.name,
+        arguments: request.arguments,
+        traceId: request.traceId
+      });
+
+      const payload = request.id === undefined ? response : { id: request.id, ...response };
+      writer(payload);
+    } catch (error) {
+      throw new ProcessLineError(toErrorMessage(error), requestMetadata);
+    }
+  };
+}
+
+function createLineQueue(
+  processLine: (line: string) => Promise<void>,
+  writer: LineWriter
+): (line: string) => void {
+  let processing = Promise.resolve();
+
+  return (line: string) => {
+    processing = processing
+      .then(() => processLine(line))
+      .catch((error: unknown) => {
+        if (error instanceof ProcessLineError) {
+          writer(createInvalidRequestEnvelope(error.message, error.metadata));
+          return;
+        }
+
+        writer(createInvalidRequestEnvelope(toErrorMessage(error)));
+      });
+  };
+}
+
+function attachStreamReader(
+  input: Readable,
+  onLine: (line: string) => void
+): () => void {
+  let buffer = "";
+  const onData = (chunk: string | Buffer) => {
+    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+
+    let lineBreakIndex = buffer.indexOf("\n");
+    while (lineBreakIndex >= 0) {
+      const line = buffer.slice(0, lineBreakIndex);
+      buffer = buffer.slice(lineBreakIndex + 1);
+      onLine(line);
+      lineBreakIndex = buffer.indexOf("\n");
+    }
+  };
+
+  input.setEncoding("utf8");
+  input.on("data", onData);
+  input.resume();
+  return () => {
+    input.off("data", onData);
+    input.pause();
+  };
+}
+
+function toTcpTransport(value: BootstrapBrowserdOptions): TcpTransport {
+  const env = value.env ?? process.env;
+  const envPort = toPositiveNumber(env.BROWSERD_PORT);
+  const optionPort = value.port;
+  return {
+    host: value.host ?? env.BROWSERD_HOST ?? DEFAULT_TCP_HOST,
+    port: optionPort ?? envPort ?? DEFAULT_TCP_PORT
+  };
+}
+
+function toPositiveNumber(value: string | undefined): number | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function resolveTransportMode(options: BootstrapBrowserdOptions): "stdio" | "tcp" {
+  if (options.transport !== undefined) {
+    return options.transport;
+  }
+
+  const env = options.env ?? process.env;
+  return env.BROWSERD_TRANSPORT === "tcp" ? "tcp" : "stdio";
+}
+
+export function startMcpStdioServer(
+  container: BrowserdContainer,
+  transport: StdioTransport = { input: process.stdin, output: process.stdout }
+): BrowserdRuntime {
+  const mcpSdkServer = createMcpSdkServer({
+    toolMap: container.mcpServer.toolMap,
+    serverInfo: {
+      name: "browserd",
+      version: DEFAULT_SERVER_VERSION
+    }
+  });
+
+  // MCP server startup is async but starts listening synchronously before this Promise resolves.
+  void mcpSdkServer.connectStdio(transport).catch(() => undefined);
+
+  return {
+    container,
+    transport: "stdio",
+    mcpStdioStarted: true,
+    close() {
+      void mcpSdkServer.close();
+      container.close();
+    }
+  };
+}
+
+export function startLegacyStdioServer(
+  container: BrowserdContainer,
+  transport: StdioTransport = { input: process.stdin, output: process.stdout }
+): BrowserdRuntime {
+  const writer: LineWriter = (payload) => {
+    writeJsonLine(transport.output, payload);
+  };
+  const processLine = createLineProcessor(container, writer);
+  const queueLine = createLineQueue(processLine, writer);
+  const detach = attachStreamReader(transport.input, queueLine);
+
+  return {
+    container,
+    transport: "stdio",
+    mcpStdioStarted: true,
+    close() {
+      detach();
+      container.close();
+    }
+  };
+}
+
+export function startMcpTcpServer(container: BrowserdContainer, transport: TcpTransport): BrowserdRuntime {
+  const server = createServer();
+  const sockets = new Set<Socket>();
+
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.setEncoding("utf8");
+
+    const writer: LineWriter = (payload) => {
+      socket.write(`${JSON.stringify(payload)}\n`);
+    };
+
+    const processLine = createLineProcessor(container, writer);
+    const queueLine = createLineQueue(processLine, writer);
+    const detachReader = attachStreamReader(socket, queueLine);
+
+    socket.on("close", () => {
+      detachReader();
+      sockets.delete(socket);
+    });
+
+    socket.on("error", () => {
+      detachReader();
+      sockets.delete(socket);
+    });
+  });
+
+  server.listen(transport.port, transport.host);
+
+  return {
+    container,
+    transport: "tcp",
+    listening: transport,
+    mcpStdioStarted: true,
+    close() {
+      for (const socket of sockets) {
+        socket.destroy();
+      }
+      sockets.clear();
+      server.close();
+      container.close();
+    }
+  };
+}
+
+type BootstrapBrowserdOptions = {
+  env?: Record<string, string | undefined>;
+  transport?: "stdio" | "tcp";
+  stdioProtocol?: StdioProtocol;
+  host?: string;
+  port?: number;
+  input?: Readable;
+  output?: Writable;
+};
+
+function resolveStdioProtocol(options: BootstrapBrowserdOptions): StdioProtocol {
+  if (options.stdioProtocol !== undefined) {
+    return options.stdioProtocol;
+  }
+
+  const env = options.env ?? process.env;
+  return env.BROWSERD_STDIO_PROTOCOL === "legacy" ? "legacy" : "mcp";
+}
+
+export function bootstrapBrowserd(options: BootstrapBrowserdOptions = {}): BrowserdRuntime {
+  const config = loadBrowserdConfig(options.env);
+  const container = createContainer(config);
+  const mode = resolveTransportMode(options);
+  if (mode === "tcp") {
+    if (config.authToken === undefined) {
+      container.close();
+      throw new Error(
+        "BROWSERD_AUTH_TOKEN is required when BROWSERD_TRANSPORT=tcp to prevent unauthenticated network access."
+      );
+    }
+    return startMcpTcpServer(container, toTcpTransport(options));
+  }
+
+  const stdioTransport: StdioTransport = {
+    input: options.input ?? process.stdin,
+    output: options.output ?? process.stdout
+  };
+  if (resolveStdioProtocol(options) === "legacy") {
+    return startLegacyStdioServer(container, stdioTransport);
+  }
+
+  return startMcpStdioServer(container, stdioTransport);
+}

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

@@ -0,0 +1,275 @@
+import { createServer } from "node:net";
+
+import { afterEach, describe, expect, it } from "vitest";
+import { WebSocket } from "ws";
+
+import { createChromeRelayExtensionBridge } from "./chrome-relay-extension-bridge";
+
+async function reservePort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (typeof address !== "object" || address === null) {
+        server.close(() => resolve(0));
+        return;
+      }
+
+      const port = address.port;
+      server.close((closeError) => {
+        if (closeError !== undefined) {
+          reject(closeError);
+          return;
+        }
+
+        resolve(port);
+      });
+    });
+  });
+}
+
+async function waitForCondition(predicate: () => boolean, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("Timed out waiting for condition.");
+    }
+
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, 10);
+    });
+  }
+}
+
+type Closable = {
+  close(): Promise<void> | void;
+};
+
+const closables: Closable[] = [];
+
+afterEach(async () => {
+  while (closables.length > 0) {
+    const item = closables.pop();
+    if (item === undefined) {
+      continue;
+    }
+
+    await item.close();
+  }
+});
+
+describe("createChromeRelayExtensionBridge", () => {
+  it("requires token configuration for extension bridge startup", async () => {
+    const port = await reservePort();
+
+    expect(() =>
+      createChromeRelayExtensionBridge({
+        relayUrl: `http://127.0.0.1:${port}`
+      })
+    ).toThrow("BROWSERD_CHROME_RELAY_EXTENSION_TOKEN");
+  });
+
+  it("sends requests to extension client and receives responses", async () => {
+    const port = await reservePort();
+    const bridge = createChromeRelayExtensionBridge({
+      relayUrl: `http://127.0.0.1:${port}`,
+      token: "secret-token",
+      requestTimeoutMs: 500
+    });
+    closables.push(bridge);
+
+    const socket = new WebSocket(`ws://127.0.0.1:${port}/bridge`);
+    closables.push({
+      async close() {
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          await new Promise<void>((resolve) => {
+            socket.once("close", () => resolve());
+            socket.close();
+          });
+        }
+      }
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      socket.once("open", () => {
+        socket.send(
+          JSON.stringify({
+            type: "hello",
+            role: "extension",
+            extensionId: "ext:test",
+            token: "secret-token"
+          })
+        );
+        resolve();
+      });
+      socket.once("error", reject);
+    });
+    await waitForCondition(() => bridge.isConnected());
+
+    socket.on("message", (message) => {
+      const parsed = JSON.parse(String(message)) as Record<string, unknown>;
+      if (parsed.type !== "request") {
+        return;
+      }
+
+      socket.send(
+        JSON.stringify({
+          type: "response",
+          id: parsed.id,
+          ok: true,
+          result: {
+            accepted: true,
+            method: parsed.method
+          }
+        })
+      );
+    });
+
+    await expect(bridge.invoke("tab.open", { url: "https://example.com" })).resolves.toEqual({
+      accepted: true,
+      method: "tab.open"
+    });
+    expect(bridge.isConnected()).toBe(true);
+  });
+
+  it("rejects invoke when extension is not connected", async () => {
+    const port = await reservePort();
+    const bridge = createChromeRelayExtensionBridge({
+      relayUrl: `http://127.0.0.1:${port}`,
+      token: "secret-token",
+      requestTimeoutMs: 200
+    });
+    closables.push(bridge);
+
+    await expect(bridge.invoke("tab.info", { tabId: 1 })).rejects.toThrowError(
+      "Chrome relay extension is not connected."
+    );
+  });
+
+  it("enforces token validation for extension websocket connection", async () => {
+    const port = await reservePort();
+    const bridge = createChromeRelayExtensionBridge({
+      relayUrl: `http://127.0.0.1:${port}`,
+      token: "secret-token",
+      requestTimeoutMs: 500
+    });
+    closables.push(bridge);
+
+    const socket = new WebSocket(`ws://127.0.0.1:${port}/bridge`);
+    closables.push({
+      async close() {
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          await new Promise<void>((resolve) => {
+            socket.once("close", () => resolve());
+            socket.close();
+          });
+        }
+      }
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      socket.once("open", () => {
+        socket.send(
+          JSON.stringify({
+            type: "hello",
+            role: "extension",
+            extensionId: "ext:test",
+            token: "wrong-token"
+          })
+        );
+      });
+      socket.once("close", () => resolve());
+      socket.once("error", reject);
+    });
+
+    expect(socket.readyState).not.toBe(WebSocket.OPEN);
+    expect(bridge.isConnected()).toBe(false);
+  });
+
+  it("forwards extension event envelopes to bridge listeners", async () => {
+    const port = await reservePort();
+    const bridge = createChromeRelayExtensionBridge({
+      relayUrl: `http://127.0.0.1:${port}`,
+      token: "secret-token",
+      requestTimeoutMs: 500
+    });
+    closables.push(bridge);
+
+    const socket = new WebSocket(`ws://127.0.0.1:${port}/bridge`);
+    closables.push({
+      async close() {
+        if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+          await new Promise<void>((resolve) => {
+            socket.once("close", () => resolve());
+            socket.close();
+          });
+        }
+      }
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      socket.once("open", () => {
+        socket.send(
+          JSON.stringify({
+            type: "hello",
+            role: "extension",
+            extensionId: "ext:test",
+            token: "secret-token"
+          })
+        );
+        resolve();
+      });
+      socket.once("error", reject);
+    });
+    await waitForCondition(() => bridge.isConnected());
+
+    const receivedEvents: Array<Record<string, unknown>> = [];
+    const detach = bridge.onEvent((event) => {
+      receivedEvents.push(event as unknown as Record<string, unknown>);
+    });
+    closables.push({
+      close() {
+        detach();
+      }
+    });
+
+    socket.send(
+      JSON.stringify({
+        type: "event",
+        event: {
+          kind: "console",
+          tabId: 7,
+          entry: {
+            type: "log",
+            text: "hello-event"
+          }
+        }
+      })
+    );
+
+    await new Promise<void>((resolve) => {
+      const start = Date.now();
+      const poll = () => {
+        if (receivedEvents.length >= 1 || Date.now() - start > 1000) {
+          resolve();
+          return;
+        }
+
+        setTimeout(poll, 10);
+      };
+
+      poll();
+    });
+
+    expect(receivedEvents).toHaveLength(1);
+    expect(receivedEvents[0]).toMatchObject({
+      kind: "console",
+      tabId: 7,
+      entry: {
+        type: "log",
+        text: "hello-event"
+      }
+    });
+  });
+});