High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: random thinking
Luigi Agostif711cf0beba7
diff --git a/cmd/pinchtab/cmd_bridge.go b/cmd/pinchtab/cmd_bridge.goindex 69a15a11..d037713e 100644--- a/cmd/pinchtab/cmd_bridge.go+++ b/cmd/pinchtab/cmd_bridge.go@@ -1,11 +1,9 @@package mainimport (- "bufio""context""fmt""log/slog"- "net""net/http""os""os/signal"@@ -48,7 +46,7 @@ func runBridgeServer(cfg *config.RuntimeConfig) {// HTTP serverserver := &http.Server{Addr: listenAddr,- Handler: recoveryMiddleware(loggingMiddleware(handlers.AuthMiddleware(cfg, mux))),+ Handler: handlers.RequestIDMiddleware(handlers.LoggingMiddleware(recoveryMiddleware(handlers.AuthMiddleware(cfg, mux)))),ReadHeaderTimeout: 10 * time.Second,ReadTimeout: 30 * time.Second,WriteTimeout: 60 * time.Second,@@ -77,23 +75,6 @@ func runBridgeServer(cfg *config.RuntimeConfig) {}}-// Simple middleware to log HTTP requests-func loggingMiddleware(next http.Handler) http.Handler {- return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {- start := time.Now()- recorder := &statusRecorder{ResponseWriter: w, statusCode: 200}-- next.ServeHTTP(recorder, r)-- slog.Info("request",- "method", r.Method,- "path", r.URL.Path,- "status", recorder.statusCode,- "ms", time.Since(start).Milliseconds(),- )- })-}-// recoveryMiddleware catches panics in HTTP handlers and returns a 500// instead of crashing the bridge process. Go's net/http server only// recovers panics in the serve goroutine; this middleware provides the@@ -102,7 +83,9 @@ func recoveryMiddleware(next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {defer func() {if p := recover(); p != nil {+ handlers.RecordRecoveredPanic()slog.Error("handler panic recovered",+ "requestId", w.Header().Get("X-Request-Id"),"method", r.Method,"path", r.URL.Path,"panic", fmt.Sprintf("%v", p),@@ -113,21 +96,3 @@ func recoveryMiddleware(next http.Handler) http.Handler {next.ServeHTTP(w, r)})}--type statusRecorder struct {- http.ResponseWriter- statusCode int-}--func (r *statusRecorder) WriteHeader(code int) {- r.statusCode = code- r.ResponseWriter.WriteHeader(code)-}--func (r *statusRecorder) Hijack() (net.Conn, *bufio.ReadWriter, error) {- h, ok := r.ResponseWriter.(http.Hijacker)- if !ok {- return nil, nil, fmt.Errorf("given http.ResponseWriter is not a http.Hijacker")- }- return h.Hijack()-}diff --git a/docs/architecture/overall-system-chart.md b/docs/architecture/overall-system-chart.mdnew file mode 100644index 00000000..274575eb--- /dev/null+++ b/docs/architecture/overall-system-chart.md@@ -0,0 +1,195 @@+# Overall System Chart++This page gives the full mental model of Pinchtab in one place.++It combines:+- the primary user path+- the server/bridge runtime split+- managed vs attached instances+- current routing and execution+- current security layer and future scheduling layer++## Chart 1: Overall Product Shape++```mermaid+flowchart TD+ U["User / Agent / Tool"] --> S["Pinchtab Server"]++ S --> D["Dashboard / Profiles / Instance API"]+ S --> R["Routing / Orchestrator"]+ S --> X["Shorthand Browser API"]++ R --> M1["Managed Instance"]+ R --> A1["Attached Instance"]++ M1 --> B["pinchtab bridge"]+ B --> C1["Chrome"]+ C1 --> T1["Tabs"]++ A1 --> C2["External Chrome"]+ C2 --> T2["Tabs"]+```++## Chart 2: Primary Usage Path++```mermaid+flowchart LR+ I["Install Pinchtab"] --> P["Run: pinchtab"]+ P --> L["Local server on localhost:9867"]+ L --> A["Agent / Tool connects over HTTP"]+ A --> W["Browser work happens through Pinchtab"]+```++This is the primary user journey.++The normal user should think:+- install Pinchtab+- run `pinchtab`+- point the client at `http://localhost:9867`++They should not need to think about `pinchtab bridge` directly.++## Chart 3: Runtime Types++```mermaid+flowchart TD+ I["Instance"] --> S{"source"}++ S --> M["managed"]+ S --> A["attached"]++ M --> R1{"runtime"}+ A --> R2{"runtime"}++ R1 --> B["bridge"]+ R1 --> D["direct-cdp"]++ R2 --> D2["direct-cdp"]+```++Interpretation:+- `source` = who introduced the instance+- `runtime` = how the server reaches the browser++## Chart 4: Current And Future Execution Layers++```mermaid+flowchart LR+ U["Agent Request"] --> P["Policy / Security Layer"]+ P --> Q["Task Scheduling Layer"]+ Q --> O["Orchestrator / Routing"]+ O --> E["Bridge Executor or Direct CDP"]+ E --> C["Chrome Tab"]+```++Meaning:+- **Policy / Security** decides whether a request should be admitted or sanitized+- **Task Scheduling** decides when and where admitted work should run+- **Orchestrator / Routing** decides which instance/tab path is used+- **Executor** performs the actual tab work++Today:+- execution exists+- routing exists+- security exists as a real IDPI defense layer+- scheduling is still mostly direct execution plus concurrency control++## Chart 4A: Current Security Layer++```mermaid+flowchart TD+ R["Request"] --> N{"Navigation?"}+ N -->|Yes| D["IDPI domain policy"]+ N -->|No| X["Continue"]++ D --> D2{"Allowed?"}+ D2 -->|No, strict| B["Block"]+ D2 -->|No, warn| W["Add warning header"]+ D2 -->|Yes| X++ X --> O{"Output content?"}+ O -->|Text or Snapshot| S["IDPI content scan"]+ O -->|Other| E["Execute / Return"]++ S --> S2{"Threat?"}+ S2 -->|No| E+ S2 -->|Yes, strict| B2["Block response"]+ S2 -->|Yes, warn| W2["Add warning metadata"]++ W2 --> WR{"Wrap text?"}+ WR -->|Yes| WT["Wrap as untrusted_web_content"]+ WR -->|No| E+ WT --> E+```++Current implementation shape:++- navigation checks happen before the tab opens or re-navigates+- content scanning happens on `/text` and `/snapshot`+- text wrapping is applied to `/text` output when enabled+- strict mode blocks, warn mode annotates++## Chart 5: Current Execution Model++```mermaid+flowchart TD+ H["HTTP Request"] --> O["Orchestrator / Server"]+ O --> T["Target Tab"]+ T --> L["Per-tab lock"]+ L --> G["Global concurrency limit"]+ G --> E["Execute CDP action"]+```++This is the current model already present in the product:+- per-tab sequential execution+- bounded cross-tab parallelism+- direct request execution++That means the current architecture already has:++- a **security layer** for admission and output safety+- an **execution layer** for concurrency correctness++What it does not yet have as a first-class subsystem is:++- a true **task scheduling layer** with queued work, fairness, and dispatch policy++## Chart 6: Recommended Future Model++```mermaid+flowchart TD+ H["HTTP Request"] --> A["Admission"]+ A --> B{"Allowed?"}+ B -->|No| X["Reject"]+ B -->|Yes| Q["Queue"]+ Q --> S["Scheduler"]+ S --> R["Instance / Tab selection"]+ R --> E["Executor"]+ E --> C["Chrome"]+```++This is the cleaner model for multi-agent and parallel execution:+- requests become tasks+- tasks are admitted or rejected+- admitted tasks are queued+- the scheduler chooses what runs next+- existing executors still enforce per-tab correctness++## Reading Guide++Use the charts like this:++- **Chart 1** for the product overview+- **Chart 2** for onboarding and default usage+- **Chart 3** for instance taxonomy+- **Chart 4** for control-plane layering+- **Chart 5** for how execution works today+- **Chart 6** for the likely future scheduling architecture++## Related Docs++- [Architecture](pinchtab-architecture.md)+- [Instance Model Charts](instance-model-charts.md)+- [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md)+- [Expert Guide: Attach](../guides/expert-attach.md)+- [Expert Guide: Multi-Instance Strategies](../guides/expert-strategies.md)diff --git a/docs/architecture/pinchtab-architecture.md b/docs/architecture/pinchtab-architecture.mdindex 0817069e..2afaa6b0 100644--- a/docs/architecture/pinchtab-architecture.md+++ b/docs/architecture/pinchtab-architecture.md@@ -31,6 +31,46 @@ The product has two process roles:Agents never touch CDP directly. They send HTTP requests, get back JSON.The accessibility tree (a11y) is the primary interface — not screenshots, not DOM.+## Security Layer++Pinchtab now has a real security layer for indirect prompt injection defense.++This layer lives in the server path, not inside the agent and not inside Chrome.+Its job is to inspect untrusted web input before that content is passed back to an LLM-driven caller.++Current security responsibilities:++- **domain policy on navigation** — block or warn before navigating to non-approved domains+- **content scanning on output** — scan `/text` and `/snapshot` output for common prompt-injection phrases+- **content wrapping** — wrap extracted text in `<untrusted_web_content>` delimiters with a safety advisory++The important architectural distinction is:++- **security** decides whether content should be admitted, annotated, or blocked+- **routing** decides which instance/tab path handles the request+- **execution** performs the actual browser action++In other words:++```text+request+ -> security / policy+ -> routing+ -> execution+```++The security layer is configured through `security.idpi` in config and supports:++- `enabled`+- `allowedDomains`+- `strictMode`+- `scanContent`+- `wrapContent`+- `customPatterns`++Strict mode blocks.+Warn mode allows the request but annotates the response with an IDPI warning.+## Instance Mental ModelThe cleanest way to think about instances is with two axes:@@ -164,6 +204,7 @@ A plausible future expansion is:For a focused comparison, see [Managed Bridge vs Managed Direct-CDP](managed-bridge-vs-managed-direct-cdp.md).For the visual version of the model, see [Instance Model Charts](instance-model-charts.md).+For the full system picture, see [Overall System Chart](overall-system-chart.md).## Design Principles@@ -171,7 +212,8 @@ For the visual version of the model, see [Instance Model Charts](instance-model-2. **HTTP over WebSocket** — Stateless requests, no connection management for agents3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints4. **Self-contained by default** — Launches and manages Chrome itself unless you explicitly use attach-5. **Decoupled Architecture** — Interface-driven design for testability and maintainability+5. **Layered Safety** — Security policy is enforced before untrusted web content reaches downstream agents+6. **Decoupled Architecture** — Interface-driven design for testability and maintainability## Project Layoutdiff --git a/docs/examples/pinchtab-bridge.md b/docs/examples/pinchtab-bridge.mdnew file mode 100644index 00000000..036fdac4--- /dev/null+++ b/docs/examples/pinchtab-bridge.md@@ -0,0 +1,200 @@+# Example: Bridge Smoke Test++This example is a happy-path smoke test for a running `pinchtab bridge` instance on `127.0.0.1:9867`.++It is useful when you want to verify that the single-instance runtime can:+- respond to health checks+- open and list tabs+- navigate and inspect pages+- perform actions+- capture screenshots and PDFs+- read cookies+- use tab locking++For the bridge-mode mental model, see [Expert Guide: Bridge Mode](../guides/expert-bridge-mode.md).++## Prerequisites++Start the bridge:++```bash+pinchtab bridge+```++Set the base URL:++```bash+BASE=http://127.0.0.1:9867+```++The commands below assume `jq` is installed.++## 1. Check Health++```bash+curl -s "$BASE/health" | jq .+```++You should get a JSON health response from the bridge runtime.++## 2. Open A Tab++```bash+TAB=$(curl -s -X POST "$BASE/tab" \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://www.wikipedia.org"}' \+ | jq -r '.tabId // .id')++echo "$TAB"+```++This opens a new tab and stores the tab ID in `TAB`.++## 3. List Tabs++```bash+curl -s "$BASE/tabs" | jq .+```++This confirms the bridge sees the tab you just opened.++## 4. Capture An Interactive Snapshot++```bash+curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .+```++This returns the accessibility-style tree used for refs and actions.++## 5. Extract Page Text++```bash+curl -s "$BASE/tabs/$TAB/text" | jq .+```++This verifies text extraction works for the current tab.++## 6. Find A Search Input Ref++```bash+SEARCH_REF=$(curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" \+ | jq -r '.. | objects | select(.role? == "textbox" or .role? == "searchbox" or .name? == "Search Wikipedia") | .ref' \+ | head -1)++echo "$SEARCH_REF"+```++This extracts one interactive ref from the snapshot.++## 7. Fill And Press Enter++```bash+curl -s -X POST "$BASE/tabs/$TAB/action" \+ -H "Content-Type: application/json" \+ -d "{\"kind\":\"fill\",\"ref\":\"$SEARCH_REF\",\"text\":\"Browser automation\"}" | jq .++curl -s -X POST "$BASE/tabs/$TAB/action" \+ -H "Content-Type: application/json" \+ -d '{"kind":"press","key":"Enter"}' | jq .+```++This verifies action execution and should trigger navigation.++## 8. Snapshot Again After Navigation++```bash+curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .+```++This confirms the bridge remains usable after a page transition.++## 9. Take A Screenshot++```bash+curl -s "$BASE/tabs/$TAB/screenshot" > smoke.jpg+ls -lh smoke.jpg+```++This verifies screenshot generation.++## 10. Export A PDF++```bash+curl -s "$BASE/tabs/$TAB/pdf" > smoke.pdf+ls -lh smoke.pdf+```++This verifies PDF export.++## 11. Read Cookies++```bash+curl -s "$BASE/tabs/$TAB/cookies" | jq .+```++This checks cookie retrieval for the active page.++## 12. Lock And Unlock The Tab++```bash+curl -s -X POST "$BASE/tabs/$TAB/lock" \+ -H "Content-Type: application/json" \+ -d '{"owner":"smoke-test","ttl":60}' | jq .++curl -s -X POST "$BASE/tabs/$TAB/unlock" \+ -H "Content-Type: application/json" \+ -d '{"owner":"smoke-test"}' | jq .+```++This verifies tab ownership locking works.++## 13. Open A Second Tab++```bash+TAB2=$(curl -s -X POST "$BASE/tab" \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://example.com"}' \+ | jq -r '.tabId // .id')++echo "$TAB2"+curl -s "$BASE/tabs" | jq .+```++This confirms the bridge handles multiple tabs in one runtime.++## Optional: Evaluate JavaScript++This only works if `evaluate` is enabled in config.++```bash+curl -s -X POST "$BASE/tabs/$TAB/evaluate" \+ -H "Content-Type: application/json" \+ -d '{"expression":"document.title"}' | jq .+```++## Optional: Use The Top-Level Shorthand Endpoints++```bash+curl -s -X POST "$BASE/navigate" \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}' | jq .++curl -s "$BASE/snapshot?filter=interactive" | jq .+```++These verify the direct bridge shortcuts in addition to the tab-scoped endpoints.++## What This Example Proves++If the full sequence works, your bridge runtime can:+- start and respond to API requests+- manage multiple tabs+- inspect page structure and text+- execute actions+- render visual outputs+- support locking and basic browser state APIs++If this example fails, check:+- the bridge is running on `127.0.0.1:9867`+- Chrome can be started successfully+- required features such as `evaluate` are enabled before testing themdiff --git a/docs/examples/pinchtab.md b/docs/examples/pinchtab.mdnew file mode 100644index 00000000..036fdac4--- /dev/null+++ b/docs/examples/pinchtab.md@@ -0,0 +1,200 @@+# Example: Bridge Smoke Test++This example is a happy-path smoke test for a running `pinchtab bridge` instance on `127.0.0.1:9867`.++It is useful when you want to verify that the single-instance runtime can:+- respond to health checks+- open and list tabs+- navigate and inspect pages+- perform actions+- capture screenshots and PDFs+- read cookies+- use tab locking++For the bridge-mode mental model, see [Expert Guide: Bridge Mode](../guides/expert-bridge-mode.md).++## Prerequisites++Start the bridge:++```bash+pinchtab bridge+```++Set the base URL:++```bash+BASE=http://127.0.0.1:9867+```++The commands below assume `jq` is installed.++## 1. Check Health++```bash+curl -s "$BASE/health" | jq .+```++You should get a JSON health response from the bridge runtime.++## 2. Open A Tab++```bash+TAB=$(curl -s -X POST "$BASE/tab" \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://www.wikipedia.org"}' \+ | jq -r '.tabId // .id')++echo "$TAB"+```++This opens a new tab and stores the tab ID in `TAB`.++## 3. List Tabs++```bash+curl -s "$BASE/tabs" | jq .+```++This confirms the bridge sees the tab you just opened.++## 4. Capture An Interactive Snapshot++```bash+curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .+```++This returns the accessibility-style tree used for refs and actions.++## 5. Extract Page Text++```bash+curl -s "$BASE/tabs/$TAB/text" | jq .+```++This verifies text extraction works for the current tab.++## 6. Find A Search Input Ref++```bash+SEARCH_REF=$(curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" \+ | jq -r '.. | objects | select(.role? == "textbox" or .role? == "searchbox" or .name? == "Search Wikipedia") | .ref' \+ | head -1)++echo "$SEARCH_REF"+```++This extracts one interactive ref from the snapshot.++## 7. Fill And Press Enter++```bash+curl -s -X POST "$BASE/tabs/$TAB/action" \+ -H "Content-Type: application/json" \+ -d "{\"kind\":\"fill\",\"ref\":\"$SEARCH_REF\",\"text\":\"Browser automation\"}" | jq .++curl -s -X POST "$BASE/tabs/$TAB/action" \+ -H "Content-Type: application/json" \+ -d '{"kind":"press","key":"Enter"}' | jq .+```++This verifies action execution and should trigger navigation.++## 8. Snapshot Again After Navigation++```bash+curl -s "$BASE/tabs/$TAB/snapshot?filter=interactive" | jq .+```++This confirms the bridge remains usable after a page transition.++## 9. Take A Screenshot++```bash+curl -s "$BASE/tabs/$TAB/screenshot" > smoke.jpg+ls -lh smoke.jpg+```++This verifies screenshot generation.++## 10. Export A PDF++```bash+curl -s "$BASE/tabs/$TAB/pdf" > smoke.pdf+ls -lh smoke.pdf+```++This verifies PDF export.++## 11. Read Cookies++```bash+curl -s "$BASE/tabs/$TAB/cookies" | jq .+```++This checks cookie retrieval for the active page.++## 12. Lock And Unlock The Tab++```bash+curl -s -X POST "$BASE/tabs/$TAB/lock" \+ -H "Content-Type: application/json" \+ -d '{"owner":"smoke-test","ttl":60}' | jq .++curl -s -X POST "$BASE/tabs/$TAB/unlock" \+ -H "Content-Type: application/json" \+ -d '{"owner":"smoke-test"}' | jq .+```++This verifies tab ownership locking works.++## 13. Open A Second Tab++```bash+TAB2=$(curl -s -X POST "$BASE/tab" \+ -H "Content-Type: application/json" \+ -d '{"action":"new","url":"https://example.com"}' \+ | jq -r '.tabId // .id')++echo "$TAB2"+curl -s "$BASE/tabs" | jq .+```++This confirms the bridge handles multiple tabs in one runtime.++## Optional: Evaluate JavaScript++This only works if `evaluate` is enabled in config.++```bash+curl -s -X POST "$BASE/tabs/$TAB/evaluate" \+ -H "Content-Type: application/json" \+ -d '{"expression":"document.title"}' | jq .+```++## Optional: Use The Top-Level Shorthand Endpoints++```bash+curl -s -X POST "$BASE/navigate" \+ -H "Content-Type: application/json" \+ -d '{"url":"https://example.com"}' | jq .++curl -s "$BASE/snapshot?filter=interactive" | jq .+```++These verify the direct bridge shortcuts in addition to the tab-scoped endpoints.++## What This Example Proves++If the full sequence works, your bridge runtime can:+- start and respond to API requests+- manage multiple tabs+- inspect page structure and text+- execute actions+- render visual outputs+- support locking and basic browser state APIs++If this example fails, check:+- the bridge is running on `127.0.0.1:9867`+- Chrome can be started successfully+- required features such as `evaluate` are enabled before testing themdiff --git a/docs/guides/expert-bridge-mode.md b/docs/guides/expert-bridge-mode.mdindex 3af158b6..f969828e 100644--- a/docs/guides/expert-bridge-mode.md+++ b/docs/guides/expert-bridge-mode.md@@ -60,6 +60,8 @@ curl -X POST http://localhost:9867/navigate \curl http://localhost:9867/snapshot?filter=interactive```+For a broader end-to-end check, see [Example: Bridge Smoke Test](../examples/bridge-smoke-test.md).+## Configuration ModelBridge mode still uses the same `config.json` and operational env surface:diff --git a/docs/index.json b/docs/index.jsonindex 8e2debe7..b7a2682d 100644--- a/docs/index.json+++ b/docs/index.json@@ -17,6 +17,7 @@],"architecture": ["architecture/pinchtab-architecture.md",+ "architecture/overall-system-chart.md","architecture/instance-model-charts.md","architecture/managed-bridge-vs-managed-direct-cdp.md","architecture/chrome-lifecycle-and-orchestration.md",@@ -34,6 +35,9 @@"guides/data-storage.md","guides/raspberry-pi.md"],+ "examples": [+ "examples/bridge-smoke-test.md"+ ],"proposals": ["proposals/default-instance.md","proposals/performance-optimization.md",diff --git a/internal/bridge/crash.go b/internal/bridge/crash.goindex 21807379..454274ff 100644--- a/internal/bridge/crash.go+++ b/internal/bridge/crash.go@@ -1,7 +1,10 @@package bridgeimport (+ "context""log/slog"+ "sync"+ "sync/atomic""time""github.com/chromedp/cdproto/inspector"@@ -9,19 +12,72 @@ import ("github.com/chromedp/chromedp")+const maxRecentCrashes = 20+// CrashEvent contains information about a crashtype CrashEvent struct {- Time time.Time- TargetID string- TabID string- URL string- Reason string- LastError string+ Time time.Time `json:"time"`+ TargetID string `json:"targetId,omitempty"`+ TabID string `json:"tabId,omitempty"`+ URL string `json:"url,omitempty"`+ Reason string `json:"reason"`+ LastError string `json:"lastError,omitempty"`}// CrashHandler is called when a crash is detectedtype CrashHandler func(event CrashEvent)+var (+ crashMu sync.Mutex+ recentCrashEvents []CrashEvent+ crashEventsTotal uint64+)++func recordCrashEvent(ev CrashEvent) {+ if ev.Time.IsZero() {+ ev.Time = time.Now()+ }+ atomic.AddUint64(&crashEventsTotal, 1)+ crashMu.Lock()+ defer crashMu.Unlock()+ recentCrashEvents = append(recentCrashEvents, ev)+ if len(recentCrashEvents) > maxRecentCrashes {+ recentCrashEvents = append([]CrashEvent(nil), recentCrashEvents[len(recentCrashEvents)-maxRecentCrashes:]...)+ }+}++// CrashSnapshot returns recent crash diagnostics for /health and /metrics.+func CrashSnapshot() map[string]any {+ crashMu.Lock()+ recent := append([]CrashEvent(nil), recentCrashEvents...)+ crashMu.Unlock()+ return map[string]any{+ "total": atomic.LoadUint64(&crashEventsTotal),+ "recent": recent,+ }+}++// HasCrashDiagnostics reports whether any crash events have been recorded.+func HasCrashDiagnostics() bool {+ crashMu.Lock()+ recentCount := len(recentCrashEvents)+ crashMu.Unlock()+ return atomic.LoadUint64(&crashEventsTotal) > 0 || recentCount > 0+}++// ResetCrashMonitoringForTests clears crash diagnostics state.+func ResetCrashMonitoringForTests() {+ atomic.StoreUint64(&crashEventsTotal, 0)+ crashMu.Lock()+ recentCrashEvents = nil+ crashMu.Unlock()+}++// RecordCrashForTests injects a crash event for diagnostics tests.+func RecordCrashForTests(ev CrashEvent) {+ recordCrashEvent(ev)+}+// MonitorCrashes listens for browser and tab crashesfunc (b *Bridge) MonitorCrashes(handler CrashHandler) {if b.BrowserCtx == nil {@@ -33,28 +89,32 @@ func (b *Bridge) MonitorCrashes(handler CrashHandler) {chromedp.ListenTarget(b.BrowserCtx, func(ev interface{}) {switch e := ev.(type) {case *inspector.EventTargetCrashed:+ event := CrashEvent{+ Time: time.Now(),+ Reason: "inspector.targetCrashed",+ }+ recordCrashEvent(event)slog.Error("🔥 TARGET CRASHED","event", "inspector.targetCrashed",)if handler != nil {- handler(CrashEvent{- Time: time.Now(),- Reason: "inspector.targetCrashed",- })+ handler(event)}case *target.EventTargetCrashed:+ event := CrashEvent{+ Time: time.Now(),+ TargetID: string(e.TargetID),+ Reason: e.Status,+ }+ recordCrashEvent(event)slog.Error("🔥 TARGET CRASHED","targetId", e.TargetID,"status", e.Status,"errorCode", e.ErrorCode,)if handler != nil {- handler(CrashEvent{- Time: time.Now(),- TargetID: string(e.TargetID),- Reason: e.Status,- })+ handler(event)}case *target.EventTargetDestroyed:@@ -66,18 +126,20 @@ func (b *Bridge) MonitorCrashes(handler CrashHandler) {go func() {<-b.BrowserCtx.Done()err := b.BrowserCtx.Err()+ if err == nil || err == context.Canceled {+ slog.Info("browser context ended", "reason", "context canceled")+ return+ }+ event := CrashEvent{+ Time: time.Now(),+ Reason: err.Error(),+ }+ recordCrashEvent(event)slog.Warn("🔥 BROWSER CONTEXT ENDED","error", err,)if handler != nil {- reason := "context cancelled"- if err != nil {- reason = err.Error()- }- handler(CrashEvent{- Time: time.Now(),- Reason: reason,- })+ handler(event)}}()diff --git a/internal/handlers/health_tabs.go b/internal/handlers/health_tabs.goindex 75064324..fd65cb3f 100644--- a/internal/handlers/health_tabs.go+++ b/internal/handlers/health_tabs.go@@ -5,6 +5,7 @@ import ("net/http""time"+ "github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/web")@@ -33,6 +34,12 @@ func (h *Handlers) HandleHealth(w http.ResponseWriter, r *http.Request) {if crashLogs := h.Bridge.GetCrashLogs(); len(crashLogs) > 0 {resp["crashLogs"] = crashLogs}+ if hasFailureDiagnostics() {+ resp["failures"] = FailureSnapshot()+ }+ if bridge.HasCrashDiagnostics() {+ resp["crashes"] = bridge.CrashSnapshot()+ }web.JSON(w, 200, resp)}@@ -48,6 +55,12 @@ func (h *Handlers) HandleEnsureChrome(w http.ResponseWriter, r *http.Request) {func (h *Handlers) HandleMetrics(w http.ResponseWriter, r *http.Request) {result := map[string]any{"metrics": SnapshotMetrics()}+ if hasFailureDiagnostics() {+ result["failures"] = FailureSnapshot()+ }+ if bridge.HasCrashDiagnostics() {+ result["crashes"] = bridge.CrashSnapshot()+ }// Aggregate memory metrics across all tabsif h.Bridge != nil {diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.goindex 5faf8a5c..574c26d6 100644--- a/internal/handlers/health_tabs_test.go+++ b/internal/handlers/health_tabs_test.go@@ -395,3 +395,40 @@ func TestHandleHealth_Response(t *testing.T) {t.Errorf("expected application/json, got %s", ct)}}++func TestHandleHealth_IncludesFailureAndCrashDiagnostics(t *testing.T) {+ resetObservabilityForTests()+ bridge.ResetCrashMonitoringForTests()+ recordFailureEvent(FailureEvent{+ Time: time.Now(),+ RequestID: "req_123",+ Method: "GET",+ Path: "/tabs/bad",+ Status: 500,+ Type: "http_error",+ })+ bridge.RecordCrashForTests(bridge.CrashEvent{+ Time: time.Now(),+ Reason: "target crashed",+ })++ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)+ req := httptest.NewRequest("GET", "/health", nil)+ w := httptest.NewRecorder()+ h.HandleHealth(w, req)++ if w.Code != 200 {+ t.Fatalf("expected 200, got %d", w.Code)+ }++ var resp map[string]any+ if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {+ t.Fatalf("failed to parse response: %v", err)+ }+ if _, ok := resp["failures"]; !ok {+ t.Fatal("expected failures diagnostics in /health response")+ }+ if _, ok := resp["crashes"]; !ok {+ t.Fatal("expected crashes diagnostics in /health response")+ }+}diff --git a/internal/handlers/metrics.go b/internal/handlers/metrics.goindex c8a36065..35b7c474 100644--- a/internal/handlers/metrics.go+++ b/internal/handlers/metrics.go@@ -35,6 +35,7 @@ func SnapshotMetrics() map[string]any {return map[string]any{"requestsTotal": total,"requestsFailed": failed,+ "panicsRecovered": atomic.LoadUint64(&metricPanicsRecovered),"avgLatencyMs": avgMs,"rateLimited": atomic.LoadUint64(&metricRateLimited),"staleRefRetries": atomic.LoadUint64(&metricStaleRefRetries),diff --git a/internal/handlers/middleware.go b/internal/handlers/middleware.goindex 6c301626..a5fed666 100644--- a/internal/handlers/middleware.go+++ b/internal/handlers/middleware.go@@ -22,6 +22,7 @@ var (metricRequestLatencyN uint64metricRateLimited uint64metricStaleRefRetries uint64+ metricPanicsRecovered uint64)func LoggingMiddleware(next http.Handler) http.Handler {@@ -34,6 +35,14 @@ func LoggingMiddleware(next http.Handler) http.Handler {atomic.AddUint64(&metricRequestLatencyN, ms)if sw.Code >= 400 {atomic.AddUint64(&metricRequestsFailed, 1)+ recordFailureEvent(FailureEvent{+ Time: time.Now(),+ RequestID: w.Header().Get("X-Request-Id"),+ Method: r.Method,+ Path: r.URL.Path,+ Status: sw.Code,+ Type: "http_error",+ })}slog.Info("request","requestId", w.Header().Get("X-Request-Id"),diff --git a/internal/handlers/middleware_test.go b/internal/handlers/middleware_test.goindex 1333628a..4659aefe 100644--- a/internal/handlers/middleware_test.go+++ b/internal/handlers/middleware_test.go@@ -160,6 +160,7 @@ func TestCorsMiddleware(t *testing.T) {}func TestLoggingMiddleware(t *testing.T) {+ resetObservabilityForTests()handler := LoggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {w.WriteHeader(201)}))@@ -173,6 +174,32 @@ func TestLoggingMiddleware(t *testing.T) {}}+func TestLoggingMiddleware_RecordsFailure(t *testing.T) {+ resetObservabilityForTests()+ handler := RequestIDMiddleware(LoggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ w.WriteHeader(http.StatusInternalServerError)+ })))++ req := httptest.NewRequest("GET", "/boom", nil)+ w := httptest.NewRecorder()+ handler.ServeHTTP(w, req)++ snap := FailureSnapshot()+ if got := snap["requestsFailed"].(uint64); got != 1 {+ t.Fatalf("requestsFailed = %d, want 1", got)+ }+ recent, ok := snap["recent"].([]FailureEvent)+ if !ok || len(recent) != 1 {+ t.Fatalf("recent failures = %#v, want 1 event", snap["recent"])+ }+ if recent[0].Path != "/boom" {+ t.Fatalf("recent path = %q, want /boom", recent[0].Path)+ }+ if recent[0].RequestID == "" {+ t.Fatal("expected request id on failure event")+ }+}+func TestRequestIDMiddleware_SetsHeader(t *testing.T) {handler := RequestIDMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {w.WriteHeader(200)diff --git a/internal/handlers/observability.go b/internal/handlers/observability.gonew file mode 100644index 00000000..c9f92cc4--- /dev/null+++ b/internal/handlers/observability.go@@ -0,0 +1,73 @@+package handlers++import (+ "sync"+ "sync/atomic"+ "time"+)++const maxRecentFailures = 20++// FailureEvent records a recent HTTP failure for bridge-side diagnostics.+type FailureEvent struct {+ Time time.Time `json:"time"`+ RequestID string `json:"requestId,omitempty"`+ Method string `json:"method"`+ Path string `json:"path"`+ Status int `json:"status"`+ Type string `json:"type"`+}++var (+ failureMu sync.Mutex+ recentFailures []FailureEvent+)++func recordFailureEvent(ev FailureEvent) {+ failureMu.Lock()+ defer failureMu.Unlock()++ recentFailures = append(recentFailures, ev)+ if len(recentFailures) > maxRecentFailures {+ recentFailures = append([]FailureEvent(nil), recentFailures[len(recentFailures)-maxRecentFailures:]...)+ }+}++// RecordRecoveredPanic increments recovered panic monitoring for bridge HTTP handlers.+func RecordRecoveredPanic() {+ atomic.AddUint64(&metricPanicsRecovered, 1)+}++// FailureSnapshot returns recent failure diagnostics for /health and /metrics.+func FailureSnapshot() map[string]any {+ failureMu.Lock()+ recent := append([]FailureEvent(nil), recentFailures...)+ failureMu.Unlock()++ return map[string]any{+ "requestsFailed": atomic.LoadUint64(&metricRequestsFailed),+ "panicsRecovered": atomic.LoadUint64(&metricPanicsRecovered),+ "recent": recent,+ }+}++func hasFailureDiagnostics() bool {+ failureMu.Lock()+ recentCount := len(recentFailures)+ failureMu.Unlock()+ return atomic.LoadUint64(&metricRequestsFailed) > 0 ||+ atomic.LoadUint64(&metricPanicsRecovered) > 0 ||+ recentCount > 0+}++func resetObservabilityForTests() {+ atomic.StoreUint64(&metricRequestsTotal, 0)+ atomic.StoreUint64(&metricRequestsFailed, 0)+ atomic.StoreUint64(&metricRequestLatencyN, 0)+ atomic.StoreUint64(&metricRateLimited, 0)+ atomic.StoreUint64(&metricStaleRefRetries, 0)+ atomic.StoreUint64(&metricPanicsRecovered, 0)+ failureMu.Lock()+ recentFailures = nil+ failureMu.Unlock()+}