Skip to content

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

fix: bridge ignores the configured browser target binary and only works when discovery happens to succeed PIN-014

Luigi Agosti77b784d2b36c
diff --git a/cmd/pinchtab/cmd_bridge.go b/cmd/pinchtab/cmd_bridge.go
index 159b611e..db7072e2 100644
--- a/cmd/pinchtab/cmd_bridge.go
+++ b/cmd/pinchtab/cmd_bridge.go
@@ -53,7 +53,7 @@ Examples:
if browser, err := resolveBridgeBrowser(bridgeBrowser, cfg.BrowsersAvailable); err != nil {
return err
} else if browser != "" {
- cfg.DefaultBrowser = browser
+ applyBridgeBrowserTarget(cfg, browser)
}
if v := strings.TrimSpace(bridgeRemoteBrowserName); v != "" {
cfg.RemoteBrowserName = v
@@ -95,6 +95,15 @@ func validateBridgeCDPURL(raw string) (string, error) {
return trimmed, nil
}
+// applyBridgeBrowserTarget points the launch at the target that serves the
+// requested provider; leaving a default target of another provider in place
+// would let target resolution overwrite the flag.
+func applyBridgeBrowserTarget(cfg *config.RuntimeConfig, browser string) {
+ cfg.DefaultBrowser = browser
+ target, _ := config.MatchBrowserToTarget(cfg, browser)
+ cfg.DefaultTarget = target
+}
+
func resolveBridgeBrowser(browserFlag string, configured []string) (string, error) {
v := strings.TrimSpace(browserFlag)
if v == "" {
diff --git a/cmd/pinchtab/cmd_bridge_test.go b/cmd/pinchtab/cmd_bridge_test.go
index e9b220aa..107dc004 100644
--- a/cmd/pinchtab/cmd_bridge_test.go
+++ b/cmd/pinchtab/cmd_bridge_test.go
@@ -4,6 +4,8 @@ import (
"testing"
_ "github.com/pinchtab/pinchtab/internal/browsers/all"
+ "github.com/pinchtab/pinchtab/internal/browsers/runtimekit"
+ "github.com/pinchtab/pinchtab/internal/config"
)
func TestValidateBridgeCDPURL(t *testing.T) {
@@ -79,3 +81,44 @@ func TestBridgeAttachChildFlagContract(t *testing.T) {
t.Error("bridge command must not register obsolete browser-provider flag")
}
}
+
+func bridgeTargetsConfig() *config.RuntimeConfig {
+ return &config.RuntimeConfig{
+ DefaultBrowser: config.BrowserCloak,
+ DefaultTarget: "cloak-primary",
+ Targets: config.BrowserTargetsConfig{
+ "chrome-alt": {Provider: config.BrowserChrome, Binary: "/tmp/pinchtab-test-chrome"},
+ "cloak-primary": {Provider: config.BrowserCloak, Binary: "/tmp/pinchtab-test-cloak"},
+ },
+ }
+}
+
+func TestApplyBridgeBrowserTargetOverridesDefaultTarget(t *testing.T) {
+ cfg := bridgeTargetsConfig()
+
+ applyBridgeBrowserTarget(cfg, config.BrowserChrome)
+
+ if cfg.DefaultTarget != "chrome-alt" {
+ t.Fatalf("DefaultTarget = %q, want chrome-alt", cfg.DefaultTarget)
+ }
+ effective := runtimekit.ResolveEffectiveBrowser(cfg)
+ if effective.ID != config.BrowserChrome {
+ t.Fatalf("resolved provider = %q, want chrome", effective.ID)
+ }
+ if effective.Binary != "/tmp/pinchtab-test-chrome" {
+ t.Fatalf("resolved binary = %q, want the chrome target binary", effective.Binary)
+ }
+}
+
+func TestApplyBridgeBrowserTargetClearsUnmatchedDefaultTarget(t *testing.T) {
+ cfg := bridgeTargetsConfig()
+
+ applyBridgeBrowserTarget(cfg, config.BrowserGhostChrome)
+
+ if cfg.DefaultTarget != "" {
+ t.Fatalf("DefaultTarget = %q, want cleared", cfg.DefaultTarget)
+ }
+ if got := runtimekit.ResolveEffectiveBrowser(cfg).ID; got != config.BrowserGhostChrome {
+ t.Fatalf("resolved provider = %q, want ghost-chrome", got)
+ }
+}
diff --git a/cmd/pinchtab/cmd_cli_runtime.go b/cmd/pinchtab/cmd_cli_runtime.go
index 25264bb2..c2be2797 100644
--- a/cmd/pinchtab/cmd_cli_runtime.go
+++ b/cmd/pinchtab/cmd_cli_runtime.go
@@ -72,8 +72,8 @@ func runCLIWithServerCheck(cfg *config.RuntimeConfig, command string, fn func(cl
// preflightBrowserBinary fails fast with an actionable message when the active
// provider has no usable browser, instead of letting the launch silently retry
// and surface only the bridge's generic "instance not ready after 10s" timeout.
-// It mirrors the launch-time resolution in bridge/runtime.InitBrowser (explicit
-// browser.binary wins over discovery) so it can't diverge from what actually runs.
+// It shares runtimekit.ResolveEffectiveBrowser with bridge/runtime.InitBrowser,
+// so it cannot diverge from what actually runs.
func preflightBrowserBinary(cfg *config.RuntimeConfig) error {
if cfg == nil || strings.TrimSpace(cfg.CDPAttachURL) != "" {
return nil // attaching to an external CDP endpoint; no local binary needed
diff --git a/internal/bridge/runtime/geo_align_test.go b/internal/bridge/runtime/geo_align_test.go
index 5899ffb2..1389f6d7 100644
--- a/internal/bridge/runtime/geo_align_test.go
+++ b/internal/bridge/runtime/geo_align_test.go
@@ -80,7 +80,7 @@ func TestBuildChromeArgsWithBundleUsesProvidedGeoAlignment(t *testing.T) {
args, _, err := buildBrowserArgsWithBundle(&config.RuntimeConfig{
DefaultBrowser: config.BrowserCloak,
- }, nil, 9222, launchGeoAlignment{
+ }, "", nil, 9222, launchGeoAlignment{
flags: []string{"--fingerprint-locale=en-GB"},
})
if err != nil {
diff --git a/internal/bridge/runtime/init.go b/internal/bridge/runtime/init.go
index fbcba7bd..543ee7e0 100644
--- a/internal/bridge/runtime/init.go
+++ b/internal/bridge/runtime/init.go
@@ -57,35 +57,31 @@ func InitBrowser(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks)
return initBrowserFromExistingCDP(cfg, bundle)
}
- targetBinary := runtimekit.FindBrowserBinary(config.NormalizeBrowser(cfg.DefaultBrowser))
- if strings.TrimSpace(cfg.BrowserBinary) != "" {
- targetBinary = strings.TrimSpace(cfg.BrowserBinary)
- }
- slog.Info("starting browser initialization", "headless", cfg.Headless, "profile", cfg.ProfileDir, "binary", targetBinary)
- browserID := config.NormalizeBrowser(cfg.DefaultBrowser)
- if b, ok := browsers.Get(browserID); ok {
+ 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: browserID,
- Binary: targetBinary,
+ Provider: effective.ID,
+ Binary: effective.Binary,
}
if err := b.ValidateTarget(tcfg); err != nil {
- return nil, nil, nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(cfg)
+ return nil, nil, nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(launchCfg)
}
}
- bundle = ensureStealthBundle(cfg, bundle)
- geoAlignment, err := resolveLaunchGeoAlignment(context.Background(), cfg)
+ 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(cfg, bundle, hooks, geoAlignment)
+ 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, cfg, bundle, opts, debugPort, hooks, geoAlignment)
+ browserCtx, browserCancel, launchMode, err := startBrowser(allocCtx, launchCfg, bundle, opts, debugPort, hooks, geoAlignment)
if err != nil {
allocCancel()
- slog.Error("browser initialization failed", "headless", cfg.Headless, "error", err.Error())
+ 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
@@ -94,23 +90,25 @@ func InitBrowser(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks)
// the launched browser.
cfg.BrowserDebugPort = debugPort
- if ProxyAuthEnabled(cfg.Proxy) {
- if err := EnableProxyAuth(browserCtx, cfg.Proxy, nil); err != nil {
+ 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", cfg.Proxy.Redacted())
+ slog.Info("proxy authentication enabled via CDP", "proxy", launchCfg.Proxy.Redacted())
}
- slog.Info("browser initialized successfully", "headless", cfg.Headless, "profile", cfg.ProfileDir)
+ slog.Info("browser initialized successfully", "headless", launchCfg.Headless, "profile", launchCfg.ProfileDir)
return allocCtx, allocCancel, browserCtx, browserCancel, launchMode, nil
}
-// FindBrowserBinary exposes the launch-time browser discovery used by runtime
-// initialization so diagnostics can report against the same search path.
-func FindBrowserBinary() string {
- return runtimekit.FindBrowserBinary("chrome")
+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 {
@@ -144,7 +142,7 @@ func ensureStealthBundle(cfg *config.RuntimeConfig, bundle *stealth.Bundle) *ste
return stealth.NewBundle(cfg, cryptoRandSeed())
}
-func setupAllocator(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hooks, geoAlignment launchGeoAlignment) (context.Context, context.CancelFunc, []chromedp.ExecAllocatorOption, int, error) {
+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,
@@ -155,10 +153,6 @@ func setupAllocator(cfg *config.RuntimeConfig, bundle *stealth.Bundle, hooks Hoo
} else if port, err := findFreePort(cfg.InstancePortStart, cfg.InstancePortEnd); err == nil {
debugPort = port
}
- binary := strings.TrimSpace(cfg.BrowserBinary)
- if binary == "" {
- binary = runtimekit.FindBrowserBinary(config.NormalizeBrowser(cfg.DefaultBrowser))
- }
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
@@ -281,11 +275,16 @@ func applyStartupStealth(ctx context.Context, cfg *config.RuntimeConfig, bundle
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: set browser.binary to the %s binary path", strings.ToLower(name), name)
+ 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: set browser.binary in config")
+ 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 {
diff --git a/internal/bridge/runtime/init_target_test.go b/internal/bridge/runtime/init_target_test.go
new file mode 100644
index 00000000..fdda74cc
--- /dev/null
+++ b/internal/bridge/runtime/init_target_test.go
@@ -0,0 +1,109 @@
+package runtime
+
+import (
+ "os"
+ "path/filepath"
+ "slices"
+ "strings"
+ "testing"
+
+ _ "github.com/pinchtab/pinchtab/internal/browsers/chrome"
+ _ "github.com/pinchtab/pinchtab/internal/browsers/cloak"
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func withoutBrowserDiscovery(t *testing.T) {
+ t.Helper()
+ t.Setenv("PATH", "")
+ t.Setenv("HOME", t.TempDir())
+}
+
+func targetConfigWithCloakBinary(t *testing.T, binary string) *config.RuntimeConfig {
+ t.Helper()
+ return &config.RuntimeConfig{
+ DefaultBrowser: config.BrowserChrome,
+ DefaultTarget: "cloak-primary",
+ Targets: config.BrowserTargetsConfig{
+ "chrome-alt": {Provider: config.BrowserChrome, Binary: "/nonexistent/chrome"},
+ "cloak-primary": {
+ Provider: config.BrowserCloak,
+ Binary: binary,
+ ExtraFlags: "--pinchtab-target-flag",
+ Cloak: config.CloakBrowserConfig{FingerprintSeed: "target-seed"},
+ Proxy: config.BrowserProxyConfig{Server: "http://127.0.0.1:8899"},
+ },
+ },
+ }
+}
+
+func TestEffectiveLaunchTargetPrefersTargetBinaryOverDiscovery(t *testing.T) {
+ withoutBrowserDiscovery(t)
+ binary := filepath.Join(t.TempDir(), "cloak-binary")
+ if err := os.WriteFile(binary, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatalf("WriteFile() error = %v", err)
+ }
+
+ launchCfg, effective := effectiveLaunchTarget(targetConfigWithCloakBinary(t, binary))
+
+ if effective.Binary != binary {
+ t.Fatalf("effective binary = %q, want %q", effective.Binary, binary)
+ }
+ if effective.ID != config.BrowserCloak {
+ t.Fatalf("effective provider = %q, want %q", effective.ID, config.BrowserCloak)
+ }
+ if launchCfg.DefaultBrowser != config.BrowserCloak {
+ t.Fatalf("launch DefaultBrowser = %q, want %q", launchCfg.DefaultBrowser, config.BrowserCloak)
+ }
+ if launchCfg.BrowserBinary != binary {
+ t.Fatalf("launch BrowserBinary = %q, want %q", launchCfg.BrowserBinary, binary)
+ }
+}
+
+func TestEffectiveLaunchTargetFallsBackToDiscoveryWithoutTargets(t *testing.T) {
+ withoutBrowserDiscovery(t)
+ dir := t.TempDir()
+ discovered := filepath.Join(dir, "cloakbrowser")
+ if err := os.WriteFile(discovered, []byte("#!/bin/sh\n"), 0o755); err != nil {
+ t.Fatalf("WriteFile() error = %v", err)
+ }
+ t.Setenv("PATH", dir)
+
+ _, effective := effectiveLaunchTarget(&config.RuntimeConfig{DefaultBrowser: config.BrowserCloak})
+
+ if effective.Binary != discovered {
+ t.Fatalf("effective binary = %q, want discovered %q", effective.Binary, discovered)
+ }
+}
+
+func TestBuildBrowserArgsCarriesTargetLaunchSettings(t *testing.T) {
+ withoutBrowserDiscovery(t)
+ cfg := targetConfigWithCloakBinary(t, filepath.Join(t.TempDir(), "cloak-binary"))
+
+ args := BuildBrowserArgs(cfg, 9222)
+
+ for _, want := range []string{
+ "--fingerprint=target-seed",
+ "--pinchtab-target-flag",
+ "--proxy-server=http://127.0.0.1:8899",
+ } {
+ if !slices.Contains(args, want) {
+ t.Fatalf("missing target-derived arg %q in %v", want, args)
+ }
+ }
+}
+
+func TestMissingBrowserBinaryErrorNamesTargetKey(t *testing.T) {
+ withoutBrowserDiscovery(t)
+ launchCfg, _ := effectiveLaunchTarget(targetConfigWithCloakBinary(t, ""))
+
+ err := missingBrowserBinaryError(launchCfg)
+
+ for _, want := range []string{`"cloak-primary"`, "browser.targets.cloak-primary.binary"} {
+ if !strings.Contains(err.Error(), want) {
+ t.Fatalf("error %q does not mention %q", err, want)
+ }
+ }
+ if strings.Contains(err.Error(), "set browser.binary") {
+ t.Fatalf("error still points at the legacy top-level key: %q", err)
+ }
+}
diff --git a/internal/bridge/runtime/init_test.go b/internal/bridge/runtime/init_test.go
index d3be6350..64f845f1 100644
--- a/internal/bridge/runtime/init_test.go
+++ b/internal/bridge/runtime/init_test.go
@@ -376,12 +376,12 @@ func TestBuildBrowserArgs_MalformedProxyFailsClosed(t *testing.T) {
DefaultBrowser: config.BrowserChrome,
Proxy: config.BrowserProxyConfig{Server: "not a proxy url"},
}
- if _, _, err := buildBrowserArgsWithBundle(cfg, nil, 9222, launchGeoAlignment{}); err == nil {
+ if _, _, err := buildBrowserArgsWithBundle(cfg, "", nil, 9222, launchGeoAlignment{}); err == nil {
t.Fatal("expected launch-args build to fail for malformed proxy server")
}
cfg.Proxy.Server = "http://proxy.example.com:8080"
- args, _, err := buildBrowserArgsWithBundle(cfg, nil, 9222, launchGeoAlignment{})
+ args, _, err := buildBrowserArgsWithBundle(cfg, "", nil, 9222, launchGeoAlignment{})
if err != nil {
t.Fatalf("valid proxy should build: %v", err)
}
diff --git a/internal/bridge/runtime/launch_args.go b/internal/bridge/runtime/launch_args.go
index ed0c3403..5766ced1 100644
--- a/internal/bridge/runtime/launch_args.go
+++ b/internal/bridge/runtime/launch_args.go
@@ -50,16 +50,17 @@ func launchNeedsNoSandbox() bool {
}
func BuildBrowserArgs(cfg *config.RuntimeConfig, port int) []string {
+ cfg, effective := effectiveLaunchTarget(cfg)
geoAlignment, err := resolveLaunchGeoAlignment(context.Background(), cfg)
if err != nil {
- args, _, buildErr := buildBrowserArgsWithBundle(cfg, nil, port, launchGeoAlignment{})
+ args, _, buildErr := buildBrowserArgsWithBundle(cfg, effective.Binary, nil, port, launchGeoAlignment{})
if buildErr != nil {
slog.Error("build browser args failed", "err", buildErr)
return nil
}
return args
}
- args, _, err := buildBrowserArgsWithBundle(cfg, nil, port, geoAlignment)
+ args, _, err := buildBrowserArgsWithBundle(cfg, effective.Binary, nil, port, geoAlignment)
if err != nil {
slog.Error("build browser args failed", "err", err)
return nil
@@ -80,12 +81,8 @@ func existingExtensionPaths(paths []string) []string {
return validPaths
}
-func buildBrowserArgsWithBundle(cfg *config.RuntimeConfig, bundle *stealth.Bundle, port int, geoAlignment launchGeoAlignment) ([]string, []string, error) {
+func buildBrowserArgsWithBundle(cfg *config.RuntimeConfig, binary string, bundle *stealth.Bundle, port int, geoAlignment launchGeoAlignment) ([]string, []string, error) {
bundle = ensureStealthBundle(cfg, bundle)
- binary := strings.TrimSpace(cfg.BrowserBinary)
- if binary == "" {
- binary = runtimekit.FindBrowserBinary(config.NormalizeBrowser(cfg.DefaultBrowser))
- }
launchCfg := runtimekit.LaunchConfigFromRuntime(cfg, binary, port, launchNeedsNoSandbox())
if cfg.DisableInProcessGPU {
// Crash-recovery kill switch: a user-supplied --in-process-gpu must
diff --git a/internal/bridge/runtime/recovery.go b/internal/bridge/runtime/recovery.go
index 713ccda0..fa225615 100644
--- a/internal/bridge/runtime/recovery.go
+++ b/internal/bridge/runtime/recovery.go
@@ -149,7 +149,7 @@ func startBrowserWithRemoteAllocator(parentCtx context.Context, cfg *config.Runt
return nil, nil, stealth.LaunchModeUninitialized, missingBrowserBinaryError(cfg)
}
- args, providerEnv, err := buildBrowserArgsWithBundle(cfg, bundle, debugPort, geoAlignment)
+ args, providerEnv, err := buildBrowserArgsWithBundle(cfg, plan.binary, bundle, debugPort, geoAlignment)
if err != nil {
return nil, nil, stealth.LaunchModeUninitialized, err
}