Retry with Backoff & Jitter

Retrying on a fixed interval turns one flaky dependency into a synchronised stampede - every client retries at the same instant. Exponential backoff spaces the attempts out; jitter, a random delay inside the backoff window, is what stops all the clients lining up on the same schedule again.

@itsnas usage.ts

codeusage.ts

// @src/code/retry
const report = await retry(() => fetchJSON('/api/report'), {
  retries: 5,
  shouldRetry: error =>
    error instanceof HttpError && error.status >= 500,
})

main

Nas (@itsnas)

interface RetryOptions {
  retries?: number // retries after the first try (default 3)
  baseMs?: number // backoff for the first retry (default 300)
  maxMs?: number // upper bound on any single delay (default 10_000)
  shouldRetry?: (error: unknown) => boolean // default: always
}
 
export async function retry<T>(
  task: () => Promise<T>,
  options: RetryOptions = {},
): Promise<T> {
  const {
    retries = 3,
    baseMs = 300,
    maxMs = 10_000,
    shouldRetry = () => true,
  } = options
 
  for (let attempt = 0; ; attempt++) {
    try {
      return await task()
    } catch (error) {
      if (attempt >= retries || !shouldRetry(error)) throw error
      await sleep(backoffMs(attempt, baseMs, maxMs))
    }
  }
}
 
// 2^attempt growth, then "full jitter": a random point in
// [0, window], so clients that failed together don't retry together.
function backoffMs(attempt: number, baseMs: number, maxMs: number): number {
  const window = Math.min(maxMs, baseMs * 2 ** attempt)
  return Math.random() * window
}
 
function sleep(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms))
}

main

Nas (@itsnas)