Skip to content

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

refine network body mode contract

Mario4cec2cde362e
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 2944818b..1338f13a 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -475,13 +475,16 @@ Network query parameters:
- `limit`
- `bufferSize`
- `body=true` on detail requests
-- `waitRetained=true` on detail requests to wait briefly for asynchronous retained-body capture instead of failing over immediately
+- `bodyMode=auto|retained-preferred|retained-only|live-only` on detail requests to choose how response bodies are resolved
- `timeoutMs` on detail requests to bound the retained-body wait window (default 2000, max 30000)
Response body behavior for network detail/export:
- by default, response bodies are fetched on demand from live CDP state and may no longer be available for older requests
- when `server.retainNetworkBodies=true`, PinchTab opportunistically retains bounded response bodies in the in-memory network buffer and returns the retained body first
+- `bodyMode=retained-preferred` waits briefly for pending retained-body capture before falling back to live CDP
+- `bodyMode=retained-only` never falls back to live CDP and returns explicit pending/skipped/error state instead
+- detail responses may expose `bodySource=retained|live` to distinguish which path produced the returned body
- retained-body detail responses may expose `bodyPending=true` while capture is still in flight, or `bodySkipped=true` with `bodySkipReason` when retention was intentionally not completed
- retained bodies are capped by `server.retainNetworkBodyMaxBytes`; oversized retained bodies are truncated and marked with `bodyTruncated=true`
- retained responses may include `bodyRetained=true`
diff --git a/internal/bridge/observe/network.go b/internal/bridge/observe/network.go
index cff2cccd..b0b5ec26 100644
--- a/internal/bridge/observe/network.go
+++ b/internal/bridge/observe/network.go
@@ -564,6 +564,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBu
entry.BodyPending = false
entry.BodySkipped = true
entry.BodySkipReason = "retention disabled"
+ entry.BodyError = ""
})
return
}
@@ -572,7 +573,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBu
entry.BodyPending = false
entry.BodySkipped = true
entry.BodySkipReason = "retention budget exceeded"
- entry.BodyError = "retention budget exceeded"
+ entry.BodyError = ""
})
return
}
@@ -584,7 +585,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBu
entry.BodyPending = false
entry.BodySkipped = true
entry.BodySkipReason = "retention concurrency limit reached"
- entry.BodyError = "retention concurrency limit reached"
+ entry.BodyError = ""
})
return
}
@@ -592,6 +593,8 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBu
if err != nil {
buf.Update(requestID, func(entry *NetworkEntry) {
entry.BodyPending = false
+ entry.BodySkipped = false
+ entry.BodySkipReason = ""
entry.BodyError = err.Error()
})
return
@@ -607,7 +610,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBu
entry.BodyPending = false
entry.BodySkipped = true
entry.BodySkipReason = "retention budget exceeded"
- entry.BodyError = "retention budget exceeded"
+ entry.BodyError = ""
})
return
}
diff --git a/internal/handlers/network.go b/internal/handlers/network.go
index 534badb2..c0246fee 100644
--- a/internal/handlers/network.go
+++ b/internal/handlers/network.go
@@ -17,6 +17,15 @@ const (
maxWaitRetainedTimeout = 30 * time.Second
)
+type networkBodyMode string
+
+const (
+ networkBodyModeAuto networkBodyMode = "auto"
+ networkBodyModeRetainedPreferred networkBodyMode = "retained-preferred"
+ networkBodyModeRetainedOnly networkBodyMode = "retained-only"
+ networkBodyModeLiveOnly networkBodyMode = "live-only"
+)
+
// parseBufferSize extracts an optional bufferSize query param. Returns 0 if absent.
func parseBufferSize(r *http.Request) int {
if v := r.URL.Query().Get("bufferSize"); v != "" {
@@ -36,6 +45,24 @@ func parseBoolQuery(value string) bool {
}
}
+func parseNetworkBodyMode(r *http.Request) networkBodyMode {
+ switch strings.ToLower(strings.TrimSpace(r.URL.Query().Get("bodyMode"))) {
+ case "", "auto":
+ return networkBodyModeAuto
+ case "retained-preferred", "retainedpreferred":
+ return networkBodyModeRetainedPreferred
+ case "retained-only", "retainedonly":
+ return networkBodyModeRetainedOnly
+ case "live-only", "liveonly":
+ return networkBodyModeLiveOnly
+ default:
+ if parseBoolQuery(r.URL.Query().Get("waitRetained")) {
+ return networkBodyModeRetainedPreferred
+ }
+ return networkBodyModeAuto
+ }
+}
+
func parseWaitRetainedTimeout(r *http.Request) time.Duration {
if v := r.URL.Query().Get("timeoutMs"); v != "" {
if n, err := strconv.Atoi(v); err == nil {
@@ -85,6 +112,7 @@ func populateRetainedBodyResult(result map[string]any, entry bridge.NetworkEntry
}
if entry.BodyRetained {
result["bodyRetained"] = true
+ result["bodySource"] = "retained"
}
if entry.BodyPending {
result["bodyPending"] = true
@@ -103,6 +131,14 @@ func populateRetainedBodyResult(result map[string]any, entry bridge.NetworkEntry
}
}
+func populateLiveBodyResult(result map[string]any, body string, base64Encoded bool) {
+ result["responseBody"] = body
+ result["bodySource"] = "live"
+ if base64Encoded {
+ result["base64Encoded"] = true
+ }
+}
+
// HandleNetwork lists recent network entries for a tab.
//
// @Endpoint GET /network
@@ -242,8 +278,8 @@ func (h *Handlers) HandleNetworkByID(w http.ResponseWriter, r *http.Request) {
// Optionally include response body
if r.URL.Query().Get("body") == "true" && entry.Finished && !entry.Failed {
- waitRetained := parseBoolQuery(r.URL.Query().Get("waitRetained"))
- if waitRetained && entry.BodyPending {
+ bodyMode := parseNetworkBodyMode(r)
+ if bodyMode == networkBodyModeRetainedPreferred && entry.BodyPending {
entry, ok = waitForRetainedBody(buf, requestID, parseWaitRetainedTimeout(r))
if !ok {
httpx.Error(w, 404, fmt.Errorf("request %s not found", requestID))
@@ -251,24 +287,26 @@ func (h *Handlers) HandleNetworkByID(w http.ResponseWriter, r *http.Request) {
}
result["entry"] = entry
}
- if entry.BodyRetained {
+ switch {
+ case bodyMode == networkBodyModeLiveOnly:
+ body, base64Encoded, err := bridge.GetResponseBodyDirect(tabCtx, requestID)
+ if err != nil {
+ result["bodyError"] = err.Error()
+ } else {
+ populateLiveBodyResult(result, body, base64Encoded)
+ }
+ case entry.BodyRetained:
+ populateRetainedBodyResult(result, entry)
+ case bodyMode == networkBodyModeRetainedOnly:
populateRetainedBodyResult(result, entry)
- } else if entry.BodyPending || (entry.BodyError != "" && !entry.BodySkipped) {
+ case entry.BodyPending || entry.BodyError != "":
populateRetainedBodyResult(result, entry)
- } else {
+ default:
body, base64Encoded, err := bridge.GetResponseBodyDirect(tabCtx, requestID)
if err != nil {
result["bodyError"] = err.Error()
} else {
- buf.Update(requestID, func(entry *bridge.NetworkEntry) {
- entry.ResponseBody = body
- entry.Base64Encoded = base64Encoded
- entry.BodyRetained = true
- entry.BodyError = ""
- })
- result["responseBody"] = body
- result["base64Encoded"] = base64Encoded
- result["bodyRetained"] = true
+ populateLiveBodyResult(result, body, base64Encoded)
}
}
populateRetainedBodyResult(result, entry)
diff --git a/internal/handlers/network_test.go b/internal/handlers/network_test.go
index 179422d1..cd1739c8 100644
--- a/internal/handlers/network_test.go
+++ b/internal/handlers/network_test.go
@@ -257,7 +257,7 @@ func TestHandleNetworkByIDUsesRetainedBody(t *testing.T) {
}
}
-func TestHandleNetworkByIDWaitRetainedReturnsBodyAfterPendingResolves(t *testing.T) {
+func TestHandleNetworkByIDRetainedPreferredReturnsBodyAfterPendingResolves(t *testing.T) {
nm := bridge.NewNetworkMonitor(100)
buf := nm.GetOrCreateBufferForTest("tab1")
buf.Add(bridge.NetworkEntry{
@@ -279,7 +279,7 @@ func TestHandleNetworkByIDWaitRetainedReturnsBodyAfterPendingResolves(t *testing
})
}()
- req := httptest.NewRequest("GET", "/network/pending-1?body=true&waitRetained=true&timeoutMs=250", nil)
+ req := httptest.NewRequest("GET", "/network/pending-1?body=true&bodyMode=retained-preferred&timeoutMs=250", nil)
req.SetPathValue("requestId", "pending-1")
w := httptest.NewRecorder()
h.HandleNetworkByID(w, req)
@@ -297,6 +297,9 @@ func TestHandleNetworkByIDWaitRetainedReturnsBodyAfterPendingResolves(t *testing
if got["bodyRetained"] != true {
t.Fatalf("expected bodyRetained=true, got %v", got["bodyRetained"])
}
+ if got["bodySource"] != "retained" {
+ t.Fatalf("expected bodySource=retained, got %v", got["bodySource"])
+ }
if _, ok := got["bodyPending"]; ok {
t.Fatalf("expected bodyPending to clear after wait, got %v", got["bodyPending"])
}
@@ -309,7 +312,7 @@ func TestHandleNetworkByIDWaitRetainedReturnsBodyAfterPendingResolves(t *testing
}
}
-func TestHandleNetworkByIDWaitRetainedTimeoutReturnsPendingState(t *testing.T) {
+func TestHandleNetworkByIDRetainedPreferredTimeoutReturnsPendingState(t *testing.T) {
nm := bridge.NewNetworkMonitor(100)
buf := nm.GetOrCreateBufferForTest("tab1")
buf.Add(bridge.NetworkEntry{
@@ -322,7 +325,7 @@ func TestHandleNetworkByIDWaitRetainedTimeoutReturnsPendingState(t *testing.T) {
})
h := newNetworkTestHandler(nm)
- req := httptest.NewRequest("GET", "/network/pending-timeout?body=true&waitRetained=true&timeoutMs=20", nil)
+ req := httptest.NewRequest("GET", "/network/pending-timeout?body=true&bodyMode=retained-preferred&timeoutMs=20", nil)
req.SetPathValue("requestId", "pending-timeout")
w := httptest.NewRecorder()
h.HandleNetworkByID(w, req)
@@ -352,6 +355,86 @@ func TestHandleNetworkByIDWaitRetainedTimeoutReturnsPendingState(t *testing.T) {
}
}
+func TestHandleNetworkByIDRetainedOnlyReturnsSkippedStateWithoutBodyError(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ buf := nm.GetOrCreateBufferForTest("tab1")
+ buf.Add(bridge.NetworkEntry{
+ RequestID: "skipped-1",
+ URL: "https://api.example.com/data",
+ Method: "GET",
+ ResourceType: "XHR",
+ Finished: true,
+ BodySkipped: true,
+ BodySkipReason: "retention budget exceeded",
+ })
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/skipped-1?body=true&bodyMode=retained-only", nil)
+ req.SetPathValue("requestId", "skipped-1")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+ var got map[string]any
+ if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if got["bodySkipped"] != true {
+ t.Fatalf("expected bodySkipped=true, got %v", got["bodySkipped"])
+ }
+ if got["bodySkipReason"] != "retention budget exceeded" {
+ t.Fatalf("expected bodySkipReason to be preserved, got %v", got["bodySkipReason"])
+ }
+ if _, ok := got["bodyError"]; ok {
+ t.Fatalf("expected no bodyError for skipped retention, got %v", got["bodyError"])
+ }
+ if _, ok := got["responseBody"]; ok {
+ t.Fatalf("expected no responseBody in retained-only skip state, got %v", got["responseBody"])
+ }
+}
+
+func TestHandleNetworkByIDRetainedPreferredDoesNotPretendSkippedBodyWasRetained(t *testing.T) {
+ nm := bridge.NewNetworkMonitor(100)
+ seedBuffer(nm, "tab1")
+ buf := nm.GetOrCreateBufferForTest("tab1")
+ buf.Update("r1", func(entry *bridge.NetworkEntry) {
+ entry.BodySkipped = true
+ entry.BodySkipReason = "retention disabled"
+ })
+ h := newNetworkTestHandler(nm)
+
+ req := httptest.NewRequest("GET", "/network/r1?body=true&bodyMode=retained-preferred", nil)
+ req.SetPathValue("requestId", "r1")
+ w := httptest.NewRecorder()
+ h.HandleNetworkByID(w, req)
+
+ if w.Code != 200 {
+ t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+ }
+ var got map[string]any
+ if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+ t.Fatalf("decode: %v", err)
+ }
+ if _, ok := got["bodyRetained"]; ok {
+ t.Fatalf("expected no bodyRetained marker for skipped retention, got %v", got["bodyRetained"])
+ }
+ if got["bodySkipped"] != true {
+ t.Fatalf("expected skip state to remain visible, got %v", got["bodySkipped"])
+ }
+ if got["bodySkipReason"] != "retention disabled" {
+ t.Fatalf("expected skip reason to remain visible, got %v", got["bodySkipReason"])
+ }
+ entryMap, ok := got["entry"].(map[string]any)
+ if !ok {
+ t.Fatalf("expected entry map, got %T", got["entry"])
+ }
+ if entryMap["bodySkipped"] != true {
+ t.Fatalf("expected nested entry bodySkipped=true, got %v", entryMap["bodySkipped"])
+ }
+}
+
func TestHandleNetworkByID_Found(t *testing.T) {
nm := bridge.NewNetworkMonitor(100)
seedBuffer(nm, "tab1")
diff --git a/tests/e2e/scenarios/api/network-retain-body.sh b/tests/e2e/scenarios/api/network-retain-body.sh
index cc23930d..433753d7 100644
--- a/tests/e2e/scenarios/api/network-retain-body.sh
+++ b/tests/e2e/scenarios/api/network-retain-body.sh
@@ -31,7 +31,7 @@ fi
echo -e " ${GREEN}✓${NC} found request id: $REQ_ID"
((ASSERTIONS_PASSED++)) || true
-DETAIL=$(e2e_curl -s "${E2E_SERVER}/network/${REQ_ID}?body=true&waitRetained=true&timeoutMs=2000")
+DETAIL=$(e2e_curl -s "${E2E_SERVER}/network/${REQ_ID}?body=true&bodyMode=retained-preferred&timeoutMs=2000")
echo "$DETAIL" | jq -e '.bodyRetained == true' >/dev/null 2>&1
if [ $? -eq 0 ]; then
@@ -43,6 +43,16 @@ else
((ASSERTIONS_FAILED++)) || true
fi
+echo "$DETAIL" | jq -e '.bodySource == "retained"' >/dev/null 2>&1
+if [ $? -eq 0 ]; then
+ echo -e " ${GREEN}✓${NC} bodySource=retained"
+ ((ASSERTIONS_PASSED++)) || true
+else
+ echo -e " ${RED}✗${NC} expected bodySource=retained"
+ echo "$DETAIL" | jq .
+ ((ASSERTIONS_FAILED++)) || true
+fi
+
echo "$DETAIL" | jq -e '.responseBody | contains("retained-body-ok")' >/dev/null 2>&1
if [ $? -eq 0 ]; then
echo -e " ${GREEN}✓${NC} retained response body contains expected payload"