High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package bridge
import (
"context"
"encoding/json"
"errors"
"net/http"
"time"
bridgetabs "github.com/pinchtab/pinchtab/internal/bridge/tabs"
"github.com/pinchtab/pinchtab/internal/cdptk"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/runtimetypes"
"github.com/pinchtab/pinchtab/internal/stealth"
)
type TabTarget struct {
TargetID string `json:"targetId"`
URL string `json:"url"`
Title string `json:"title"`
Type string `json:"type"`
BrowserContextID string `json:"browserContextId,omitempty"`
}
var ErrBrowserDraining = errors.New("browser restart in progress; retry shortly")
type BridgeAPI interface {
BrowserContext() context.Context
TabContext(tabID string) (ctx *TabHandle, resolvedID string, err error)
ListTargets() ([]TabTarget, error)
CreateTab(url string) (tabID string, ctx context.Context, cancel context.CancelFunc, err error)
CloseTab(tabID string) error
FocusTab(tabID string) error
ScheduleIdleLifecycle(tabID string)
CancelIdleLifecycle(tabID string)
GetRefCache(tabID string) *RefCache
SetRefCache(tabID string, cache *RefCache)
DeleteRefCache(tabID string)
ExecuteAction(ctx context.Context, kind string, req ActionRequest) (map[string]any, error)
AvailableActions() []string
// Execute runs a task for a tab with per-tab sequential execution
// and cross-tab bounded parallelism. If not supported, runs directly.
Execute(ctx context.Context, tabID string, task func(ctx context.Context) error) error
TabLockInfo(tabID string) *LockInfo
Lock(tabID, owner string, ttl time.Duration) error
Unlock(tabID, owner string) error
EnsureBrowser(cfg *config.RuntimeConfig) error
RestartBrowser(cfg *config.RuntimeConfig) error
// RunningBrowser reports the provider of the live browser process, or
// ("", false) when nothing is running. EnsureBrowser ignores the requested
// config once initialized, so handlers use this to reject explicit
// browser params that the running process cannot honor.
RunningBrowser() (string, bool)
StealthStatus() *stealth.Status
// GetAggregatedMemoryMetrics measures the whole browser process tree. There is
// no per-tab reading behind it, so it takes no tab identifier: /tabs/{id}/metrics
// uses the id to select the owning instance, never the measurement.
GetAggregatedMemoryMetrics() (*MemoryMetrics, error)
GetCrashLogs() []string
NetworkMonitor() *NetworkMonitor
AddRouteRule(tabID string, rule RouteRule) error
RemoveRouteRule(tabID, pattern string) (int, error)
ListRouteRules(tabID string) ([]RouteRule, error)
GetDialogManager() *DialogManager
GetConsoleLogs(tabID string, limit int) []LogEntry
ClearConsoleLogs(tabID string)
GetErrorLogs(tabID string, limit int) []ErrorEntry
ClearErrorLogs(tabID string)
Navigate(ctx context.Context, url string, params NavigateParams) (*NavigateResult, error)
Snapshot(ctx context.Context, tabID string, filter string, params ContentParams) (*SnapshotResult, error)
Text(ctx context.Context, tabID string, params ContentParams) (*TextResult, error)
ClearCache(ctx context.Context) error
CanClearCache(ctx context.Context) (bool, error)
ClearCookies(ctx context.Context) error
Evaluate(ctx context.Context, expression string, result any, opts EvalOpts) error
// CallFunctionOnNode resolves a backend node ID to a Runtime object,
// then calls the given JavaScript function on it. args may be nil.
// The result is unmarshaled from the CDP returnByValue response.
CallFunctionOnNode(ctx context.Context, backendNodeID int64, functionDecl string, args []map[string]any, result any) error
// EvaluateInFrame evaluates a JavaScript expression in the given
// frame's execution context. If frameID is empty, behaves like Evaluate.
EvaluateInFrame(ctx context.Context, frameID string, expression string, result any, opts EvalOpts) error
DescribeNode(ctx context.Context, backendNodeID int64) (*NodeInfo, error)
CaptureScreenshot(ctx context.Context, format string, quality int, clip *cdptk.ScreenshotClip) ([]byte, error)
StartScreencast(ctx context.Context, opts ScreencastOpts) (*ScreencastStream, error)
SetViewport(ctx context.Context, params ViewportParams) error
SetGeolocation(ctx context.Context, lat, lng, accuracy float64) error
SetEmulatedMedia(ctx context.Context, feature, value string) error
SetNetworkConditions(ctx context.Context, params NetworkConditions) error
SetExtraHTTPHeaders(ctx context.Context, headers map[string]string) error
GetCookies(ctx context.Context, urls []string) ([]CookieData, error)
SetCookie(ctx context.Context, params SetCookieParams) error
CurrentURL(ctx context.Context) (string, error)
CurrentTitle(ctx context.Context) (string, error)
PrintToPDF(ctx context.Context, params PDFParams) ([]byte, error)
SetFileInputFiles(ctx context.Context, nodeID int64, paths []string) error
ResolveSelectorToNodeID(ctx context.Context, selector string, refCache *RefCache, frameID string) (int64, error)
DownloadURL(ctx context.Context, dlURL string, opts DownloadOpts) (*DownloadResult, error)
EnableFetchWithAuth(ctx context.Context) error
DisableFetch(ctx context.Context) error
ListenAuthRequired(ctx context.Context, handler func(requestID string, isAuth bool))
ContinueWithAuth(ctx context.Context, requestID, username, password string) error
ContinueRequest(ctx context.Context, requestID string) error
// SetFetchPauseSuppressed toggles per-tab suppression of the proxy-auth
// listener's blanket ContinueRequest while the credentials handler owns
// request-pause dispatch. Declared here (not probed) so decorated bridges
// forward it instead of silently dropping the suppression contract.
SetFetchPauseSuppressed(tabID string, v bool)
GoBack(ctx context.Context) (didNavigate bool, err error)
GoForward(ctx context.Context) (didNavigate bool, err error)
Reload(ctx context.Context) error
WaitVisible(ctx context.Context, selector string) error
EnableNetwork(ctx context.Context) error
ListenNetworkEvents(ctx context.Context, handler NetworkEventHandler)
SetRawCookie(ctx context.Context, params RawSetCookieParams) error
GetRawCookies(ctx context.Context) ([]RawCookie, error)
SetUserAgentOverride(ctx context.Context, params UserAgentOverrideParams) error
SetLocaleOverride(ctx context.Context, locale string) error
SetTimezoneOverride(ctx context.Context, timezoneID string) error
SetDeviceMetricsOverride(ctx context.Context, params DeviceMetricsOverrideParams) error
AddScriptToEvaluateOnNewDocument(ctx context.Context, source string) (string, error)
}
// Construct ScreencastStream via runtimetypes.NewScreencastStreamWithDone (the
// bridge screencast loop owns and closes the done channel itself).
type (
EvalOpts = runtimetypes.EvalOpts
NodeInfo = runtimetypes.NodeInfo
ScreencastOpts = runtimetypes.ScreencastOpts
ScreencastStream = runtimetypes.ScreencastStream
CookieData = runtimetypes.CookieData
SetCookieParams = runtimetypes.SetCookieParams
ViewportParams = runtimetypes.ViewportParams
NetworkConditions = runtimetypes.NetworkConditions
DownloadOpts = runtimetypes.DownloadOpts
DownloadResult = runtimetypes.DownloadResult
PDFParams = runtimetypes.PDFParams
)
type LockInfo = bridgetabs.LockInfo
type NetworkEventHandler struct {
OnRequestWillBeSent func(frameID, requestID string, resourceType string)
OnResponseReceived func(requestID string, remoteIPAddress string)
}
// RawSetCookieParams holds parameters for setting a cookie via CDP network domain,
// used by state.go to restore cookies from state files without importing cdproto.
type RawSetCookieParams struct {
Name string
Value string
Domain string
Path string
Secure bool
HTTPOnly bool
SameSite string // "Strict", "Lax", "None", or ""
}
type RawCookie struct {
Name string `json:"name"`
Value string `json:"value"`
Domain string `json:"domain"`
Path string `json:"path"`
Expires float64 `json:"expires"`
Secure bool `json:"secure"`
HTTPOnly bool `json:"httpOnly"`
SameSite string `json:"sameSite"`
}
type UserAgentOverrideParams struct {
UserAgent string
Platform string
AcceptLanguage string
}
type DeviceMetricsOverrideParams struct {
Width int64
Height int64
DeviceScaleFactor float64
Mobile bool
ScreenWidth int64
ScreenHeight int64
}
type ProfileService interface {
RegisterHandlers(mux *http.ServeMux)
List() ([]ProfileInfo, error)
Create(name string) error
Import(name, sourcePath string) error
Reset(name string) error
Delete(name string) error
Logs(name string, limit int) []ActionRecord
Analytics(name string) AnalyticsReport
RecordAction(profile string, record ActionRecord)
}
type OrchestratorService interface {
RegisterHandlers(mux *http.ServeMux)
Launch(name, port string, headless bool, extensionPaths []string) (*Instance, error)
Stop(id string) error
StopProfile(name string) error
List() []Instance
Logs(id string) (string, error)
FirstRunningURL() string
AllTabs() []InstanceTab
FindInstanceByTab(tabID string) (*Instance, bool)
ScreencastURL(instanceID, tabID string) string
Shutdown()
ForceShutdown()
}
type ProfileInfo struct {
ID string `json:"id,omitempty"`
Name string `json:"name"`
Path string `json:"path,omitempty"`
PathExists bool `json:"pathExists,omitempty"`
Created time.Time `json:"created"`
LastUsed time.Time `json:"lastUsed"`
DiskUsage int64 `json:"diskUsage"`
Running bool `json:"running"`
Temporary bool `json:"temporary,omitempty"` // ephemeral instance profiles (auto-generated)
Quarantined bool `json:"quarantined,omitempty"` // corrupted profiles renamed aside by quarantine
Source string `json:"source,omitempty"`
ChromeProfileName string `json:"chromeProfileName,omitempty"`
AccountEmail string `json:"accountEmail,omitempty"`
AccountName string `json:"accountName,omitempty"`
HasAccount bool `json:"hasAccount,omitempty"`
UseWhen string `json:"useWhen,omitempty"`
Description string `json:"description,omitempty"`
}
type ActionRecord struct {
Timestamp time.Time `json:"timestamp"`
Method string `json:"method"`
Endpoint string `json:"endpoint"`
URL string `json:"url"`
TabID string `json:"tabId"`
DurationMs int64 `json:"durationMs"`
Status int `json:"status"`
}
type AnalyticsReport struct {
TotalActions int `json:"totalActions"`
Last24h int `json:"last24h"`
CommonHosts map[string]int `json:"commonHosts"`
TopEndpoints map[string]int `json:"topEndpoints,omitempty"`
RepeatPatterns []string `json:"repeatPatterns,omitempty"`
Suggestions []string `json:"suggestions,omitempty"`
}
type SecurityPolicy struct {
AllowedDomains []string `json:"allowedDomains,omitempty"`
}
func ModeFromHeadless(headless bool) string {
if headless {
return "headless"
}
return "headed"
}
func normalizeInstanceMode(mode string, headless bool) string {
switch mode {
case "headless", "headed":
return mode
default:
return ModeFromHeadless(headless)
}
}
type Instance struct {
ID string `json:"id"` // Hash-based ID: inst_XXXXXXXX
ProfileID string `json:"profileId"` // Hash-based profile ID: prof_XXXXXXXX
ProfileName string `json:"profileName"` // Human-readable profile name (for display only)
Port string `json:"port"` // Internal: instance port
URL string `json:"url,omitempty"` // Canonical base URL for bridge-backed instances
Mode string `json:"mode"` // API mode: "headless" or "headed"
Headless bool `json:"headless"` // Mode: headless vs headed
Status string `json:"status"` // Status: starting/running/stopping/stopped/error
StartTime time.Time `json:"startTime"`
Error string `json:"error,omitempty"` // Error message if status=error
Attached bool `json:"attached"` // True if attached rather than locally launched
AttachType string `json:"attachType,omitempty"` // "cdp" or "bridge" for attached instances
CdpURL string `json:"cdpUrl,omitempty"` // CDP WebSocket URL (for CDP-attached instances)
SecurityPolicy *SecurityPolicy `json:"securityPolicy,omitempty"`
Browser string `json:"browser,omitempty"`
// FallbackFrom/FallbackReason: omitempty keeps successful-launch
// Instance JSON byte-identical to pre-P2.4a output.
FallbackFrom string `json:"fallbackFrom,omitempty"`
FallbackReason string `json:"fallbackReason,omitempty"`
Crashes *CrashSummary `json:"crashes,omitempty"`
Responsiveness string `json:"responsiveness"`
}
const (
ResponsivenessResponsive = "responsive"
ResponsivenessUnresponsive = "unresponsive"
ResponsivenessUnknown = "unknown"
)
func NormalizeResponsiveness(value string) string {
switch value {
case ResponsivenessResponsive, ResponsivenessUnresponsive:
return value
default:
return ResponsivenessUnknown
}
}
func (i Instance) MarshalJSON() ([]byte, error) {
type alias Instance
copy := alias(i)
copy.Mode = normalizeInstanceMode(copy.Mode, copy.Headless)
copy.Responsiveness = NormalizeResponsiveness(copy.Responsiveness)
return json.Marshal(copy)
}
type InstanceTab struct {
ID string `json:"id"` // Runtime tab ID (raw CDP target ID on this branch)
InstanceID string `json:"instanceId"` // Hash-based instance ID: inst_XXXXXXXX
URL string `json:"url"`
Title string `json:"title"`
}