High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package runtime
import (
"context"
"fmt"
"log/slog"
"os"
"os/exec"
goruntime "runtime"
"strings"
"time"
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/browsers"
_ "github.com/pinchtab/pinchtab/internal/browsers/builtin"
"github.com/pinchtab/pinchtab/internal/browsers/runtimekit"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/config/geo"
"github.com/pinchtab/pinchtab/internal/stealth"
)
var (
runtimeGOOS = goruntime.GOOS
osGeteuid = os.Geteuid
containerMarkerPath = "/.dockerenv"
geoProviderForConfigFunc = geoProviderForConfig
)
const launchGeoLookupTimeout = 3 * time.Second
type launchGeoAlignment struct {
info geo.Info
flags []string
env []string
}
type Hooks struct {
SetHumanRandSeed func(int64)
IsProfileLockError func(string) bool
ClearStaleProfileLocks func(profileDir, errMsg string) (bool, error)
ConfigureBrowserProcess func(*exec.Cmd)
// QuarantineCorruptedProfile moves profileDir aside and recreates an
// empty dir at the same path. Used to recover from silent CDP attach
// failures (observed with CloakBrowser when the profile dir holds
// state it cannot ingest). Returns the quarantine path on success. keep is how
// many quarantined siblings of that profile survive, newest first, with 0
// meaning keep every one.
QuarantineCorruptedProfile func(profileDir string, keep int) (string, error)
}
// InitBrowser initializes a browser for a Bridge instance.
//
// When cfg.CDPAttachURL is set, this skips launching a browser process and
// connects to the externally-managed browser at that browser-level CDP
// WebSocket URL. The returned cancel funcs only release the chromedp
// allocator + browser context; the external browser process is left alive.
func InitBrowser(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks) (context.Context, context.CancelFunc, context.Context, context.CancelFunc, stealth.LaunchMode, error) {
if cfg != nil && strings.TrimSpace(cfg.CDPAttachURL) != "" {
return initBrowserFromExistingCDP(cfg, bundle)
}
launchCfg, effective := effectiveLaunchTarget(cfg)
slog.Info("starting browser initialization", "headless", launchCfg.Headless, "profile", launchCfg.ProfileDir, "binary", effective.Binary)
if b, ok := browsers.Get(effective.ID); ok {
tcfg := browsers.TargetConfig{
Provider: effective.ID,
Binary: effective.Binary,
}
if err := b.ValidateTarget(tcfg); err != nil {
return nil, nil, nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(launchCfg)
}
}
stealth.WarnBrowserVersionMismatch(launchCfg)
bundle = ensureStealthBundle(launchCfg, bundle)
geoAlignment, err := resolveLaunchGeoAlignment(context.Background(), launchCfg)
if err != nil {
return nil, nil, nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to resolve proxy geo alignment: %w", err)
}
allocCtx, allocCancel, opts, debugPort, err := setupAllocator(launchCfg, effective.Binary, bundle, hooks, geoAlignment)
if err != nil {
return nil, nil, nil, nil, stealth.LaunchModeUninitialized, err
}
browserCtx, browserCancel, launchMode, err := startBrowser(allocCtx, launchCfg, bundle, opts, debugPort, hooks, geoAlignment)
if err != nil {
allocCancel()
slog.Error("browser initialization failed", "headless", launchCfg.Headless, "error", err.Error())
return nil, nil, nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to start browser: %w", err)
}
// Publish the resolved DevTools port (auto-picked when the config left it
// unset) so bridge features that open side CDP sessions — e.g. the Console
// domain fallback for browsers without CapRuntimeConsoleEvents — can reach
// the launched browser.
cfg.BrowserDebugPort = debugPort
if ProxyAuthEnabled(launchCfg.Proxy) {
if err := EnableProxyAuth(browserCtx, launchCfg.Proxy, nil); err != nil {
browserCancel()
allocCancel()
return nil, nil, nil, nil, stealth.LaunchModeUninitialized, fmt.Errorf("failed to enable proxy auth: %w", err)
}
slog.Info("proxy authentication enabled via CDP", "proxy", launchCfg.Proxy.Redacted())
}
slog.Info("browser initialized successfully", "headless", launchCfg.Headless, "profile", launchCfg.ProfileDir)
return allocCtx, allocCancel, browserCtx, browserCancel, launchMode, nil
}
func effectiveLaunchTarget(cfg *config.RuntimeConfig) (*config.RuntimeConfig, runtimekit.EffectiveBrowser) {
effective := runtimekit.ResolveEffectiveBrowser(cfg)
if effective.Config == nil {
return cfg, effective
}
return effective.Config, effective
}
type providerLaunchPlan struct {
browser browsers.Browser
args []string
env []string
binary string
}
func providerLaunchConfig(cfg *config.RuntimeConfig, binary string, debugPort int) browsers.LaunchConfig {
return runtimekit.LaunchConfigFromRuntime(cfg, binary, debugPort, launchNeedsNoSandbox())
}
func resolveProviderLaunchPlan(cfg *config.RuntimeConfig, launchCfg browsers.LaunchConfig) (providerLaunchPlan, error) {
plan, err := runtimekit.ResolveProviderLaunchPlan(cfg, launchCfg)
if err != nil {
return providerLaunchPlan{}, fmt.Errorf("%s launch args: %w", config.NormalizeBrowser(cfg.DefaultBrowser), err)
}
return providerLaunchPlan{
browser: plan.Browser,
args: plan.Args,
env: plan.Env,
binary: plan.Binary,
}, nil
}
func ensureStealthBundle(cfg *config.RuntimeConfig, bundle *stealth.Bundle) *stealth.Bundle {
if bundle != nil {
return bundle
}
return stealth.NewBundle(cfg, cryptoRandSeed())
}
func setupAllocator(cfg *config.RuntimeConfig, binary string, bundle *stealth.Bundle, hooks Hooks, geoAlignment launchGeoAlignment) (context.Context, context.CancelFunc, []chromedp.ExecAllocatorOption, int, error) {
opts := []chromedp.ExecAllocatorOption{
chromedp.NoFirstRun,
chromedp.NoDefaultBrowserCheck,
}
debugPort := 0
if cfg.BrowserDebugPort > 0 {
debugPort = cfg.BrowserDebugPort
} else if port, err := findFreePort(cfg.InstancePortStart, cfg.InstancePortEnd); err == nil {
debugPort = port
}
launchCfg := runtimekit.LaunchConfigFromRuntime(cfg, binary, debugPort, launchNeedsNoSandbox())
// setupAllocator appends user extra flags itself (below), where the
// DisableInProcessGPU kill switch can strip them; the plan must not
// re-inject a second, unstrippable copy.
launchCfg.ExtraFlags = nil
plan, err := resolveProviderLaunchPlan(cfg, launchCfg)
if err != nil {
return nil, nil, nil, 0, err
}
opts = appendExecAllocatorFlags(opts, plan.args)
opts = appendExecAllocatorFlags(opts, bundle.Launch.Args)
proxyFlags, err := config.BrowserProxyFlags(cfg.Proxy)
if err != nil {
return nil, nil, nil, 0, err
}
opts = appendExecAllocatorFlags(opts, proxyFlags)
opts = appendExecAllocatorFlags(opts, geoAlignment.flags)
if plan.binary != "" {
opts = append(opts, chromedp.ExecPath(plan.binary))
}
if cfg.Headless {
opts = append(opts, chromedp.Flag("headless", "new"))
opts = append(opts, chromedp.Flag("hide-scrollbars", true))
opts = append(opts, chromedp.Flag("mute-audio", true))
opts = append(opts, chromedp.Flag("disable-vulkan", true))
// Use swiftshader (software GPU) for compositing under --headless=new.
// We deliberately do NOT pass --disable-gpu here: in new-headless
// mode Page.captureScreenshot routes through the compositor, which
// needs a GPU backend — disabling the GPU process leaves the
// compositor with no backend and screenshot calls hang past the
// action timeout.
opts = append(opts, chromedp.Flag("use-angle", "swiftshader"))
// Chromium 121+ requires this opt-in to actually load the
// swiftshader backend; without it, --use-angle=swiftshader is
// silently ignored and the compositor has no backend, which
// manifests as Page.captureScreenshot/printToPDF hanging.
opts = append(opts, chromedp.Flag("enable-unsafe-swiftshader", true))
// --in-process-gpu used to be enabled here as a perf optimization
// (saves one OS process and ~50-150MB per instance). Chrome stable
// patch updates have repeatedly regressed it for the headless=new
// + swiftshader combo: a GPU code crash takes the browser with it
// ~500ms after init, surfacing as `context canceled` on the first
// CreateTab. We now leave it off by default. Users who know their
// Chrome build is healthy and want the memory savings can opt in
// via `browser.extraFlags = "--in-process-gpu"`. DisableInProcessGPU
// is still honored as a kill switch by the crash-recovery path.
} else {
opts = append(opts, chromedp.Flag("headless", false))
}
if validPaths := existingExtensionPaths(cfg.ExtensionPaths); len(validPaths) > 0 {
joined := strings.Join(validPaths, ",")
opts = append(opts, chromedp.Flag("disable-extensions", false))
opts = append(opts, chromedp.Flag("load-extension", joined))
opts = append(opts, chromedp.Flag("disable-extensions-except", joined))
slog.Info("loading extensions", "paths", joined)
} else {
opts = append(opts, chromedp.Flag("disable-extensions", true))
}
if cfg.ProfileDir != "" {
opts = append(opts, chromedp.UserDataDir(cfg.ProfileDir))
}
w, h := randomWindowSize()
opts = append(opts, chromedp.WindowSize(w, h))
if cfg.Timezone != "" {
opts = append(opts, chromedp.Flag("tz", cfg.Timezone))
}
extraFlags := config.AllowedBrowserExtraFlags(cfg.BrowserExtraFlags)
if cfg.DisableInProcessGPU {
// Kill switch from the crash-recovery path: strip a user-supplied
// --in-process-gpu so a crash loop can't repeat after retry.
extraFlags = stripInProcessGPUFlag(extraFlags)
}
opts = appendExecAllocatorFlags(opts, extraFlags)
for _, flag := range appendBrowserCompatibilityFlags(nil) {
opts = appendExecAllocatorFlag(opts, flag)
}
opts = append(opts, chromedp.CombinedOutput(newPrefixedLogWriter(os.Stdout, "browser")))
opts = append(opts, chromedp.ModifyCmdFunc(func(cmd *exec.Cmd) {
if len(plan.env) > 0 || len(geoAlignment.env) > 0 {
if cmd.Env == nil {
cmd.Env = os.Environ()
}
if len(plan.env) > 0 {
cmd.Env = mergeGeoEnv(cmd.Env, plan.env)
}
cmd.Env = mergeGeoEnv(cmd.Env, geoAlignment.env)
}
if hooks.ConfigureBrowserProcess != nil {
hooks.ConfigureBrowserProcess(cmd)
}
}))
ctx, cancel := context.WithCancel(context.Background())
return ctx, cancel, opts, debugPort, nil
}
func applyStartupStealth(ctx context.Context, cfg *config.RuntimeConfig, bundle *stealth.Bundle, script string) error {
if !config.PinchTabStealthDefaultsDisabled(cfg) {
ua := ""
if bundle != nil {
ua = bundle.LaunchUserAgent()
}
if err := stealth.ApplyTargetEmulation(ctx, cfg, ua); err != nil {
return err
}
}
if strings.TrimSpace(script) == "" {
return nil
}
return injectedScript(ctx, script)
}
func missingBrowserBinaryError(cfg *config.RuntimeConfig) error {
browserID := config.NormalizeBrowser(cfg.DefaultBrowser)
target := config.ResolveDefaultTarget(cfg)
if target == "" {
target = browserID
}
if b, ok := browsers.Get(browserID); ok {
name := b.DisplayName()
return fmt.Errorf("%s binary not found for browser target %q: set browser.targets.%s.binary to the %s binary path",
strings.ToLower(name), target, target, name)
}
return fmt.Errorf("browser binary not found for browser target %q: set browser.targets.%s.binary in config", target, target)
}
func injectedScript(ctx context.Context, script string) error {
return chromedp.FromContext(ctx).Target.Execute(ctx,
"Page.addScriptToEvaluateOnNewDocument",
map[string]interface{}{
"source": script,
}, nil)
}
func geoProviderForConfig(cfg *config.RuntimeConfig) geo.Provider {
if cfg == nil || cfg.Proxy.Geo == nil || cfg.Proxy.Geo.IsZero() {
return geo.Noop{}
}
return geo.Static{Info: cfg.Proxy.GeoInfo()}
}
func resolveLaunchGeoAlignment(parent context.Context, cfg *config.RuntimeConfig) (launchGeoAlignment, error) {
// HasNoServer, not IsZero: launch alignment matches geo to the PROXY's egress, so
// with no server there is no egress to align with.
if cfg == nil || cfg.Proxy.HasNoServer() || cfg.Proxy.Geo == nil || cfg.Proxy.Geo.IsZero() {
return launchGeoAlignment{}, nil
}
if !config.CloakBrowserActive(cfg) {
return launchGeoAlignment{}, nil
}
if parent == nil {
parent = context.Background()
}
ctx, cancel := context.WithTimeout(parent, launchGeoLookupTimeout)
defer cancel()
info, err := geoProviderForConfigFunc(cfg).Lookup(ctx, "")
if err != nil {
return launchGeoAlignment{}, err
}
flags, env := applyGeoAlignment(cfg.DefaultBrowser, info, cfg.Cloak)
return launchGeoAlignment{
info: info,
flags: flags,
env: env,
}, nil
}
// mergeGeoEnv overlays additions over base by key; base is not mutated.
func mergeGeoEnv(base, additions []string) []string {
if len(additions) == 0 {
return base
}
out := make([]string, 0, len(base)+len(additions))
overrideKeys := make(map[string]struct{}, len(additions))
for _, kv := range additions {
if eq := strings.IndexByte(kv, '='); eq > 0 {
overrideKeys[kv[:eq]] = struct{}{}
}
}
for _, kv := range base {
eq := strings.IndexByte(kv, '=')
if eq > 0 {
if _, replace := overrideKeys[kv[:eq]]; replace {
continue
}
}
out = append(out, kv)
}
out = append(out, additions...)
return out
}