feat(dev,html-app): pause long-polling when Webhooks HTML app tab is hidden

Author: azasypkin

dev/tools/AGENTS.md

@@ -2400,6 +2400,78 @@ exception still releases the lock. The Parse-button restoration in the
 `finally` is separate (`els.parseBtn.disabled = !pdfFile`) because their
 disabled state mirrors file-loaded state, not the snapshot.
 
+## Live updates / polling (visibility-aware)
+
+Any tool that polls or long-polls a backend (repeated `fetch`, `EventSource`, or a
+long-poll loop like the webhook inspector's `secutils.kv.watch`) **MUST**:
+
+- **Abort the in-flight request and stop scheduling new ones when the tab is hidden**
+  (`visibilitychange` -> `document.hidden`) and on `pagehide` (navigation / close / bfcache).
+- **Re-establish from the last cursor when the tab becomes visible again.**
+
+Rationale: a backgrounded or closed tab that keeps polling wastes server work for output
+nobody is looking at. For a long-poll it is worse - each open request parks a **server-side
+V8 isolate (+ worker thread)** for the whole window, and with the safe actix default
+(`h1_allow_half_closed = true`) the server **cannot** detect the client disconnect on its own
+(it only notices on its next socket write, which a parked long-poll never does). So the client
+is the only party that can promptly close the connection - it must do so itself.
+
+Model the loop as two pieces of state: **intent** (the user toggled it on; drives the toggle
+pill) and **running** (a request loop is actually open). Pausing for visibility clears
+*running* but preserves *intent*, so it resumes transparently.
+
+Canonical shape (reference implementation: [`dev/tools/webhook.html`](webhook.html)):
+
+```js
+let abort = null;       // AbortController for the in-flight request
+let running = false;    // a request loop is actually open
+let enabled = false;    // user intent (drives the toggle UI)
+
+// Record intent + reflect it in the UI, but only open a connection while visible.
+function start() {
+    enabled = true;
+    // ...reflect enabled in the toggle UI here...
+    if (!document.hidden) runLoop();
+}
+function runLoop() {
+    if (running) return;            // idempotent
+    running = true;
+    abort = new AbortController();
+    (async () => {
+        while (running /* && still-current */) {
+            try {
+                const res = await fetch(url, { signal: abort.signal });
+                /* ...handle response, advance cursor... */
+            } catch (e) {
+                if (e.name === 'AbortError') break;
+                await sleep(2000);
+            }
+        }
+    })();
+}
+// Pause WITHOUT clearing intent, so visibility can resume it from the last cursor.
+function pauseLoop() {
+    running = false;
+    if (abort) { try { abort.abort(); } catch {} abort = null; }
+}
+// Explicit user-off: clears intent + UI, then pauses.
+function stop() {
+    enabled = false;
+    // ...reflect disabled in the toggle UI here...
+    pauseLoop();
+}
+
+document.addEventListener('visibilitychange', () => {
+    if (document.hidden) { if (running) pauseLoop(); }
+    else if (enabled && !running) runLoop();
+});
+window.addEventListener('pagehide', () => { if (running) pauseLoop(); });
+```
+
+**Agent instruction:** when building a new tool, or adding any polling / long-polling to an
+existing one, implement this pattern and **explicitly confirm with the developer** that the
+visibility-abort + resume wiring is in place before considering the tool done.
+
 ## Pre-deploy verification
 
 After editing any tool, run these checks before `make deploy-tools`. They take seconds,

dev/tools/webhook.html

@@ -63,7 +63,10 @@
   // *is* enabled it only clamps the deadline shorter; it can never extend it.
   const LIFESPAN_FALLBACK_SEC = 604800; // 7 days.
   const PAGE_LIMIT = 200;
-  const WATCH_TIMEOUT_MS = 25000;
+  // Long-poll window. Kept short so a watch that ever outlives its client (e.g. an abrupt
+  // kill the client can't intercept) parks a server-side V8 isolate for at most this long
+  // before the worker is reclaimed. The client also aborts proactively on hide/close.
+  const WATCH_TIMEOUT_MS = 15000;
   // Remaining seconds until the webhook's absolute deadline (`exp`, unix seconds),
   // so dependent writes never outlive the key. Floors at 1s so a near-deadline
   // write still lands rather than being rejected as a zero/negative TTL.
@@ -1151,7 +1154,9 @@ <h2 id="confirmDialogTitle">Confirm</h2>
 }
 
 async function activateSession(session, { register }) {
-    stopLive();
+    // Pause (not stop) so the user's live intent carries over and resumes for the new
+    // session via the `if (liveEnabled) startLive()` below.
+    pauseLoop();
     current = session;
     setActive(session.t);
     upsertSession(session);
@@ -1334,11 +1339,24 @@ <h2 id="confirmDialogTitle">Confirm</h2>
 }
 
 // ---- live watch (long-poll loop) ----
+// Three-state model: `liveEnabled` is the user's intent (pill state), `liveRunning` is
+// whether a fetch loop is actually open. We keep these separate so the loop can be paused
+// (e.g. while the tab is hidden) without losing the user's intent, and transparently
+// resumed when the tab becomes visible again.
+
+// startLive() records intent and reflects it in the pill, but only opens a connection when
+// the tab is visible - a backgrounded tab would otherwise park a server-side V8 isolate
+// (one per long-poll) for nothing.
 function startLive() {
-    if (liveRunning || !current) return;
-    liveRunning = true;
+    if (!current) return;
     liveEnabled = true;
     els.liveToggle.setAttribute('aria-checked', 'true');
+    if (!document.hidden) runLiveLoop();
+}
+// The actual long-poll loop. Idempotent: a no-op if already running.
+function runLiveLoop() {
+    if (liveRunning || !current) return;
+    liveRunning = true;
     watchAbort = new AbortController();
     (async () => {
         const token = current.t;
@@ -1357,11 +1375,35 @@ <h2 id="confirmDialogTitle">Confirm</h2>
         }
     })();
 }
-function stopLive() {
+// Pause the loop and FIN the in-flight connection WITHOUT clearing user intent, so it can
+// be resumed (e.g. on visibility change) from the last `cursor`.
+function pauseLoop() {
     liveRunning = false;
-    els.liveToggle.setAttribute('aria-checked', 'false');
     if (watchAbort) { try { watchAbort.abort(); } catch {} watchAbort = null; }
 }
+// Explicit user-off: clears intent, unchecks the pill, and pauses the loop.
+function stopLive() {
+    liveEnabled = false;
+    els.liveToggle.setAttribute('aria-checked', 'false');
+    pauseLoop();
+}
+
+// Don't hold a server-side long-poll open for a tab nobody is looking at: pause when hidden,
+// resume from the last cursor when visible. User intent (`liveEnabled` + pill) is preserved
+// across hide/show. With the safe actix default the server can't detect the disconnect on
+// its own, so the client must close the connection itself.
+document.addEventListener('visibilitychange', () => {
+    if (document.hidden) {
+        if (liveRunning) pauseLoop();
+    } else if (liveEnabled && !liveRunning) {
+        runLiveLoop();
+    }
+});
+// On navigation / close / bfcache, drop the in-flight watch so the connection FINs promptly
+// instead of lingering server-side until the watch window elapses.
+window.addEventListener('pagehide', () => {
+    if (liveRunning) pauseLoop();
+});
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 // ---- mock response editor ----
@@ -1565,7 +1607,7 @@ <h2 id="confirmDialogTitle">Confirm</h2>
 });
 els.refreshBtn.addEventListener('click', () => refresh());
 els.liveToggle.addEventListener('click', () => {
-    if (liveRunning) { liveEnabled = false; stopLive(); }
+    if (liveEnabled) stopLive();
     else startLive();
 });
 els.clearBtn.addEventListener('click', async () => {
@@ -1617,7 +1659,6 @@ <h2 id="confirmDialogTitle">Confirm</h2>
         confirmLabel: 'Delete webhook',
     });
     if (!ok) return;
-    liveEnabled = false;
     stopLive();
     els.deleteBtn.disabled = true;
     const token = current.t;