:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { ApiError } from 'lib/api-error'
// Spread poll ticks ±20% around the base cadence so clients whose runs kicked off together (or whose
// tabs woke together) don't hit the endpoint in lockstep, avoiding a thundering herd on the API.
export const POLL_JITTER_RATIO = 0.2
export function jitteredIntervalMs(baseMs: number, random: () => number = Math.random): number {
return Math.round(baseMs * (1 - POLL_JITTER_RATIO + random() * 2 * POLL_JITTER_RATIO))
}
// Backoff ceiling for consecutive failures/empties, and how many empty ticks ride the base cadence
// before slowing down (a run usually appears within a few ticks; a killswitched or idle endpoint
// should not be polled at full rate forever).
export const MAX_POLL_BACKOFF_MS = 60_000
export const EMPTY_POLLS_BEFORE_BACKOFF = 5
// 401/403 (access revoked), 404 (deleted), 410 (gone): retrying cannot succeed, stop the loop.
export function isPermanentPollError(error: unknown): boolean {
return error instanceof ApiError && [401, 403, 404, 410].includes(error.status ?? 0)
}
export type PollTickOutcome = 'ok' | 'empty' | 'terminal'
export interface PollLoopOptions {
/** Base cadence between ticks; jitter and backoff are applied on top. */
intervalMs: number
/** Fetch + dispatch one snapshot. Classify the result; throw on request failure. */
tick: () => Promise<PollTickOutcome>
/** Called for each failed tick. Return 'stop' to end the loop permanently. */
onError: (error: unknown, consecutiveFailures: number) => 'retry' | 'stop'
/** Checked before each tick; returning true ends the loop permanently. */
shouldStop?: () => boolean
/** Runs when the loop ends itself (terminal tick, error stop, shouldStop) — not on external cleanup. */
onLoopEnd?: () => void
}
/**
* Shared poll loop for the wizard sync transports (task-run and wizard-session polling modes).
* Returns a disposable setup function for `cache.disposables.add`.
*
* Guarantees:
* - Each tick schedules the next one only after its request settles, so a slow server can never
* stack requests, and every gap gets fresh jitter.
* - Consecutive failures back off exponentially (capped at MAX_POLL_BACKOFF_MS) and permanent
* errors stop the loop, so an outage or a deleted resource is not hammered at full cadence.
* - Consecutive empty ticks past EMPTY_POLLS_BEFORE_BACKOFF back off the same way, so an endpoint
* with nothing to report (no session yet, killswitched) winds down instead of polling forever.
*/
export function createPollLoop(options: PollLoopOptions): () => () => void {
return (): (() => void) => {
let cancelled = false
let timer: number | undefined
let consecutiveFailures = 0
let consecutiveEmpty = 0
const nextDelayMs = (): number => {
if (consecutiveFailures > 0) {
return Math.min(options.intervalMs * 2 ** consecutiveFailures, MAX_POLL_BACKOFF_MS)
}
const emptyOverage = consecutiveEmpty - EMPTY_POLLS_BEFORE_BACKOFF
if (emptyOverage >= 0) {
return Math.min(options.intervalMs * 2 ** (emptyOverage + 1), MAX_POLL_BACKOFF_MS)
}
return options.intervalMs
}
const poll = async (): Promise<void> => {
// Re-checked every tick, not just at connect: the disposables plugin re-runs setup on
// tab-visibility resume, so connect-time guards alone would let a stale loop revive.
if (options.shouldStop?.()) {
options.onLoopEnd?.()
return
}
try {
const outcome = await options.tick()
if (cancelled) {
return
}
consecutiveFailures = 0
consecutiveEmpty = outcome === 'empty' ? consecutiveEmpty + 1 : 0
if (outcome === 'terminal') {
options.onLoopEnd?.()
return
}
} catch (error) {
if (cancelled) {
return
}
consecutiveFailures += 1
if (options.onError(error, consecutiveFailures) === 'stop') {
options.onLoopEnd?.()
return
}
}
// A tick's dispatches can synchronously dispose this loop; don't schedule an orphan.
if (!cancelled) {
timer = window.setTimeout(() => void poll(), jitteredIntervalMs(nextDelayMs()))
}
}
void poll()
return () => {
cancelled = true
window.clearTimeout(timer)
}
}
}