browser-commander 0.2.0

package/src/core/network-tracker.js

@@ -0,0 +1,373 @@
+/**
+ * NetworkTracker - Track all HTTP requests and wait for network idle
+ *
+ * This module monitors all network requests on a page and provides
+ * methods to wait until all requests are complete (network idle).
+ */
+
+/**
+ * Create a NetworkTracker instance for a page
+ * @param {Object} options - Configuration options
+ * @param {Object} options.page - Playwright or Puppeteer page object
+ * @param {string} options.engine - 'playwright' or 'puppeteer'
+ * @param {Function} options.log - Logger instance
+ * @param {number} options.idleTimeout - Time to wait after last request completes (default: 500ms)
+ * @param {number} options.requestTimeout - Maximum time to wait for a single request (default: 30000ms)
+ * @returns {Object} - NetworkTracker API
+ */
+export function createNetworkTracker(options = {}) {
+  const {
+    page,
+    engine,
+    log,
+    idleTimeout = 500,
+    requestTimeout = 30000,
+  } = options;
+
+  if (!page) {
+    throw new Error('page is required in options');
+  }
+
+  // Track pending requests by URL
+  const pendingRequests = new Map();
+
+  // Track request start times for timeout detection
+  const requestStartTimes = new Map();
+
+  // Event listeners
+  const listeners = {
+    onRequestStart: [],
+    onRequestEnd: [],
+    onNetworkIdle: [],
+  };
+
+  // State
+  let isTracking = false;
+  let idleTimer = null;
+  let navigationId = 0; // Track navigation sessions
+
+  /**
+   * Get unique request key
+   */
+  function getRequestKey(request) {
+    // Use URL + method as unique key (handles redirects properly)
+    const url = typeof request.url === 'function' ? request.url() : request.url;
+    const method =
+      typeof request.method === 'function' ? request.method() : request.method;
+    return `${method}:${url}`;
+  }
+
+  /**
+   * Handle request start
+   */
+  function onRequest(request) {
+    const key = getRequestKey(request);
+    const url = typeof request.url === 'function' ? request.url() : request.url;
+
+    // Ignore data URLs and blob URLs
+    if (url.startsWith('data:') || url.startsWith('blob:')) {
+      return;
+    }
+
+    pendingRequests.set(key, request);
+    requestStartTimes.set(key, Date.now());
+
+    // Clear idle timer since we have a new request
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+
+    log.debug(
+      () =>
+        `📤 Request started: ${url.substring(0, 80)}... (pending: ${pendingRequests.size})`
+    );
+
+    // Notify listeners
+    listeners.onRequestStart.forEach((fn) =>
+      fn({ url, pendingCount: pendingRequests.size })
+    );
+  }
+
+  /**
+   * Handle request completion (success or failure)
+   */
+  function onRequestEnd(request) {
+    const key = getRequestKey(request);
+    const url = typeof request.url === 'function' ? request.url() : request.url;
+
+    if (!pendingRequests.has(key)) {
+      return; // Request was filtered out or already completed
+    }
+
+    pendingRequests.delete(key);
+    requestStartTimes.delete(key);
+
+    log.debug(
+      () =>
+        `📥 Request ended: ${url.substring(0, 80)}... (pending: ${pendingRequests.size})`
+    );
+
+    // Notify listeners
+    listeners.onRequestEnd.forEach((fn) =>
+      fn({ url, pendingCount: pendingRequests.size })
+    );
+
+    // Check if we're now idle
+    checkIdle();
+  }
+
+  /**
+   * Check if network is idle and trigger idle event
+   */
+  function checkIdle() {
+    if (pendingRequests.size === 0 && !idleTimer) {
+      // Start idle timer
+      idleTimer = setTimeout(() => {
+        if (pendingRequests.size === 0) {
+          log.debug(() => '🌐 Network idle detected');
+          listeners.onNetworkIdle.forEach((fn) => fn());
+        }
+        idleTimer = null;
+      }, idleTimeout);
+    }
+  }
+
+  /**
+   * Start tracking network requests
+   */
+  function startTracking() {
+    if (isTracking) {
+      return;
+    }
+
+    isTracking = true;
+    navigationId++;
+
+    // Clear any existing state
+    pendingRequests.clear();
+    requestStartTimes.clear();
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+
+    // Setup event listeners based on engine
+    if (engine === 'playwright') {
+      page.on('request', onRequest);
+      page.on('requestfinished', onRequestEnd);
+      page.on('requestfailed', onRequestEnd);
+    } else {
+      // Puppeteer
+      page.on('request', onRequest);
+      page.on('requestfinished', onRequestEnd);
+      page.on('requestfailed', onRequestEnd);
+    }
+
+    log.debug(() => '🔌 Network tracking started');
+  }
+
+  /**
+   * Stop tracking network requests
+   */
+  function stopTracking() {
+    if (!isTracking) {
+      return;
+    }
+
+    isTracking = false;
+
+    // Remove event listeners
+    if (engine === 'playwright') {
+      page.off('request', onRequest);
+      page.off('requestfinished', onRequestEnd);
+      page.off('requestfailed', onRequestEnd);
+    } else {
+      page.off('request', onRequest);
+      page.off('requestfinished', onRequestEnd);
+      page.off('requestfailed', onRequestEnd);
+    }
+
+    // Clear state
+    pendingRequests.clear();
+    requestStartTimes.clear();
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+
+    log.debug(() => '🔌 Network tracking stopped');
+  }
+
+  /**
+   * Wait for network to become idle
+   * @param {Object} options - Configuration options
+   * @param {number} options.timeout - Maximum time to wait (default: 30000ms)
+   * @param {number} options.idleTime - Time network must be idle (default: idleTimeout)
+   * @returns {Promise<boolean>} - True if idle, false if timeout
+   */
+  async function waitForNetworkIdle(opts = {}) {
+    const { timeout = 30000, idleTime = idleTimeout } = opts;
+
+    const startTime = Date.now();
+    const currentNavId = navigationId;
+
+    // If already idle, wait for idle time
+    if (pendingRequests.size === 0) {
+      await new Promise((r) => setTimeout(r, idleTime));
+
+      // Check if still idle and no navigation happened
+      if (pendingRequests.size === 0 && navigationId === currentNavId) {
+        return true;
+      }
+    }
+
+    return new Promise((resolve) => {
+      let resolved = false;
+      let checkTimer = null;
+      let timeoutTimer = null;
+
+      const cleanup = () => {
+        if (checkTimer) {
+          clearInterval(checkTimer);
+        }
+        if (timeoutTimer) {
+          clearTimeout(timeoutTimer);
+        }
+        resolved = true;
+      };
+
+      // Timeout handler
+      timeoutTimer = setTimeout(() => {
+        if (!resolved) {
+          cleanup();
+          log.debug(
+            () =>
+              `⚠️  Network idle timeout after ${timeout}ms (${pendingRequests.size} pending)`
+          );
+
+          // Log stuck requests
+          if (pendingRequests.size > 0) {
+            const stuckRequests = [];
+            for (const [key, req] of pendingRequests) {
+              const startTime = requestStartTimes.get(key);
+              const duration = Date.now() - startTime;
+              const url = typeof req.url === 'function' ? req.url() : req.url;
+              stuckRequests.push(
+                `  ${url.substring(0, 60)}... (${duration}ms)`
+              );
+            }
+            log.debug(() => `⚠️  Stuck requests:\n${stuckRequests.join('\n')}`);
+          }
+
+          resolve(false);
+        }
+      }, timeout);
+
+      // Check periodically for idle state
+      checkTimer = setInterval(async () => {
+        if (resolved) {
+          return;
+        }
+
+        // Check for navigation change (abort wait)
+        if (navigationId !== currentNavId) {
+          cleanup();
+          resolve(false);
+          return;
+        }
+
+        // Check for timed out requests and remove them
+        const now = Date.now();
+        for (const [key, startTime] of requestStartTimes) {
+          if (now - startTime > requestTimeout) {
+            log.debug(() => `⚠️  Request timed out, removing: ${key}`);
+            pendingRequests.delete(key);
+            requestStartTimes.delete(key);
+          }
+        }
+
+        // Check if idle
+        if (pendingRequests.size === 0) {
+          // Wait for idle time to confirm
+          await new Promise((r) => setTimeout(r, idleTime));
+
+          if (
+            !resolved &&
+            pendingRequests.size === 0 &&
+            navigationId === currentNavId
+          ) {
+            cleanup();
+            resolve(true);
+          }
+        }
+      }, 100);
+    });
+  }
+
+  /**
+   * Get current pending request count
+   */
+  function getPendingCount() {
+    return pendingRequests.size;
+  }
+
+  /**
+   * Get list of pending request URLs
+   */
+  function getPendingUrls() {
+    const urls = [];
+    for (const [key, req] of pendingRequests) {
+      const url = typeof req.url === 'function' ? req.url() : req.url;
+      urls.push(url);
+    }
+    return urls;
+  }
+
+  /**
+   * Add event listener
+   */
+  function on(event, callback) {
+    if (listeners[event]) {
+      listeners[event].push(callback);
+    }
+  }
+
+  /**
+   * Remove event listener
+   */
+  function off(event, callback) {
+    if (listeners[event]) {
+      const index = listeners[event].indexOf(callback);
+      if (index !== -1) {
+        listeners[event].splice(index, 1);
+      }
+    }
+  }
+
+  /**
+   * Reset tracking (clear all pending requests)
+   * Called on navigation to start fresh
+   */
+  function reset() {
+    navigationId++;
+    pendingRequests.clear();
+    requestStartTimes.clear();
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = null;
+    }
+    log.debug(() => '🔄 Network tracker reset');
+  }
+
+  return {
+    startTracking,
+    stopTracking,
+    waitForNetworkIdle,
+    getPendingCount,
+    getPendingUrls,
+    reset,
+    on,
+    off,
+  };
+}

package/src/core/page-session.js

@@ -0,0 +1,299 @@
+/**
+ * PageSession - Abstraction for page lifecycle management
+ *
+ * A PageSession represents a single "page context" - from when a page
+ * is loaded until navigation to a different page occurs.
+ *
+ * Key features:
+ * - Automatic cleanup when navigation occurs
+ * - Scope handlers to current page only
+ * - Provide context for automation logic
+ */
+
+/**
+ * Create a PageSession factory
+ * @param {Object} options - Configuration options
+ * @param {Object} options.navigationManager - NavigationManager instance
+ * @param {Object} options.networkTracker - NetworkTracker instance
+ * @param {Function} options.log - Logger instance
+ * @returns {Object} - PageSession factory
+ */
+export function createPageSessionFactory(options = {}) {
+  const { navigationManager, networkTracker, log } = options;
+
+  const activeSessions = new Map();
+
+  /**
+   * Create a new PageSession for the current page
+   * @param {Object} sessionOptions - Session options
+   * @param {string} sessionOptions.name - Session name for debugging
+   * @param {RegExp|Function} sessionOptions.urlPattern - URL pattern to match (optional)
+   * @returns {Object} - PageSession instance
+   */
+  function createSession(sessionOptions = {}) {
+    const { name = 'unnamed', urlPattern = null } = sessionOptions;
+
+    const sessionId = navigationManager.getSessionId();
+    const startUrl = navigationManager.getCurrentUrl();
+
+    // State
+    let isActive = true;
+    let cleanupCallbacks = [];
+    let eventListeners = [];
+
+    log.debug(
+      () =>
+        `📄 Creating page session "${name}" (id: ${sessionId}) for: ${startUrl}`
+    );
+
+    /**
+     * Check if URL matches the session pattern
+     */
+    function matchesUrl(url) {
+      if (!urlPattern) {
+        return true;
+      }
+      if (urlPattern instanceof RegExp) {
+        return urlPattern.test(url);
+      }
+      if (typeof urlPattern === 'function') {
+        return urlPattern(url);
+      }
+      return true;
+    }
+
+    /**
+     * Handle navigation - deactivate session if URL no longer matches
+     */
+    function handleUrlChange({ previousUrl, newUrl }) {
+      if (!isActive) {
+        return;
+      }
+
+      // If we have a URL pattern, check if we're still on a matching page
+      if (urlPattern && !matchesUrl(newUrl)) {
+        log.debug(
+          () => `📄 Session "${name}" ending - URL no longer matches: ${newUrl}`
+        );
+        deactivate();
+      }
+    }
+
+    /**
+     * Handle navigation start - cleanup before leaving
+     */
+    async function handleBeforeNavigate() {
+      if (!isActive) {
+        return;
+      }
+
+      log.debug(
+        () => `📄 Session "${name}" cleanup triggered (navigation starting)`
+      );
+      await runCleanup();
+      deactivate();
+    }
+
+    // Subscribe to navigation events
+    navigationManager.on('onUrlChange', handleUrlChange);
+    navigationManager.on('onBeforeNavigate', handleBeforeNavigate);
+
+    /**
+     * Run all cleanup callbacks
+     */
+    async function runCleanup() {
+      for (const callback of cleanupCallbacks) {
+        try {
+          await callback();
+        } catch (e) {
+          log.debug(() => `⚠️  Session cleanup error: ${e.message}`);
+        }
+      }
+      cleanupCallbacks = [];
+
+      // Remove all event listeners
+      for (const { target, event, handler } of eventListeners) {
+        try {
+          target.off(event, handler);
+        } catch (e) {
+          // Ignore removal errors
+        }
+      }
+      eventListeners = [];
+    }
+
+    /**
+     * Deactivate the session
+     */
+    function deactivate() {
+      if (!isActive) {
+        return;
+      }
+
+      isActive = false;
+
+      // Unsubscribe from navigation events
+      navigationManager.off('onUrlChange', handleUrlChange);
+      navigationManager.off('onBeforeNavigate', handleBeforeNavigate);
+
+      // Remove from active sessions
+      activeSessions.delete(sessionId);
+
+      log.debug(() => `📄 Session "${name}" deactivated`);
+    }
+
+    /**
+     * Register cleanup callback
+     * @param {Function} callback - Cleanup callback
+     */
+    function onCleanup(callback) {
+      if (!isActive) {
+        log.debug(
+          () => `⚠️  Cannot register cleanup on inactive session "${name}"`
+        );
+        return;
+      }
+      cleanupCallbacks.push(callback);
+    }
+
+    /**
+     * Run code only if session is still active
+     * @param {Function} fn - Async function to run
+     * @returns {Promise<any>} - Result or null if session inactive
+     */
+    async function ifActive(fn) {
+      if (!isActive) {
+        log.debug(() => `⏭️  Skipping action - session "${name}" is inactive`);
+        return null;
+      }
+      return fn();
+    }
+
+    /**
+     * Add event listener that will be cleaned up with session
+     * @param {Object} target - Event target (page, navigationManager, etc.)
+     * @param {string} event - Event name
+     * @param {Function} handler - Event handler
+     */
+    function addEventListener(target, event, handler) {
+      if (!isActive) {
+        return;
+      }
+
+      target.on(event, handler);
+      eventListeners.push({ target, event, handler });
+    }
+
+    /**
+     * Check if session is still active
+     */
+    function checkActive() {
+      return isActive;
+    }
+
+    /**
+     * Get session info
+     */
+    function getInfo() {
+      return {
+        name,
+        sessionId,
+        startUrl,
+        isActive,
+        currentUrl: navigationManager.getCurrentUrl(),
+      };
+    }
+
+    /**
+     * Wait for network idle within this session
+     */
+    async function waitForNetworkIdle(opts = {}) {
+      if (!isActive) {
+        return false;
+      }
+      if (!networkTracker) {
+        return true;
+      }
+      return networkTracker.waitForNetworkIdle(opts);
+    }
+
+    /**
+     * Wait for page to be ready within this session
+     */
+    async function waitForPageReady(opts = {}) {
+      if (!isActive) {
+        return false;
+      }
+      return navigationManager.waitForPageReady(opts);
+    }
+
+    /**
+     * Manually end the session
+     */
+    async function end() {
+      if (!isActive) {
+        return;
+      }
+
+      log.debug(() => `📄 Session "${name}" ending (manual)`);
+      await runCleanup();
+      deactivate();
+    }
+
+    const session = {
+      // State
+      get isActive() {
+        return isActive;
+      },
+      get sessionId() {
+        return sessionId;
+      },
+      get startUrl() {
+        return startUrl;
+      },
+      get currentUrl() {
+        return navigationManager.getCurrentUrl();
+      },
+
+      // Lifecycle
+      onCleanup,
+      end,
+      checkActive,
+      getInfo,
+
+      // Utilities
+      ifActive,
+      addEventListener,
+      waitForNetworkIdle,
+      waitForPageReady,
+    };
+
+    // Track active session
+    activeSessions.set(sessionId, session);
+
+    return session;
+  }
+
+  /**
+   * Get all active sessions
+   */
+  function getActiveSessions() {
+    return Array.from(activeSessions.values());
+  }
+
+  /**
+   * End all active sessions
+   */
+  async function endAllSessions() {
+    const sessions = Array.from(activeSessions.values());
+    for (const session of sessions) {
+      await session.end();
+    }
+  }
+
+  return {
+    createSession,
+    getActiveSessions,
+    endAllSessions,
+  };
+}