Skip to content

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.go
index 69a15a11..d037713e 100644
--- a/cmd/pinchtab/cmd_bridge.go
+++ b/cmd/pinchtab/cmd_bridge.go
@@ -1,11 +1,9 @@
package main
import (
- "bufio"
"context"
"fmt"
"log/slog"
- "net"
"net/http"
"os"
"os/signal"
@@ -48,7 +46,7 @@ func runBridgeServer(cfg *config.RuntimeConfig) {
// HTTP server
server := &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.md
new file mode 100644
index 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.md
index 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 Model
The 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 agents
3. **Ref stability** — Snapshot refs (e0, e1...) are cached and reused by action endpoints
4. **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 Layout
diff --git a/docs/examples/pinchtab-bridge.md b/docs/examples/pinchtab-bridge.md
new file mode 100644
index 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 them
diff --git a/docs/examples/pinchtab.md b/docs/examples/pinchtab.md
new file mode 100644
index 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 them
diff --git a/docs/guides/expert-bridge-mode.md b/docs/guides/expert-bridge-mode.md
index 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 Model
Bridge mode still uses the same `config.json` and operational env surface:
diff --git a/docs/index.json b/docs/index.json
index 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.go
index 21807379..454274ff 100644
--- a/internal/bridge/crash.go
+++ b/internal/bridge/crash.go
@@ -1,7 +1,10 @@
package bridge
import (
+ "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 crash
type 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 detected
type 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 crashes
func (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.go
index 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 tabs
if h.Bridge != nil {
diff --git a/internal/handlers/health_tabs_test.go b/internal/handlers/health_tabs_test.go
index 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.go
index 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.go
index 6c301626..a5fed666 100644
--- a/internal/handlers/middleware.go
+++ b/internal/handlers/middleware.go
@@ -22,6 +22,7 @@ var (
metricRequestLatencyN uint64
metricRateLimited uint64
metricStaleRefRetries 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.go
index 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.go
new file mode 100644
index 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()
+}