@ulpi/browse 0.1.0

package/src/server.ts

@@ -0,0 +1,325 @@
+/**
+ * browse server — persistent Chromium daemon
+ *
+ * Architecture:
+ *   Bun.serve HTTP on localhost → routes commands to Playwright
+ *   Session multiplexing: multiple agents share one Chromium via X-Browse-Session header
+ *   Console/network buffers: per-session in-memory + disk flush every 1s
+ *   Chromium crash → server EXITS with clear error (CLI auto-restarts)
+ *   Auto-shutdown when all sessions idle past BROWSE_IDLE_TIMEOUT (default 30 min)
+ */
+
+import { chromium, type Browser } from 'playwright';
+import { SessionManager, type Session } from './session-manager';
+import { handleReadCommand } from './commands/read';
+import { handleWriteCommand } from './commands/write';
+import { handleMetaCommand } from './commands/meta';
+import { DEFAULTS } from './constants';
+import { type LogEntry, type NetworkEntry } from './buffers';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+// Re-export types for backward compatibility
+export { type LogEntry, type NetworkEntry };
+
+// ─── Auth (inline) ─────────────────────────────────────────────
+const AUTH_TOKEN = crypto.randomUUID();
+const BROWSE_PORT = parseInt(process.env.BROWSE_PORT || '0', 10); // 0 = auto-scan
+const INSTANCE_SUFFIX = BROWSE_PORT ? `-${BROWSE_PORT}` : '';
+const LOCAL_DIR = process.env.BROWSE_LOCAL_DIR || '/tmp';
+const STATE_FILE = process.env.BROWSE_STATE_FILE || `${LOCAL_DIR}/browse-server${INSTANCE_SUFFIX}.json`;
+const IDLE_TIMEOUT_MS = parseInt(process.env.BROWSE_IDLE_TIMEOUT || String(DEFAULTS.IDLE_TIMEOUT_MS), 10);
+
+function validateAuth(req: Request): boolean {
+  const header = req.headers.get('authorization');
+  return header === `Bearer ${AUTH_TOKEN}`;
+}
+
+// ─── Per-Session Buffer Flush ──────────────────────────────────
+// Flushes each session's buffers to separate log files on disk.
+
+function flushAllBuffers(sessionManager: SessionManager, final = false) {
+  for (const session of sessionManager.getAllSessions()) {
+    flushSessionBuffers(session, final);
+  }
+}
+
+function flushSessionBuffers(session: Session, final: boolean) {
+  const suffix = session.id === 'default' ? INSTANCE_SUFFIX : `-${session.id}`;
+  const consolePath = `${LOCAL_DIR}/browse-console${suffix}.log`;
+  const networkPath = `${LOCAL_DIR}/browse-network${suffix}.log`;
+  const buffers = session.buffers;
+
+  // Console flush
+  const newConsoleCount = buffers.consoleTotalAdded - buffers.lastConsoleFlushed;
+  if (newConsoleCount > 0) {
+    const count = Math.min(newConsoleCount, buffers.consoleBuffer.length);
+    const newEntries = buffers.consoleBuffer.slice(-count);
+    const lines = newEntries.map(e =>
+      `[${new Date(e.timestamp).toISOString()}] [${e.level}] ${e.text}`
+    ).join('\n') + '\n';
+    fs.appendFileSync(consolePath, lines);
+    buffers.lastConsoleFlushed = buffers.consoleTotalAdded;
+  }
+
+  // Network flush
+  let newNetworkCount = buffers.networkTotalAdded - buffers.lastNetworkFlushed;
+  if (newNetworkCount > 0) {
+    if (newNetworkCount > buffers.networkBuffer.length) {
+      buffers.lastNetworkFlushed = buffers.networkTotalAdded - buffers.networkBuffer.length;
+      newNetworkCount = buffers.networkBuffer.length;
+    }
+    const newEntries = buffers.networkBuffer.slice(-newNetworkCount);
+    const now = Date.now();
+
+    let prefixLen = 0;
+    for (let i = 0; i < newEntries.length; i++) {
+      const e = newEntries[i];
+      if (final || e.status !== undefined || (now - e.timestamp > DEFAULTS.NETWORK_SETTLE_MS)) {
+        prefixLen = i + 1;
+      } else {
+        break;
+      }
+    }
+
+    if (prefixLen > 0) {
+      const prefix = newEntries.slice(0, prefixLen);
+      const lines = prefix.map(e =>
+        `[${new Date(e.timestamp).toISOString()}] ${e.method} ${e.url} → ${e.status || 'pending'} (${e.duration || '?'}ms, ${e.size || '?'}B)`
+      ).join('\n') + '\n';
+      fs.appendFileSync(networkPath, lines);
+      buffers.lastNetworkFlushed += prefixLen;
+    }
+  }
+}
+
+// ─── Server ────────────────────────────────────────────────────
+let sessionManager: SessionManager;
+let browser: Browser;
+let isShuttingDown = false;
+
+// Read/write/meta command sets for routing
+const READ_COMMANDS = new Set([
+  'text', 'html', 'links', 'forms', 'accessibility',
+  'js', 'eval', 'css', 'attrs', 'state', 'dialog',
+  'console', 'network', 'cookies', 'storage', 'perf', 'devices',
+]);
+
+const WRITE_COMMANDS = new Set([
+  'goto', 'back', 'forward', 'reload',
+  'click', 'fill', 'select', 'hover', 'type', 'press', 'scroll', 'wait',
+  'viewport', 'cookie', 'header', 'useragent',
+  'upload', 'dialog-accept', 'dialog-dismiss', 'emulate',
+]);
+
+const META_COMMANDS = new Set([
+  'tabs', 'tab', 'newtab', 'closetab',
+  'status', 'stop', 'restart',
+  'screenshot', 'pdf', 'responsive',
+  'chain', 'diff',
+  'url', 'snapshot', 'snapshot-diff',
+  'sessions', 'session-close',
+]);
+
+// Find port: use BROWSE_PORT or scan range
+async function findPort(): Promise<number> {
+  if (BROWSE_PORT) {
+    try {
+      const testServer = Bun.serve({ port: BROWSE_PORT, fetch: () => new Response('ok') });
+      testServer.stop();
+      return BROWSE_PORT;
+    } catch {
+      throw new Error(`[browse] Port ${BROWSE_PORT} is in use`);
+    }
+  }
+
+  // Scan range
+  const start = parseInt(process.env.BROWSE_PORT_START || String(DEFAULTS.PORT_RANGE_START), 10);
+  const end = start + (DEFAULTS.PORT_RANGE_END - DEFAULTS.PORT_RANGE_START);
+  for (let port = start; port <= end; port++) {
+    try {
+      const testServer = Bun.serve({ port, fetch: () => new Response('ok') });
+      testServer.stop();
+      return port;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`[browse] No available port in range ${start}-${end}`);
+}
+
+async function handleCommand(body: any, session: Session): Promise<Response> {
+  const { command, args = [] } = body;
+
+  if (!command) {
+    return new Response(JSON.stringify({ error: 'Missing "command" field' }), {
+      status: 400,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  try {
+    let result: string;
+
+    if (READ_COMMANDS.has(command)) {
+      result = await handleReadCommand(command, args, session.manager, session.buffers);
+    } else if (WRITE_COMMANDS.has(command)) {
+      result = await handleWriteCommand(command, args, session.manager);
+    } else if (META_COMMANDS.has(command)) {
+      result = await handleMetaCommand(command, args, session.manager, shutdown, sessionManager, session);
+    } else {
+      return new Response(JSON.stringify({
+        error: `Unknown command: ${command}`,
+        hint: `Available commands: ${[...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS].sort().join(', ')}`,
+      }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+
+    return new Response(result, {
+      status: 200,
+      headers: { 'Content-Type': 'text/plain' },
+    });
+  } catch (err: any) {
+    return new Response(JSON.stringify({ error: err.message }), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+}
+
+async function shutdown() {
+  if (isShuttingDown) return;
+  isShuttingDown = true;
+
+  console.log('[browse] Shutting down...');
+  clearInterval(flushInterval);
+  clearInterval(sessionCleanupInterval);
+  flushAllBuffers(sessionManager, true);
+
+  await sessionManager.closeAll();
+
+  // Close the shared browser
+  if (browser) {
+    browser.removeAllListeners('disconnected');
+    await browser.close().catch(() => {});
+  }
+
+  // Only remove state file if it still belongs to this server instance.
+  try {
+    const currentState = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+    if (currentState.pid === process.pid || currentState.token === AUTH_TOKEN) {
+      fs.unlinkSync(STATE_FILE);
+    }
+  } catch {}
+
+  process.exit(0);
+}
+
+// Handle signals
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+
+// ─── Flush Timer ────────────────────────────────────────────────
+const flushInterval = setInterval(() => {
+  if (sessionManager) flushAllBuffers(sessionManager);
+}, DEFAULTS.BUFFER_FLUSH_INTERVAL_MS);
+
+// ─── Session Idle Cleanup ───────────────────────────────────────
+const sessionCleanupInterval = setInterval(async () => {
+  if (!sessionManager || isShuttingDown) return;
+
+  const closed = await sessionManager.closeIdleSessions(IDLE_TIMEOUT_MS);
+  for (const id of closed) {
+    console.log(`[browse] Session "${id}" idle for ${IDLE_TIMEOUT_MS / 1000}s — closed`);
+  }
+
+  if (sessionManager.getSessionCount() === 0) {
+    console.log('[browse] All sessions idle — shutting down');
+    shutdown();
+  }
+}, 60_000);
+
+// ─── Start ─────────────────────────────────────────────────────
+async function start() {
+  const port = await findPort();
+
+  // Launch shared Chromium
+  browser = await chromium.launch({ headless: true });
+
+  // Chromium crash → flush, cleanup, exit
+  browser.on('disconnected', () => {
+    console.error('[browse] FATAL: Chromium process crashed or was killed. Server exiting.');
+    if (sessionManager) flushAllBuffers(sessionManager, true);
+    try {
+      const currentState = JSON.parse(fs.readFileSync(STATE_FILE, 'utf-8'));
+      if (currentState.pid === process.pid || currentState.token === AUTH_TOKEN) {
+        fs.unlinkSync(STATE_FILE);
+      }
+    } catch {}
+    process.exit(1);
+  });
+
+  // Create session manager
+  sessionManager = new SessionManager(browser);
+
+  const startTime = Date.now();
+  const server = Bun.serve({
+    port,
+    hostname: '127.0.0.1',
+    fetch: async (req) => {
+      const url = new URL(req.url);
+
+      // Health check — no auth required
+      if (url.pathname === '/health') {
+        const healthy = browser.isConnected();
+        return new Response(JSON.stringify({
+          status: healthy ? 'healthy' : 'unhealthy',
+          uptime: Math.floor((Date.now() - startTime) / 1000),
+          sessions: sessionManager.getSessionCount(),
+        }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      // All other endpoints require auth
+      if (!validateAuth(req)) {
+        return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+
+      if (url.pathname === '/command' && req.method === 'POST') {
+        const body = await req.json();
+        const sessionId = req.headers.get('x-browse-session') || 'default';
+        const session = await sessionManager.getOrCreate(sessionId);
+        return handleCommand(body, session);
+      }
+
+      return new Response('Not found', { status: 404 });
+    },
+  });
+
+  // Write state file
+  const state = {
+    pid: process.pid,
+    port,
+    token: AUTH_TOKEN,
+    startedAt: new Date().toISOString(),
+    serverPath: path.resolve(import.meta.dir, 'server.ts'),
+  };
+  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), { mode: 0o600 });
+
+  console.log(`[browse] Server running on http://127.0.0.1:${port} (PID: ${process.pid})`);
+  console.log(`[browse] State file: ${STATE_FILE}`);
+  console.log(`[browse] Idle timeout: ${IDLE_TIMEOUT_MS / 1000}s`);
+}
+
+start().catch((err) => {
+  console.error(`[browse] Failed to start: ${err.message}`);
+  process.exit(1);
+});

package/src/session-manager.ts

@@ -0,0 +1,121 @@
+/**
+ * Session manager — multiplexes multiple agents on a single Chromium instance
+ *
+ * Each session gets its own BrowserManager (tabs, refs, cookies, storage)
+ * backed by an isolated BrowserContext on the shared Browser.
+ * Sessions are identified by string IDs (from X-Browse-Session header).
+ */
+
+import type { Browser } from 'playwright';
+import { BrowserManager } from './browser-manager';
+import { SessionBuffers } from './buffers';
+
+export interface Session {
+  id: string;
+  manager: BrowserManager;
+  buffers: SessionBuffers;
+  lastActivity: number;
+  createdAt: number;
+}
+
+export class SessionManager {
+  private sessions = new Map<string, Session>();
+  private browser: Browser;
+
+  constructor(browser: Browser) {
+    this.browser = browser;
+  }
+
+  /**
+   * Get an existing session or create a new one.
+   * Creating a session launches a new BrowserContext on the shared Chromium.
+   */
+  async getOrCreate(sessionId: string): Promise<Session> {
+    let session = this.sessions.get(sessionId);
+    if (session) {
+      session.lastActivity = Date.now();
+      return session;
+    }
+
+    const buffers = new SessionBuffers();
+    const manager = new BrowserManager(buffers);
+    await manager.launchWithBrowser(this.browser);
+
+    session = {
+      id: sessionId,
+      manager,
+      buffers,
+      lastActivity: Date.now(),
+      createdAt: Date.now(),
+    };
+    this.sessions.set(sessionId, session);
+    console.log(`[browse] Session "${sessionId}" created`);
+    return session;
+  }
+
+  /**
+   * Close and remove a specific session.
+   */
+  async closeSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error(`Session "${sessionId}" not found`);
+
+    await session.manager.close();
+    this.sessions.delete(sessionId);
+    console.log(`[browse] Session "${sessionId}" closed`);
+  }
+
+  /**
+   * Close sessions idle longer than maxIdleMs.
+   * Returns list of closed session IDs.
+   */
+  async closeIdleSessions(maxIdleMs: number): Promise<string[]> {
+    const now = Date.now();
+    const closed: string[] = [];
+
+    for (const [id, session] of this.sessions) {
+      if (now - session.lastActivity > maxIdleMs) {
+        await session.manager.close().catch(() => {});
+        this.sessions.delete(id);
+        closed.push(id);
+      }
+    }
+
+    return closed;
+  }
+
+  /**
+   * List all active sessions (for status/sessions commands).
+   */
+  listSessions(): Array<{ id: string; tabs: number; url: string; idleSeconds: number; active: boolean }> {
+    const now = Date.now();
+    return [...this.sessions.entries()].map(([id, session]) => ({
+      id,
+      tabs: session.manager.getTabCount(),
+      url: session.manager.getCurrentUrl(),
+      idleSeconds: Math.floor((now - session.lastActivity) / 1000),
+      active: true,
+    }));
+  }
+
+  /**
+   * Get all sessions (for buffer flush iteration).
+   */
+  getAllSessions(): Session[] {
+    return [...this.sessions.values()];
+  }
+
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Close all sessions (for server shutdown).
+   */
+  async closeAll(): Promise<void> {
+    for (const [id, session] of this.sessions) {
+      await session.manager.close().catch(() => {});
+    }
+    this.sessions.clear();
+  }
+}