ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(ui): one visibility-aware polling convention, and a ratchet on the rest
Juan Denisf21abe7af5ef
diff --git a/frontend/scripts/check-frontend-boundaries.mjs b/frontend/scripts/check-frontend-boundaries.mjsindex 2109e078..d2b9c9fb 100644--- a/frontend/scripts/check-frontend-boundaries.mjs+++ b/frontend/scripts/check-frontend-boundaries.mjs@@ -34,6 +34,55 @@ const EXTENSION_OWNED_STYLES = [// insecure context, and SSL is optional by policy. This map must stay empty.const LEGACY_CLIPBOARD = new Map();+// Polling belongs to usePolling / useServerQuery({refetchInterval}), which do+// two things a hand-rolled setInterval does not: they never start a request+// while the previous one is still in flight, and they stop entirely while the+// tab is hidden, catching up once on return. A bare setInterval that fetches is+// the documented poller-stampede shape - the page gets slower the longer it is+// left open. Finite legacy baseline with exact counts, so every cleanup shrinks+// it. A genuine non-fetching timer (a clock tick, a countdown) may stay, but it+// is still listed so nothing new slips in unnoticed.+const LEGACY_POLLERS = new Map(Object.entries({+ 'components/dashboard/widgets/renderers.jsx': 1,+ 'components/deploy-console/SuccessBanner.jsx': 1,+ 'components/docker/ContainersTab.jsx': 2,+ 'components/monitoring/DoctorPanel.jsx': 1,+ 'components/security/ScannerTab.jsx': 2,+ 'components/security/VulnerabilityTab.jsx': 1,+ 'components/server/OnboardingWizard.jsx': 2,+ 'components/serverdetail/ServicesTab.jsx': 1,+ 'components/servers/LinkPanelForm.jsx': 1,+ 'components/service-detail/LogsTab.jsx': 1,+ 'components/service-detail/MetricsTab.jsx': 1,+ 'components/service-detail/OverviewTab.jsx': 1,+ 'hooks/useContainerStatus.js': 1,+ 'hooks/useDeployJobStream.js': 1,+ 'hooks/useMetrics.js': 1,+ 'pages/Dashboard.jsx': 4,+ 'pages/Databases.jsx': 1,+ 'pages/DeliveryLog.jsx': 1,+ 'pages/DeployConsole.jsx': 1,+ 'pages/Deployments.jsx': 1,+ 'pages/ImportWizard.jsx': 1,+ 'pages/Jobs.jsx': 1,+ 'pages/MonitorDetail.jsx': 1,+ 'pages/Monitors.jsx': 2,+ 'pages/QueueDetail.jsx': 1,+ 'pages/QueueOperations.jsx': 1,+ 'pages/ServerDetail.jsx': 1,+ 'pages/Terminal.jsx': 3,+ 'pages/TestSandbox.jsx': 2,+ 'plugins/serverkit-gui/components/ServerGui.jsx': 1,+ 'plugins/serverkit-gui/components/SyntheticDesktop.jsx': 1,+}));++// The polling door itself, plus the query hook that wraps it.+const POLLING_DOOR = new Set([+ 'utils/pollScheduler.js',+ 'hooks/usePolling.js',+ 'hooks/useServerQuery.js',+]);+// These are purpose-built experiences whose geometry/content is intentionally// richer than the ordinary Modal contract. Any new exception needs review.const LOW_LEVEL_DIALOG_EXCEPTIONS = new Set([@@ -52,6 +101,7 @@ function walk(dir) {const files = walk(src).filter((path) => ['.js', '.jsx'].includes(extname(path)));const failures = [];const seenClipboard = new Set();+const seenPollers = new Set();function rel(path) {return relative(src, path).replaceAll('\\', '/');@@ -74,6 +124,15 @@ for (const path of files) {if (expected) seenClipboard.add(file);}+ if (!POLLING_DOOR.has(file)) {+ const actual = count(source, /setInterval\s*\(/g);+ const expected = LEGACY_POLLERS.get(file) || 0;+ if (actual !== expected) {+ failures.push(`${file}: raw setInterval count is ${actual}; legacy baseline is ${expected}. Use usePolling() (or useServerQuery({refetchInterval})) and shrink the baseline.`);+ }+ if (expected) seenPollers.add(file);+ }+if (/(?:(?:window|globalThis)\s*\.\s*)?confirm\s*\(\s*['"`]/m.test(source)) {failures.push(`${file}: use useConfirm() instead of the browser confirm dialog.`);}@@ -117,6 +176,12 @@ for (const file of LEGACY_CLIPBOARD.keys()) {}}+for (const file of LEGACY_POLLERS.keys()) {+ if (!seenPollers.has(file)) {+ failures.push(`${file}: legacy poller entry is stale; remove it from the boundary baseline.`);+ }+}+const mainStylesPath = resolve(src, 'styles', 'main.scss');const mainStyles = readFileSync(mainStylesPath, 'utf8');for (const ownership of EXTENSION_OWNED_STYLES) {@@ -159,4 +224,4 @@ if (failures.length) {process.exit(1);}-console.log(`✓ frontend boundaries: browser/API/dialog boundaries and ${EXTENSION_OWNED_STYLES.length} extension style ownership rule(s) hold (${LEGACY_CLIPBOARD.size} clipboard files remain ratcheted).`);+console.log(`✓ frontend boundaries: browser/API/dialog boundaries and ${EXTENSION_OWNED_STYLES.length} extension style ownership rule(s) hold (${LEGACY_CLIPBOARD.size} clipboard / ${LEGACY_POLLERS.size} poller files remain ratcheted).`);diff --git a/frontend/src/components/DeployPill.jsx b/frontend/src/components/DeployPill.jsxindex 44fc5486..7541c053 100644--- a/frontend/src/components/DeployPill.jsx+++ b/frontend/src/components/DeployPill.jsx@@ -3,6 +3,7 @@ import { Link, useLocation } from 'react-router-dom';import { Loader2 } from 'lucide-react';import api from '../services/api';import socketService from '../services/socket';+import { usePolling } from '../hooks/usePolling';// A small global "deploy in progress" pill: while any deployment job is// pending/running it appears (bottom-left) so you can navigate away mid-deploy@@ -49,30 +50,19 @@ export default function DeployPill() {}}, []);+ // The interval, the hidden-tab pause, and the catch-up on return are the+ // shared convention now; this component was where they were first worked+ // out by hand.+ usePolling(refresh, POLL_MS, { enabled: !onDeploySurface });+useEffect(() => {if (onDeploySurface) return undefined;-- // Polling a background tab buys nothing and competes for the browser's- // per-origin connections with whatever the visible tab is doing.- const tick = () => {- if (document.visibilityState !== 'visible') return;- refresh();- };- tick();- const t = setInterval(tick, POLL_MS);-- // Catch up once when the tab comes back rather than polling all along.- const onVisible = () => { if (document.visibilityState === 'visible') refresh(); };- document.addEventListener('visibilitychange', onVisible);-// React quickly to live status changes when a console elsewhere is// streaming — but a burst of deploy_status events must not become a// burst of requests, so the in-flight guard covers these too.const unsubStatus = socketService.on('deploy_status', refresh);const unsubConnect = socketService.on('connected', refresh);return () => {- clearInterval(t);- document.removeEventListener('visibilitychange', onVisible);unsubStatus();unsubConnect();};diff --git a/frontend/src/components/appdetail/LogsTab.jsx b/frontend/src/components/appdetail/LogsTab.jsxindex 7f3c7069..fe991f56 100644--- a/frontend/src/components/appdetail/LogsTab.jsx+++ b/frontend/src/components/appdetail/LogsTab.jsx@@ -2,6 +2,9 @@ import { useState, useEffect } from 'react';import { logsToText } from '@/utils/logText';import api from '../../services/api';import { Button } from '@/components/ui/button';+import { usePolling } from '../../hooks/usePolling';++const LOG_REFRESH_MS = 5000;const LogsTab = ({ app }) => {const [logs, setLogs] = useState('');@@ -15,11 +18,9 @@ const LogsTab = ({ app }) => {loadLogs();}, [app.id]);- useEffect(() => {- if (!autoRefresh) return;- const interval = setInterval(loadLogs, 5000);- return () => clearInterval(interval);- }, [autoRefresh, app.id]);+ // immediate: false — the effect above already loads on mount and on app+ // change; this adds only the repeat while auto-refresh is on.+ usePolling(loadLogs, LOG_REFRESH_MS, { enabled: autoRefresh, immediate: false });async function loadLogs() {try {diff --git a/frontend/src/components/databases/ProcessListPanel.jsx b/frontend/src/components/databases/ProcessListPanel.jsxindex 3648d360..c6f9644b 100644--- a/frontend/src/components/databases/ProcessListPanel.jsx+++ b/frontend/src/components/databases/ProcessListPanel.jsx@@ -3,6 +3,7 @@ import { Ban, Activity, TimerReset } from 'lucide-react';import api from '../../services/api';import { useToast } from '../../contexts/ToastContext';import { useConfirm } from '../../hooks/useConfirm';+import { usePolling } from '../../hooks/usePolling';import EmptyState from '../EmptyState';import { DataTable, DataTableFooter, SearchField } from '@/components/ds';import {@@ -114,11 +115,10 @@ export default function ProcessListPanel({ conn, engine, active, isAdmin }) {useEffect(() => { load(); }, [load]);- useEffect(() => {- if (!active || !autoRefresh) return undefined;- const t = setInterval(() => load(true), REFRESH_MS);- return () => clearInterval(t);- }, [active, autoRefresh, load]);+ usePolling(() => load(true), REFRESH_MS, {+ enabled: active && autoRefresh,+ immediate: false, // the effect above already loaded once+ });async function killProcess(proc) {const verb = engineKind === 'postgresql' ? 'Terminate' : 'Kill';diff --git a/frontend/src/components/monitoring/MonitorsSummary.jsx b/frontend/src/components/monitoring/MonitorsSummary.jsxindex b15d3550..a65cb5be 100644--- a/frontend/src/components/monitoring/MonitorsSummary.jsx+++ b/frontend/src/components/monitoring/MonitorsSummary.jsx@@ -5,13 +5,14 @@// machines ServerKit runs on, and nothing described the things it is supposed to// be watching. Host health stays below; this sits above it because "is the site// up" is the question the page is actually for.-import { useCallback, useEffect, useRef, useState } from 'react';+import { useCallback, useEffect, useState } from 'react';import { Link, useNavigate } from 'react-router-dom';import { Activity, Plus, Radar, ShieldAlert, Timer, Zap } from 'lucide-react';import api from '../../services/api';import { AreaChart, KpiBand, MetricCard, Pill } from '@/components/ds';import { Button } from '@/components/ui/button';import { monitorStateOf } from './monitorShared';+import { usePolling } from '../../hooks/usePolling';const POLL_MS = 15000;const FEED_LIMIT = 9;@@ -32,7 +33,6 @@ export default function MonitorsSummary({ refreshKey = 0 }) {const [stats, setStats] = useState(null);const [feed, setFeed] = useState([]);const [loaded, setLoaded] = useState(false);- const pollRef = useRef(null);const load = useCallback(async () => {try {@@ -60,11 +60,13 @@ export default function MonitorsSummary({ refreshKey = 0 }) {}}, []);+ const refresh = usePolling(load, POLL_MS);++ // The parent bumps refreshKey to force a reload (e.g. after creating a+ // monitor); it is not part of the polling schedule.useEffect(() => {- load();- pollRef.current = setInterval(load, POLL_MS);- return () => clearInterval(pollRef.current);- }, [load, refreshKey]);+ if (refreshKey) refresh();+ }, [refreshKey, refresh]);if (!loaded) return null;diff --git a/frontend/src/hooks/usePolling.js b/frontend/src/hooks/usePolling.jsnew file mode 100644index 00000000..dd9130e3--- /dev/null+++ b/frontend/src/hooks/usePolling.js@@ -0,0 +1,84 @@+import { useCallback, useEffect, useRef } from 'react';++import { createPollScheduler, DEFAULT_INTERVAL_MS } from '@/utils/pollScheduler';++// One convention for "keep this fresh while the user is looking at it".+//+// usePolling(loadStatus, 5000);+// usePolling(loadLogs, 3000, { enabled: autoRefresh });+//+// Replaces the `useEffect(() => { const t = setInterval(load, 5000); return+// () => clearInterval(t); })` block, which this codebase had ~47 of and which+// gets two things wrong every time:+//+// * it starts a new request every 5s whether or not the last one came back,+// so a slow endpoint turns into a growing pile of concurrent requests;+// * it keeps polling a tab nobody is looking at.+//+// The scheduling itself lives in utils/pollScheduler.js so it can be tested+// without a DOM; this is the React binding.+//+// `callback` is held in a ref, so an inline arrow re-created every render does+// NOT restart the timer — the usual reason a hand-rolled poller silently polls+// far faster than its stated interval.+//+// Returns a stable `refresh()` for "reload now" buttons, which goes through the+// same in-flight guard.+export function usePolling(callback, intervalMs = DEFAULT_INTERVAL_MS, options = {}) {+ const {+ enabled = true,+ immediate = true,+ pauseWhenHidden = true,+ onError,+ } = options;++ const callbackRef = useRef(callback);+ const onErrorRef = useRef(onError);+ callbackRef.current = callback;+ onErrorRef.current = onError;++ const schedulerRef = useRef(null);++ useEffect(() => {+ if (!enabled || !intervalMs) return undefined;++ const scheduler = createPollScheduler({+ run: () => callbackRef.current?.(),+ intervalMs,+ setTimer: (fn, ms) => window.setTimeout(fn, ms),+ clearTimer: (handle) => window.clearTimeout(handle),+ isHidden: () => (+ pauseWhenHidden+ && typeof document !== 'undefined'+ && document.visibilityState === 'hidden'+ ),+ onError: (error) => onErrorRef.current?.(error),+ });+ schedulerRef.current = scheduler;+ scheduler.start({ runNow: immediate });++ let onVisibility;+ if (pauseWhenHidden && typeof document !== 'undefined') {+ onVisibility = () => scheduler.setHidden(document.visibilityState === 'hidden');+ document.addEventListener('visibilitychange', onVisibility);+ }++ return () => {+ if (onVisibility) document.removeEventListener('visibilitychange', onVisibility);+ scheduler.stop();+ schedulerRef.current = null;+ };+ }, [enabled, intervalMs, immediate, pauseWhenHidden]);++ return useCallback(() => {+ const scheduler = schedulerRef.current;+ if (scheduler) {+ scheduler.refresh();+ return;+ }+ // Disabled or unmounted: a manual refresh should still do the work.+ callbackRef.current?.();+ }, []);+}++export default usePolling;diff --git a/frontend/src/hooks/useServerQuery.js b/frontend/src/hooks/useServerQuery.jsindex 98960e92..ef6c660f 100644--- a/frontend/src/hooks/useServerQuery.js+++ b/frontend/src/hooks/useServerQuery.js@@ -1,6 +1,7 @@import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';import { useWorkspace } from '../contexts/WorkspaceContext';import { queryClient, serializeQueryKey } from '../services/queryClient';+import { usePolling } from './usePolling';const workspaceKey = (workspaceId, queryKey) => ['workspace', workspaceId, ...queryKey];@@ -8,6 +9,11 @@ export function useServerQuery(queryKey, queryFn, options = {}) {const {enabled = true,staleTime = 0,+ // Keep this key fresh on an interval. Two things a hand-rolled+ // setInterval next to a useState does not get: the query client already+ // dedupes concurrent fetches of the same key, and the scheduler below+ // stops entirely while the tab is hidden, catching up once on return.+ refetchInterval = 0,onError,} = options;const { activeWorkspaceId } = useWorkspace();@@ -60,6 +66,13 @@ export function useServerQuery(queryKey, queryFn, options = {}) {[scopedKeyHash, staleTime],);+ usePolling(refetch, refetchInterval, {+ enabled: enabled && refetchInterval > 0,+ // The mount effect above already fetched; polling adds the *repeat*.+ immediate: false,+ onError: (error) => onErrorRef.current?.(error),+ });+return {...state,isLoading: state.status === 'idle' || state.status === 'loading',diff --git a/frontend/src/utils/__tests__/pollScheduler.test.mjs b/frontend/src/utils/__tests__/pollScheduler.test.mjsnew file mode 100644index 00000000..396d6027--- /dev/null+++ b/frontend/src/utils/__tests__/pollScheduler.test.mjs@@ -0,0 +1,313 @@+import assert from 'node:assert/strict';+import test from 'node:test';++import { createPollScheduler } from '../pollScheduler.js';++// A hand-driven clock. The scheduler only ever talks to timers through the+// injected pair, so a test can advance time deterministically.+function fakeClock() {+ let next = 1;+ const pending = new Map();+ return {+ setTimer(fn, ms) {+ const id = next++;+ pending.set(id, { fn, ms });+ return id;+ },+ clearTimer(id) { pending.delete(id); },+ /** Fire every timer currently scheduled (one round). */+ async fire() {+ const round = [...pending.entries()];+ round.forEach(([id]) => pending.delete(id));+ round.forEach(([, t]) => t.fn());+ await Promise.resolve();+ await Promise.resolve();+ },+ get scheduled() { return pending.size; },+ };+}++function deferred() {+ let resolve;+ let reject;+ const promise = new Promise((res, rej) => { resolve = res; reject = rej; });+ return { promise, resolve, reject };+}+++test('runs immediately on start, then on each tick', async () => {+ const clock = fakeClock();+ let runs = 0;+ const poller = createPollScheduler({+ run: () => { runs += 1; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ assert.equal(runs, 1, 'start() should run once immediately');++ await clock.fire();+ assert.equal(runs, 2);+ await clock.fire();+ assert.equal(runs, 3);++ poller.stop();+});+++test('start({runNow:false}) waits for the first interval', async () => {+ const clock = fakeClock();+ let runs = 0;+ const poller = createPollScheduler({+ run: () => { runs += 1; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start({ runNow: false });+ assert.equal(runs, 0);+ await clock.fire();+ assert.equal(runs, 1);+ poller.stop();+});+++test('the schedule itself can never overlap a request', async () => {+ // The stampede this module exists to prevent. Note the schedule cannot+ // produce one *structurally*: the next timer is armed by the previous run+ // finishing, so while a request is in flight there is no timer at all.+ // That is the property worth pinning — a guard you can also delete without+ // any test noticing would be no guard.+ const clock = fakeClock();+ const first = deferred();+ let starts = 0;+ const poller = createPollScheduler({+ run: () => { starts += 1; return first.promise; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ assert.equal(starts, 1);+ assert.equal(clock.scheduled, 0, 'no timer may be armed while a request is in flight');++ await clock.fire();+ await clock.fire();+ assert.equal(starts, 1, 'nothing to fire, so nothing stacked');++ first.resolve();+ await Promise.resolve();+ await Promise.resolve();++ await clock.fire();+ assert.equal(starts, 2, 'polling resumes once the request settles');+ poller.stop();+});+++test('out-of-band runs are what the in-flight guard actually protects', async () => {+ // refresh() and the visibility catch-up bypass the schedule, so they are+ // the paths that CAN land on top of a request in flight.+ const clock = fakeClock();+ const pending = deferred();+ let starts = 0;+ const poller = createPollScheduler({+ run: () => { starts += 1; return pending.promise; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ isHidden: () => false,+ });++ poller.start();+ assert.equal(starts, 1);++ poller.refresh();+ poller.refresh();+ poller.setHidden(false); // a catch-up while the first is still open+ poller.start(); // and a redundant start++ assert.equal(starts, 1, 'none of these may stack a second request');+ assert.equal(poller.skippedTicks, 4);++ pending.resolve();+ await Promise.resolve();+ await Promise.resolve();+ await clock.fire();+ assert.equal(starts, 2);+ poller.stop();+});+++test('a skipped tick does not queue up a burst afterwards', async () => {+ // Skipping must mean "drop it", not "remember it". Otherwise the stampede+ // just arrives later, all at once.+ const clock = fakeClock();+ const slow = deferred();+ let starts = 0;+ const poller = createPollScheduler({+ run: () => { starts += 1; return starts === 1 ? slow.promise : Promise.resolve(); },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ for (let i = 0; i < 5; i += 1) await clock.fire();+ assert.equal(starts, 1);++ slow.resolve();+ await Promise.resolve();+ await Promise.resolve();++ await clock.fire();+ assert.equal(starts, 2, 'exactly one run, not five');+ assert.equal(clock.scheduled, 1, 'and exactly one timer outstanding');+ poller.stop();+});+++test('the gap is measured after the work finishes, not tick to tick', async () => {+ const clock = fakeClock();+ let starts = 0;+ let pendingRun = deferred();+ const poller = createPollScheduler({+ run: () => { starts += 1; return pendingRun.promise; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ assert.equal(clock.scheduled, 0, 'nothing is scheduled while work is in flight');++ pendingRun.resolve();+ await Promise.resolve();+ await Promise.resolve();+ assert.equal(clock.scheduled, 1, 'the next tick is scheduled only once work settled');++ pendingRun = deferred();+ await clock.fire();+ assert.equal(starts, 2);+ poller.stop();+});+++test('stops polling while the tab is hidden and catches up when it returns', async () => {+ const clock = fakeClock();+ let hidden = false;+ let runs = 0;+ const poller = createPollScheduler({+ run: () => { runs += 1; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ isHidden: () => hidden,+ });++ poller.start();+ assert.equal(runs, 1);++ hidden = true;+ poller.setHidden(true);+ assert.equal(clock.scheduled, 0, 'no timer should be armed for a hidden tab');+ await clock.fire();+ assert.equal(runs, 1, 'a hidden tab must not poll');++ hidden = false;+ poller.setHidden(false);+ assert.equal(runs, 2, 'coming back runs once immediately to catch up');++ await clock.fire();+ assert.equal(runs, 3, 'and resumes the schedule');+ poller.stop();+});+++test('stop() cancels the outstanding timer', async () => {+ const clock = fakeClock();+ let runs = 0;+ const poller = createPollScheduler({+ run: () => { runs += 1; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ poller.stop();+ assert.equal(clock.scheduled, 0);+ await clock.fire();+ assert.equal(runs, 1, 'no further runs after stop()');+ assert.equal(poller.isRunning, false);+});+++test('a rejected run does not wedge the poller', async () => {+ // If a failed request left inFlight true, the poller would go silent+ // forever — the worst failure mode, because the page looks live.+ const clock = fakeClock();+ let starts = 0;+ const errors = [];+ const poller = createPollScheduler({+ run: () => { starts += 1; return Promise.reject(new Error('boom')); },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ onError: (error) => errors.push(error.message),+ });++ poller.start();+ await Promise.resolve();+ await Promise.resolve();++ assert.deepEqual(errors, ['boom'], 'the failure is surfaced, not swallowed');++ await clock.fire();+ assert.equal(starts, 2, 'polling continues after a failure');+ assert.equal(poller.isInFlight, false);+ poller.stop();+});+++test('a synchronously throwing run does not wedge the poller either', async () => {+ const clock = fakeClock();+ let starts = 0;+ const poller = createPollScheduler({+ run: () => { starts += 1; throw new Error('sync boom'); },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ onError: () => {},+ });++ poller.start();+ assert.equal(poller.isInFlight, false);+ await clock.fire();+ assert.equal(starts, 2);+ poller.stop();+});+++test('refresh() honours the in-flight guard', async () => {+ const clock = fakeClock();+ const pending = deferred();+ let starts = 0;+ const poller = createPollScheduler({+ run: () => { starts += 1; return pending.promise; },+ intervalMs: 1000,+ setTimer: clock.setTimer,+ clearTimer: clock.clearTimer,+ });++ poller.start();+ poller.refresh();+ poller.refresh();+ assert.equal(starts, 1, 'a manual refresh must not stack either');+ pending.resolve();+ poller.stop();+});diff --git a/frontend/src/utils/pollScheduler.js b/frontend/src/utils/pollScheduler.jsnew file mode 100644index 00000000..8083a55b--- /dev/null+++ b/frontend/src/utils/pollScheduler.js@@ -0,0 +1,127 @@+// The scheduling rules behind usePolling, as a plain object so they can be+// tested without a DOM.+//+// Two rules, both of which every hand-rolled `setInterval(load, 5000)` in this+// codebase got wrong:+//+// 1. NEVER let a tick start while the previous one is still in flight. A poller+// on a 5s interval against a request that has started taking 30s does not+// slow down — it stacks, and each new request makes the server slower, which+// makes the next request more likely to overlap. That is the stampede: the+// page gets slower the longer you leave it open, and the server sees a load+// it never sees in a fresh session.+//+// 2. Do not poll a tab nobody is looking at. A background tab polling every 5s+// is pure cost, and browsers throttle its timers unevenly anyway, so it is+// not even a reliable refresh. Catch up ONCE when it comes back instead —+// which is also what makes the data fresh at the moment someone looks.+//+// A skipped tick is not a dropped update: the next one takes its place, and the+// in-flight request that caused the skip is delivering the same data.++export const DEFAULT_INTERVAL_MS = 5000;++/**+ * @param {object} config+ * @param {() => (Promise<any>|any)} config.run the work to repeat+ * @param {number} config.intervalMs delay BETWEEN runs+ * @param {(fn: Function, ms: number) => any} config.setTimer+ * @param {(handle: any) => void} config.clearTimer+ * @param {() => boolean} [config.isHidden] document.hidden, injected+ * @param {(error: any) => void} [config.onError]+ */+export function createPollScheduler({+ run,+ intervalMs = DEFAULT_INTERVAL_MS,+ setTimer,+ clearTimer,+ isHidden = () => false,+ onError,+}) {+ let handle = null;+ let inFlight = false;+ let stopped = true;+ let skipped = 0;++ const clear = () => {+ if (handle !== null) {+ clearTimer(handle);+ handle = null;+ }+ };++ // A timeout chained after each run, not setInterval: with setInterval the+ // delay is measured from tick to tick regardless of how long the work took,+ // so slow work silently turns a 5s gap into no gap at all.+ const schedule = () => {+ clear();+ if (stopped || isHidden()) return;+ handle = setTimer(tick, intervalMs);+ };++ function tick() {+ handle = null;+ if (stopped) return;+ if (inFlight) {+ // Rule 1. Do not queue behind it; the next tick will do.+ skipped += 1;+ schedule();+ return;+ }+ if (isHidden()) return; // rule 2; onVisible() resumes++ let result;+ inFlight = true;+ try {+ result = run();+ } catch (error) {+ inFlight = false;+ onError?.(error);+ schedule();+ return;+ }++ if (!result || typeof result.then !== 'function') {+ inFlight = false;+ schedule();+ return;+ }++ result.then(+ () => { inFlight = false; schedule(); },+ (error) => { inFlight = false; onError?.(error); schedule(); },+ );+ }++ return {+ /** Begin polling. `runNow` performs the first run immediately. */+ start({ runNow = true } = {}) {+ stopped = false;+ if (runNow) tick();+ else schedule();+ },+ stop() {+ stopped = true;+ clear();+ },+ /** Visibility changed. Coming back runs once immediately to catch up. */+ setHidden(hidden) {+ if (stopped) return;+ if (hidden) clear();+ else tick();+ },+ /** Run now, outside the schedule, honouring the in-flight guard. */+ refresh() {+ if (stopped) {+ stopped = false;+ }+ tick();+ },+ /** Test/diagnostic surface. */+ get isRunning() { return !stopped; },+ get isInFlight() { return inFlight; },+ get skippedTicks() { return skipped; },+ };+}++export default createPollScheduler;