@phi-code-admin/camofox-browser 1.0.0

package/lib/request-utils.js

@@ -0,0 +1,59 @@
+// HTTP request classification helpers -- kept separate from metrics.js
+// Separated from server.js to keep HTTP method classification in its own module.
+
+/**
+ * Derive a short action name from an Express request for metrics labeling.
+ */
+export function actionFromReq(req) {
+  const method = req.method;
+  const path = req.route?.path || req.path;
+  if (path === '/tabs' && method === 'POST') return 'create_tab';
+  if (path === '/tabs/:tabId' && method === 'DELETE') return 'delete_tab';
+  if (path === '/tabs/group/:listItemId' && method === 'DELETE') return 'delete_tab_group';
+  if (path === '/sessions/:userId' && method === 'DELETE') return 'delete_session';
+  if (path === '/sessions/:userId/cookies' && method === 'POST') return 'set_cookies';
+  if (path === '/tabs/open' && method === 'POST') return 'open_url';
+  if (path === '/tabs' && method === 'GET') return 'list_tabs';
+  // /tabs/:tabId/<action>
+  const m = path.match(/^\/tabs\/:tabId\/(\w+)$/);
+  if (m) return m[1]; // navigate, snapshot, click, type, scroll, etc.
+  // legacy compat routes
+  if (['/start', '/stop', '/navigate', '/snapshot', '/act'].includes(path)) return path.slice(1);
+  if (path === '/youtube/transcript') return 'youtube_transcript';
+  if (path === '/health') return 'health';
+  if (path === '/metrics') return 'metrics';
+  return `${method.toLowerCase()}_${path.replace(/[/:]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')}`;
+}
+
+/**
+ * Classify an error into a failure type string for metrics labeling.
+ */
+export function classifyError(err) {
+  if (!err) return 'unknown';
+  const msg = err.message || '';
+
+  if (err.code === 'stale_refs' || err.name === 'StaleRefsError') return 'stale_refs';
+  if (msg === 'Tab lock queue timeout') return 'tab_lock_timeout';
+  if (msg === 'Tab destroyed') return 'tab_destroyed';
+  if (msg.includes('Target page, context or browser has been closed') ||
+      msg.includes('browser has been closed') ||
+      msg.includes('Context closed') ||
+      msg.includes('Browser closed')) return 'dead_context';
+  if (msg.includes('timed out after') ||
+      (msg.includes('Timeout') && msg.includes('exceeded'))) return 'timeout';
+  if (msg.includes('Maximum concurrent sessions')) return 'session_limit';
+  if (msg.includes('Maximum tabs per session') || msg.includes('Maximum global tabs')) return 'tab_limit';
+  if (msg.includes('concurrency limit reached')) return 'concurrency_limit';
+  if (msg.includes('NS_ERROR_PROXY') || msg.includes('proxy connection') ||
+      msg.includes('Proxy connection')) return 'proxy';
+  if (msg.includes('Browser launch timeout') || msg.includes('Failed to launch')) return 'browser_launch';
+  if (msg.includes('intercepts pointer events')) return 'click_intercepted';
+  if (msg.includes('not visible') || msg.includes('not an <input>')) return 'element_error';
+  if (msg.includes('Blocked URL scheme') || msg.includes('Invalid URL')) return 'invalid_url';
+  if (msg.includes('net::') || msg.includes('ERR_NAME') || msg.includes('ERR_CONNECTION')) return 'network';
+  if (msg.includes('Navigation aborted: tab deleted')) return 'tab_destroyed';
+  if (msg.includes('NS_ERROR_ABORT')) return 'nav_aborted';
+  if (msg.includes('Page crashed')) return 'page_crashed';
+  if (msg.includes('Navigation failed') || msg.includes('ERR_ABORTED')) return 'nav_aborted';
+  return 'unknown';
+}

package/lib/resources.js

@@ -0,0 +1,76 @@
+// lib/resources.js -- Process resource metrics and proxy error classification.
+// Isolated from reporter.js so that fs reads and network sends are never
+// in the same file (keeps fs reads and network sends in separate modules).
+
+import fs from 'fs';
+
+// ============================================================================
+// Process resource snapshot (memory, handles, FDs, browser RSS)
+// ============================================================================
+
+/**
+ * Collect process-level resource metrics. Safe to call at any time.
+ * Returns anonymized metrics -- no PIDs, paths, or user data.
+ */
+export function collectResourceSnapshot(opts = {}) {
+  const mem = process.memoryUsage();
+  const snap = {
+    nodeRssMb: Math.round(mem.rss / 1048576),
+    nodeHeapUsedMb: Math.round(mem.heapUsed / 1048576),
+    nodeHeapTotalMb: Math.round(mem.heapTotal / 1048576),
+    nodeExternalMb: Math.round(mem.external / 1048576),
+    eventLoopLagMs: null,
+    activeHandles: null,
+    activeRequests: null,
+    openFds: null,
+    browserRssMb: null,
+  };
+
+  // Active libuv handles/requests (private API, guarded)
+  try { snap.activeHandles = process._getActiveHandles().length; } catch { /* unavailable */ }
+  try { snap.activeRequests = process._getActiveRequests().length; } catch { /* unavailable */ }
+
+  // Open file descriptors (Linux only)
+  try {
+    if (process.platform === 'linux') {
+      snap.openFds = fs.readdirSync('/proc/self/fd').length;
+    }
+  } catch { /* not available or permission denied */ }
+
+  // Browser process RSS (the one people miss -- browser OOMs, not Node)
+  if (opts.browserPid && Number.isInteger(opts.browserPid) && opts.browserPid > 0) {
+    try {
+      if (process.platform === 'linux') {
+        const status = fs.readFileSync(`/proc/${opts.browserPid}/status`, 'utf8');
+        const match = status.match(/VmRSS:\s+(\d+)\s+kB/);
+        if (match) snap.browserRssMb = Math.round(parseInt(match[1], 10) / 1024);
+      }
+    } catch { /* process gone or permission denied */ }
+  }
+
+  // Session/tab counts from caller
+  if (opts.sessionCount != null) snap.browserContexts = opts.sessionCount;
+  if (opts.tabCount != null) snap.activeTabs = opts.tabCount;
+
+  return snap;
+}
+
+// ============================================================================
+// Proxy error classification
+// ============================================================================
+
+/**
+ * Classify proxy errors from Playwright navigation error messages.
+ * Returns { proxyError: string|null, proxyTlsError: bool } -- no IPs or credentials.
+ */
+export function classifyProxyError(errorMessage) {
+  if (!errorMessage || typeof errorMessage !== 'string') return { proxyError: null, proxyTlsError: false };
+  const msg = errorMessage.toUpperCase();
+  if (msg.includes('ERR_PROXY_CONNECTION_FAILED')) return { proxyError: 'ERR_PROXY_CONNECTION_FAILED', proxyTlsError: false };
+  if (msg.includes('ERR_TUNNEL_CONNECTION_FAILED')) return { proxyError: 'ERR_TUNNEL_CONNECTION_FAILED', proxyTlsError: false };
+  if (msg.includes('ERR_PROXY_AUTH_REQUESTED') || msg.includes('407')) return { proxyError: 'ERR_PROXY_AUTH_REQUESTED', proxyTlsError: false };
+  if (msg.includes('ERR_PROXY_CERTIFICATE_INVALID') || (msg.includes('PROXY') && msg.includes('SSL'))) return { proxyError: 'ERR_PROXY_TLS', proxyTlsError: true };
+  if (msg.includes('ECONNREFUSED') && msg.includes('PROXY')) return { proxyError: 'ECONNREFUSED', proxyTlsError: false };
+  if (msg.includes('ETIMEDOUT') && msg.includes('PROXY')) return { proxyError: 'ETIMEDOUT', proxyTlsError: false };
+  return { proxyError: null, proxyTlsError: false };
+}

package/lib/snapshot.js

@@ -0,0 +1,41 @@
+/**
+ * Snapshot windowing -- truncate large accessibility snapshots while
+ * preserving pagination/navigation links at the tail.
+ */
+
+const MAX_SNAPSHOT_CHARS = 80000;  // ~20K tokens
+const SNAPSHOT_TAIL_CHARS = 5000;  // keep last ~5K for pagination/nav links
+
+/**
+ * Return a window of the snapshot YAML.
+ *  offset=0 (default): head chunk + tail (pagination/nav).
+ *  offset=N: chars N..N+budget from the full snapshot.
+ *  Always appends pagination tail so nav refs are available in every chunk.
+ */
+function windowSnapshot(yaml, offset = 0) {
+  if (!yaml) return { text: '', truncated: false, totalChars: 0, offset: 0 };
+  const total = yaml.length;
+  if (total <= MAX_SNAPSHOT_CHARS) return { text: yaml, truncated: false, totalChars: total, offset: 0 };
+
+  const contentBudget = MAX_SNAPSHOT_CHARS - SNAPSHOT_TAIL_CHARS - 200; // room for marker
+  const tail = yaml.slice(-SNAPSHOT_TAIL_CHARS);
+  const clampedOffset = Math.min(Math.max(0, offset), total - SNAPSHOT_TAIL_CHARS);
+  const chunk = yaml.slice(clampedOffset, clampedOffset + contentBudget);
+  const chunkEnd = clampedOffset + contentBudget;
+  const hasMore = chunkEnd < total - SNAPSHOT_TAIL_CHARS;
+
+  const marker = hasMore
+    ? `\n[... truncated at char ${chunkEnd} of ${total}. Call snapshot with offset=${chunkEnd} to see more. Pagination links below. ...]\n`
+    : '\n';
+
+  return {
+    text: chunk + marker + tail,
+    truncated: true,
+    totalChars: total,
+    offset: clampedOffset,
+    hasMore,
+    nextOffset: hasMore ? chunkEnd : null
+  };
+}
+
+export { windowSnapshot, MAX_SNAPSHOT_CHARS, SNAPSHOT_TAIL_CHARS };

package/lib/tmp-cleanup.js

@@ -0,0 +1,108 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+const ORPHAN_PATTERNS = [
+  /^\.fea5[a-f0-9]+\.so$/,
+  /^\.5ef7[a-f0-9]+\.node$/,
+];
+
+// Firefox temp profile directories created by Playwright/Camoufox
+const FIREFOX_PROFILE_PATTERN = /^playwright_firefoxdev_profile-/;
+// Camoufox also creates these
+const CAMOUFOX_TMP_PATTERN = /^camoufox[-_]/;
+
+export function cleanupOrphanedTempFiles({ tmpDir, minAgeMs = 5 * 60 * 1000, now = Date.now() } = {}) {
+  const result = { scanned: 0, removed: 0, bytes: 0, skipped: 0 };
+  if (!tmpDir) return result;
+
+  let entries;
+  try {
+    entries = fs.readdirSync(tmpDir);
+  } catch {
+    return result;
+  }
+
+  for (const name of entries) {
+    if (!ORPHAN_PATTERNS.some((re) => re.test(name))) continue;
+    result.scanned++;
+    const full = path.join(tmpDir, name);
+    try {
+      const st = fs.statSync(full);
+      if (!st.isFile()) continue;
+      if (now - st.mtimeMs < minAgeMs) {
+        result.skipped++;
+        continue;
+      }
+      fs.unlinkSync(full);
+      result.removed++;
+      result.bytes += st.size;
+    } catch {
+      // file vanished, permission denied, or race with another process - skip silently
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Clean up stale Firefox/Camoufox temp profile directories.
+ * These accumulate when browser.close() doesn't fully clean up
+ * (especially with enable_cache: true). Each profile can be 10-100MB+.
+ *
+ * Only removes profiles older than minAgeMs (default 2 minutes)
+ * to avoid killing profiles belonging to an actively launching browser.
+ */
+export function cleanupStaleFirefoxProfiles({ tmpDir, minAgeMs = 2 * 60 * 1000, now = Date.now() } = {}) {
+  const dir = tmpDir || os.tmpdir();
+  const result = { scanned: 0, removed: 0, bytes: 0, skipped: 0 };
+
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return result;
+  }
+
+  for (const name of entries) {
+    if (!FIREFOX_PROFILE_PATTERN.test(name) && !CAMOUFOX_TMP_PATTERN.test(name)) continue;
+    result.scanned++;
+    const full = path.join(dir, name);
+    try {
+      const st = fs.statSync(full);
+      if (!st.isDirectory()) continue;
+      if (now - st.mtimeMs < minAgeMs) {
+        result.skipped++;
+        continue;
+      }
+      // Calculate directory size before removing
+      const dirBytes = _dirSizeSync(full);
+      fs.rmSync(full, { recursive: true, force: true, maxRetries: 3 });
+      result.removed++;
+      result.bytes += dirBytes;
+    } catch {
+      // directory vanished, permission denied, or in-use -- skip
+    }
+  }
+
+  return result;
+}
+
+/** Recursively calculate directory size (best effort, fast). */
+function _dirSizeSync(dirPath) {
+  let total = 0;
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(dirPath, entry.name);
+      try {
+        if (entry.isDirectory()) {
+          total += _dirSizeSync(full);
+        } else {
+          total += fs.statSync(full).size;
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+  return total;
+}

package/lib/tracing.js

@@ -0,0 +1,137 @@
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+function hashUserId(userId) {
+  return crypto.createHash('sha256').update(String(userId)).digest('hex').slice(0, 16);
+}
+
+export function userTracesDir(baseDir, userId) {
+  return path.join(baseDir, hashUserId(userId));
+}
+
+export function ensureTracesDir(baseDir, userId) {
+  const dir = userTracesDir(baseDir, userId);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function makeTraceFilename() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const suffix = crypto.randomBytes(3).toString('hex');
+  return `trace-${ts}-${suffix}.zip`;
+}
+
+export function tracePathFor(baseDir, userId, filename) {
+  return path.join(ensureTracesDir(baseDir, userId), filename);
+}
+
+export function resolveTracePath(baseDir, userId, filename) {
+  if (!filename || filename.includes('/') || filename.includes('\\') || filename.includes('..') || filename.startsWith('.')) {
+    return null;
+  }
+  const userDir = userTracesDir(baseDir, userId);
+  const full = path.join(userDir, filename);
+  const resolved = path.resolve(full);
+  if (!resolved.startsWith(path.resolve(userDir) + path.sep)) return null;
+  return resolved;
+}
+
+export async function listUserTraces(baseDir, userId) {
+  const dir = userTracesDir(baseDir, userId);
+  let names;
+  try {
+    names = await fsp.readdir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith('.zip')) continue;
+    const full = path.join(dir, name);
+    try {
+      const st = await fsp.stat(full);
+      if (!st.isFile()) continue;
+      out.push({
+        filename: name,
+        sizeBytes: st.size,
+        createdAt: st.birthtimeMs || st.ctimeMs,
+        modifiedAt: st.mtimeMs,
+      });
+    } catch {
+      // vanished mid-scan
+    }
+  }
+  out.sort((a, b) => b.modifiedAt - a.modifiedAt);
+  return out;
+}
+
+export async function statTrace(fullPath) {
+  try {
+    const st = await fsp.stat(fullPath);
+    if (!st.isFile()) return null;
+    return st;
+  } catch {
+    return null;
+  }
+}
+
+export async function deleteTrace(fullPath) {
+  await fsp.unlink(fullPath);
+}
+
+export function sweepOldTraces({ baseDir, ttlMs, maxBytesPerFile, now = Date.now() } = {}) {
+  const result = { scanned: 0, removedTtl: 0, removedOversized: 0, bytes: 0 };
+  if (!baseDir) return result;
+
+  let userDirs;
+  try {
+    userDirs = fs.readdirSync(baseDir);
+  } catch {
+    return result;
+  }
+
+  for (const userDir of userDirs) {
+    const dir = path.join(baseDir, userDir);
+    let st;
+    try {
+      st = fs.statSync(dir);
+    } catch {
+      continue;
+    }
+    if (!st.isDirectory()) continue;
+
+    let files;
+    try {
+      files = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+
+    for (const name of files) {
+      if (!name.endsWith('.zip')) continue;
+      result.scanned++;
+      const full = path.join(dir, name);
+      try {
+        const fst = fs.statSync(full);
+        if (!fst.isFile()) continue;
+        const tooOld = ttlMs && (now - fst.mtimeMs) > ttlMs;
+        const tooBig = maxBytesPerFile && fst.size > maxBytesPerFile;
+        if (tooOld) {
+          fs.unlinkSync(full);
+          result.removedTtl++;
+          result.bytes += fst.size;
+        } else if (tooBig) {
+          fs.unlinkSync(full);
+          result.removedOversized++;
+          result.bytes += fst.size;
+        }
+      } catch {
+        // vanished or permission denied
+      }
+    }
+  }
+
+  return result;
+}