Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

13.1 KB
Raw Blame
package bridge

import (
	"context"
	"errors"
	"fmt"
	"log/slog"
	"sync"
	"time"

	cdp "github.com/chromedp/cdproto/cdp"
	"github.com/chromedp/cdproto/page"
	"github.com/chromedp/cdproto/target"
	"github.com/chromedp/chromedp"
	"github.com/pinchtab/pinchtab/internal/config"
	"github.com/pinchtab/pinchtab/internal/ids"
)

const (
	// tabCreateTimeout bounds the CDP target creation for a new tab. Creating a
	// target is near-instant on a healthy browser, so a long stall means the
	// browser is unhealthy (e.g. resource exhaustion) — fail fast instead of
	// waiting tens of seconds.
	tabCreateTimeout = 10 * time.Second
	// tabCreateNavTimeout bounds the initial load of a freshly created tab. Kept
	// well below the full navigate timeout so a wedged renderer (e.g. after an
	// out-of-memory event) surfaces quickly rather than hanging ~60s.
	tabCreateNavTimeout = 20 * time.Second
)

type TabSetupFunc func(ctx context.Context, tabID string) error

type TabManager struct {
	browserCtx        context.Context
	config            *config.RuntimeConfig
	idMgr             *ids.Manager
	tabs              map[string]*TabEntry
	accessed          map[string]bool
	snapshots         map[string]*RefCache
	frameScope        map[string]FrameScope
	onTabSetup        TabSetupFunc
	onAfterClose      func() // optional: invoked after any successful CloseTab
	dialogMgr         *DialogManager
	logStore          *ConsoleLogStore
	routeMgr          *RouteManager
	onTabRemovedHooks []func(tabID string)
	netMonitor        *NetworkMonitor
	currentTab        string // ID of the most recently used tab
	lastStaleSweep    time.Time
	executor          *TabExecutor
	guardOnce         sync.Once
	guardActive       bool
	mu                sync.RWMutex
	freezeVeto        func(tabID string) bool
	setFrozen         func(ctx context.Context, frozen bool) error

	// pendingClicks tracks in-flight click actions that may open a popup.
	// Keyed by the opener tab's raw CDP target ID. Read by the popup guard
	// to decide whether to suppress closing the newly created tab.
	pendingClicks map[target.ID]*pendingClickSlot
}

func NewTabManager(browserCtx context.Context, cfg *config.RuntimeConfig, idMgr *ids.Manager, logStore *ConsoleLogStore, onTabSetup TabSetupFunc) *TabManager {
	if idMgr == nil {
		idMgr = ids.NewManager()
	}
	maxParallel := 0
	if cfg != nil {
		maxParallel = cfg.MaxParallelTabs
	}
	return &TabManager{
		browserCtx: browserCtx,
		config:     cfg,
		idMgr:      idMgr,
		tabs:       make(map[string]*TabEntry),
		accessed:   make(map[string]bool),
		snapshots:  make(map[string]*RefCache),
		frameScope: make(map[string]FrameScope),
		onTabSetup: onTabSetup,
		logStore:   logStore,
		executor:   NewTabExecutor(maxParallel),
		setFrozen:  setTabFrozen,
	}
}

func (tm *TabManager) SetDialogManager(dm *DialogManager) {
	tm.dialogMgr = dm
}

// SetOnAfterClose registers a callback fired whenever a tracked tab is removed
// from the manager — manual /close, eviction, auto-close lifecycle timer, or
// Chrome reporting the target gone (e.g. user closing it in a headed window).
// Used by the parent Bridge to persist session state immediately rather than
// waiting for graceful shutdown.
func (tm *TabManager) SetOnAfterClose(fn func()) {
	tm.onAfterClose = fn
}

func (tm *TabManager) SetNetworkMonitor(nm *NetworkMonitor) {
	tm.netMonitor = nm
}

// SetRouteManager registers the per-bridge RouteManager so the cleanup path
// can drop a tab's interception state when the tab closes (mirrors the
// network-monitor / log-store / executor cleanup hooks in tab_cleanup.go).
func (tm *TabManager) SetRouteManager(rm *RouteManager) {
	tm.routeMgr = rm
}

// AddTabRemovedHook registers a per-tab cleanup callback fired alongside the
// route/log/executor cleanup whenever a tracked tab is removed. Multiple hooks
// may be registered; each must be best-effort and must not panic.
func (tm *TabManager) AddTabRemovedHook(fn func(tabID string)) {
	if fn == nil {
		return
	}
	tm.mu.Lock()
	tm.onTabRemovedHooks = append(tm.onTabRemovedHooks, fn)
	tm.mu.Unlock()
}

// browserExecutorContext returns a context bound to the top-level browser
// executor, suitable for issuing browser-scoped CDP calls (e.g. target.*).
// Shared helper used by tab lifecycle, lookup, popup-guard, and cleanup paths.
func browserExecutorContext(ctx context.Context) (context.Context, error) {
	if ctx == nil {
		return nil, fmt.Errorf("no browser context available")
	}
	c := chromedp.FromContext(ctx)
	if c == nil || c.Browser == nil {
		return nil, fmt.Errorf("no browser executor available")
	}
	return cdp.WithExecutor(ctx, c.Browser), nil
}

func (tm *TabManager) LiveTabContexts() map[string]context.Context {
	tm.mu.RLock()
	defer tm.mu.RUnlock()
	out := make(map[string]context.Context, len(tm.tabs))
	for id, entry := range tm.tabs {
		if entry.Ctx != nil && entry.Ctx.Err() == nil {
			out[id] = entry.Ctx
		}
	}
	return out
}

func (tm *TabManager) trackedTabIDs() []string {
	tm.mu.RLock()
	defer tm.mu.RUnlock()
	ids := make([]string, 0, len(tm.tabs))
	for id := range tm.tabs {
		ids = append(ids, id)
	}
	return ids
}

func (tm *TabManager) CreateTab(url string) (string, context.Context, context.CancelFunc, error) {
	return tm.createTab(url, "")
}

func (tm *TabManager) CreateTabInBrowserContext(url, browserContextID string) (string, context.Context, context.CancelFunc, error) {
	if browserContextID == "" {
		return "", nil, nil, fmt.Errorf("browser context id required")
	}
	return tm.createTab(url, browserContextID)
}

func (tm *TabManager) createTab(url, browserContextID string) (string, context.Context, context.CancelFunc, error) {
	if tm == nil {
		return "", nil, nil, fmt.Errorf("tab manager not initialized")
	}
	if tm.browserCtx == nil {
		return "", nil, nil, fmt.Errorf("no browser context available")
	}

	if tm.config != nil && tm.config.MaxTabs > 0 {
		// Count managed tabs for eviction decisions. Using Chrome's target list
		// would include unmanaged targets (e.g. the initial about:blank tab),
		// causing premature eviction of managed tabs.
		tm.mu.RLock()
		managedCount := len(tm.tabs)
		tm.mu.RUnlock()

		if managedCount >= tm.config.MaxTabs {
			switch tm.config.TabEvictionPolicy {
			case "close_oldest":
				if evictErr := tm.closeOldestTab(); evictErr != nil {
					return "", nil, nil, fmt.Errorf("eviction failed: %w", evictErr)
				}
			case "reject":
				return "", nil, nil, &TabLimitError{Current: managedCount, Max: tm.config.MaxTabs}
			default: // "close_lru" (default)
				if evictErr := tm.closeLRUTab(); evictErr != nil {
					return "", nil, nil, fmt.Errorf("eviction failed: %w", evictErr)
				}
			}
		}
	}

	// target.CreateTarget works for both local and remote (CDP_URL) allocators.
	// Chromium's explicit focus=false contract opens a normal rendered tab while
	// leaving the browser window's OS focus unchanged. Do not set background=true:
	// heavy headed SPAs can suspend that target before DOM/AX reads. newWindow
	// remains false, so no additional OS window is created.
	//
	// Target.createTarget is a browser-level command, so it is issued on the
	// browser connection rather than through tm.browserCtx's own CDP session.
	// When PinchTab attaches to a browser that is already running, chromedp
	// binds that session to a tab the user owns; routing this call through it
	// makes every later tab creation block until the user's tab happens to
	// outlive the instance.
	browserExecCtx, err := browserExecutorContext(tm.browserCtx)
	if err != nil {
		return "", nil, nil, err
	}
	var targetID target.ID
	createCtx, createCancel := context.WithTimeout(browserExecCtx, tabCreateTimeout)
	params := target.CreateTarget("about:blank").WithFocus(false)
	if browserContextID != "" {
		params = params.WithBrowserContextID(cdp.BrowserContextID(browserContextID))
	}
	targetID, err = params.Do(createCtx)
	if err != nil {
		createCancel()
		if errors.Is(err, context.DeadlineExceeded) {
			return "", nil, nil, fmt.Errorf("create tab: browser did not open a new tab within %s — it may be out of memory or overloaded (close tabs or restart the instance)", tabCreateTimeout)
		}
		return "", nil, nil, fmt.Errorf("create target: %w", err)
	}
	createCancel()

	ctx, cancel := chromedp.NewContext(tm.browserCtx,
		chromedp.WithTargetID(targetID),
	)

	rawCDPID := string(targetID)
	tabID := tm.idMgr.TabIDFromCDPTarget(rawCDPID)

	if tm.onTabSetup != nil {
		if err := chromedp.Run(ctx, chromedp.ActionFunc(func(execCtx context.Context) error {
			return tm.onTabSetup(execCtx, tabID)
		})); err != nil {
			cancel()
			if execCtx, execErr := browserExecutorContext(tm.browserCtx); execErr == nil {
				_ = target.CloseTarget(targetID).Do(execCtx)
			}
			return "", nil, nil, fmt.Errorf("setup new tab: %w", err)
		}
	}

	if blockPatterns := tm.tabBlockPatterns(); len(blockPatterns) > 0 {
		_ = SetResourceBlocking(ctx, blockPatterns)
	}

	// Capture must be enabled before navigation: a page can throw from its first
	// synchronous script, before Navigate returns and before any later listener
	// could observe the exception.
	if tm.shouldEagerlyCaptureConsole() {
		tm.setupConsoleCapture(ctx, rawCDPID)
	}

	// Start network capture before navigation so CDP events are captured.
	if tm.netMonitor != nil {
		if err := tm.netMonitor.StartCapture(ctx, tabID); err != nil {
			slog.Warn("eager network capture failed", "tab", tabID, "err", err)
		}
	}

	if url != "" && url != "about:blank" {
		navCtx, navCancel := context.WithTimeout(ctx, tabCreateNavTimeout)
		if err := chromedp.Run(navCtx, chromedp.Navigate(url)); err != nil {
			navCancel()
			cancel()
			if execCtx, execErr := browserExecutorContext(tm.browserCtx); execErr == nil {
				_ = target.CloseTarget(targetID).Do(execCtx)
			}
			if errors.Is(err, context.DeadlineExceeded) {
				return "", nil, nil, fmt.Errorf("navigate new tab: page did not load within %s — the browser may be out of memory or overloaded (close tabs or restart the instance)", tabCreateNavTimeout)
			}
			return "", nil, nil, fmt.Errorf("navigate: %w", err)
		}
		navCancel()
	}

	now := time.Now()

	if tm.dialogMgr != nil {
		autoAccept := tm.config != nil && tm.config.DialogAutoAccept
		ListenDialogEvents(ctx, tabID, tm.dialogMgr, autoAccept)
		// Page domain must be enabled for Page.javascriptDialogOpening events
		// to be delivered to ListenTarget callbacks.
		if err := EnableDialogEvents(ctx); err != nil {
			slog.Warn("enable dialog events failed", "tabId", tabID, "err", err)
		}
	}

	tm.mu.Lock()
	tm.tabs[tabID] = &TabEntry{
		Ctx:                   ctx,
		Cancel:                cancel,
		CDPID:                 rawCDPID,
		CreatedAt:             now,
		LastUsed:              now,
		ConsoleCaptureEnabled: tm.shouldEagerlyCaptureConsole(),
	}
	tm.accessed[tabID] = true
	tm.currentTab = tabID
	tm.mu.Unlock()

	tm.startTabPolicyWatcher(tabID, ctx)

	return tabID, ctx, cancel, nil
}

// ErrCannotCloseLastTab is the last-tab precondition: at least one tab must
// remain or Chrome exits and takes the server down. It is a client precondition,
// not a server fault, so handlers classify it as a 4xx via errors.Is rather than
// matching the message text.
var ErrCannotCloseLastTab = errors.New("cannot close the last tab — at least one tab must remain")

func (tm *TabManager) CloseTab(tabID string) error {
	if tm == nil {
		return fmt.Errorf("tab manager not initialized")
	}
	// Guard against closing the last tab to prevent Chrome from exiting
	targets, err := tm.ListTargets()
	if err != nil {
		return fmt.Errorf("list targets: %w", err)
	}
	if len(targets) <= 1 {
		return ErrCannotCloseLastTab
	}

	tm.mu.Lock()
	entry, tracked := tm.tabs[tabID]
	tm.mu.Unlock()

	if tracked && entry.Cancel != nil {
		entry.Cancel()
	}

	cdpTargetID := tabID
	if tracked && entry.CDPID != "" {
		cdpTargetID = entry.CDPID
	}

	closeCtx, closeCancel := context.WithTimeout(tm.browserCtx, 5*time.Second)
	defer closeCancel()

	execCtx, execErr := browserExecutorContext(closeCtx)
	if execErr != nil {
		if !tracked {
			return tabNotFound(tabID)
		}
		slog.Debug("close target skipped", "tabId", tabID, "cdpId", cdpTargetID, "err", execErr)
		tm.purgeTrackedTabState(tabID, cdpTargetID)
		return nil
	}

	if err := target.CloseTarget(target.ID(cdpTargetID)).Do(execCtx); err != nil {
		if !tracked {
			return tabNotFound(tabID)
		}
		slog.Debug("close target CDP", "tabId", tabID, "cdpId", cdpTargetID, "err", err)
	}
	tm.purgeTrackedTabState(tabID, cdpTargetID)
	return nil
}

func (tm *TabManager) FocusTab(tabID string) error {
	if tm == nil {
		return fmt.Errorf("tab manager not initialized")
	}
	ctx, _, err := tm.TabContext(tabID)
	if err != nil {
		return err
	}

	if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
		return page.BringToFront().Do(ctx)
	})); err != nil {
		return fmt.Errorf("bring to front: %w", err)
	}
	return nil
}

// Execute runs a task for a tab through the TabExecutor, ensuring per-tab
// sequential execution with cross-tab parallelism bounded by the semaphore.
// If the TabExecutor has not been initialized, the task runs directly.
func (tm *TabManager) Execute(ctx context.Context, tabID string, task func(ctx context.Context) error) error {
	if tm.executor == nil {
		return task(ctx)
	}
	return tm.executor.Execute(ctx, tabID, task)
}

// Executor returns the underlying TabExecutor (may be nil).
func (tm *TabManager) Executor() *TabExecutor {
	return tm.executor
}