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.mdindex 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.goindex 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 *NetworkBuentry.BodyPending = falseentry.BodySkipped = trueentry.BodySkipReason = "retention disabled"+ entry.BodyError = ""})return}@@ -572,7 +573,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBuentry.BodyPending = falseentry.BodySkipped = trueentry.BodySkipReason = "retention budget exceeded"- entry.BodyError = "retention budget exceeded"+ entry.BodyError = ""})return}@@ -584,7 +585,7 @@ func (nm *NetworkMonitor) maybeRetainBody(tabCtx context.Context, buf *NetworkBuentry.BodyPending = falseentry.BodySkipped = trueentry.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 *NetworkBuif 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 *NetworkBuentry.BodyPending = falseentry.BodySkipped = trueentry.BodySkipReason = "retention budget exceeded"- entry.BodyError = "retention budget exceeded"+ entry.BodyError = ""})return}diff --git a/internal/handlers/network.go b/internal/handlers/network.goindex 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 bodyif 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.goindex 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 *testingif 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.shindex 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 @@ fiecho -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>&1if [ $? -eq 0 ]; then@@ -43,6 +43,16 @@ else((ASSERTIONS_FAILED++)) || truefi+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>&1if [ $? -eq 0 ]; thenecho -e " ${GREEN}✓${NC} retained response body contains expected payload"