Retry
이 콘텐츠는 아직 번역되지 않았습니다.
retry is a pure async function for “try this call up to N times,
with backoff between attempts.” It’s the simplest layer in the
resilience stack — no actors, no state, just a Promise-returning
factory.
import { retry } from 'actor-ts';
const data = await retry( () => fetch('https://example.com/items').then(r => r.json()), { attempts: 3, delayMs: 200, factor: 2 },);The factory is called up to 3 times. Each retry waits longer: attempt 1 immediately, attempt 2 after 200 ms, attempt 3 after 400 ms. Returns the first success; rejects with the last error if every attempt fails.
The signature
Section titled “The signature”function retry<T>(factory: () => Promise<T>, options: RetryOptions): Promise<T>;
type RetryOptions = { attempts: number; // total including initial call (>= 1) delayMs?: number; // base delay between attempts factor?: number; // multiplier for exponential backoff (default 1) maxDelayMs?: number; // ceiling for any individual delay (default 60_000) randomFactor?: number; // jitter fraction in [0, 1] (default 0 — none) random?: () => number; // override Math.random in tests shouldRetry?: (err: Error, attempt: number) => boolean; onAttempt?: (err: Error, attempt: number) => void; sleep?: (ms: number) => Promise<void>; // how the delay is awaited};The attempts field is total attempts, not retries — attempts: 1 runs the factory exactly once with no retries. attempts: 3
runs up to 3 times.
Configuring the backoff
Section titled “Configuring the backoff”Four knobs cooperate to control the delay between attempts:
| Setting | What it does |
|---|---|
delayMs | Base delay between attempts. Default 0 (no wait). |
factor | Multiplier per attempt. Delay on attempt N is delayMs × factor^(N-1). Default 1 (constant). |
maxDelayMs | Upper bound on any single delay. Default 60_000 (one minute). Pass Number.POSITIVE_INFINITY for an unbounded schedule — then only the 32-bit timer limit is left, which retry clamps to unconditionally (see the overflow note at the end of this page). |
randomFactor | Jitter fraction in [0, 1]. The delay is spread to delay × (1 ± randomFactor). Default 0 (no jitter). |
A malformed value for any of them is refused where you call
retry, with an OptionsError, before the factory runs once:
delayMs finite and at least 0, factor finite and above 0,
maxDelayMs at least 0 (or Number.POSITIVE_INFINITY for the
unbounded schedule), randomFactor inside [0, 1]. Unchecked they
all arrive at the same place — a computed delay that is NaN,
negative or zero, which the loop skips — so a single mistyped option
would turn the backoff into a hot loop against the dependency that is
already failing. That is the direction the clamp at the end of this
page exists to invert, reached through the options instead of through
the arithmetic, so it is refused rather than clamped: there is no
sensible delay to fall back to when the one you asked for is not a
number.
// Constant 500ms between attempts:retry(factory, { attempts: 5, delayMs: 500 });
// Exponential: 200ms, 400ms, 800ms, capped at 5s:retry(factory, { attempts: 6, delayMs: 200, factor: 2, maxDelayMs: 5_000 });
// Fibonacci-ish: ad-hoc via factor=1.6:retry(factory, { attempts: 5, delayMs: 100, factor: 1.6 });
// Explicitly unbounded — every delay is delayMs × factor^(N-1), up to// the 32-bit timer limit:retry(factory, { attempts: 20, delayMs: 200, factor: 2, maxDelayMs: Number.POSITIVE_INFINITY });The default ceiling
Section titled “The default ceiling”maxDelayMs defaults to 60 000 ms, so an exponential backoff
flattens at one minute per attempt unless you say otherwise. It
used to default to infinity, on the reasoning that a caller who
wants a ceiling asks for one — but what an omitted cap plus
factor > 1 actually converges on is ~24.9 days per attempt (the
timer clamp, below), and nobody configures that on purpose. A
default is what happens when the question was never asked, so it
should be the answer that is sane when nobody thought about it.
Raise it, lower it, or opt back out with
Number.POSITIVE_INFINITY — the option itself has not changed.
Jitter — randomFactor
Section titled “Jitter — randomFactor”Without jitter the delay is a pure function of the attempt number,
so every caller that failed on the same upstream event comes back
in the same millisecond, wave after wave — and a synchronized herd
can hold a recovering service down. randomFactor spreads each
delay to delay × (1 ± randomFactor):
// 200ms, 400ms, 800ms … each ±20%, capped at 5s:retry(factory, { attempts: 6, delayMs: 200, factor: 2, maxDelayMs: 5_000, randomFactor: 0.2,});It defaults to 0, so a retry written before this option keeps
its exact schedule. Turn it on whenever more than one caller can
fail on the same event — a fleet of pods talking to one database, a
fan-out of workers behind one API. 0.2 is the spread
exponentialBackoff and the broker
reconnect loop both default to.
random overrides Math.random, so a jittered schedule stays
exactly assertable in a test — same escape hatch as sleep, below.
Or use BackoffSupervisor if the thing being retried is an actor
restart.
Selective retry — shouldRetry
Section titled “Selective retry — shouldRetry”class TransientError extends Error {}class PermanentError extends Error {}
await retry( () => callExternalAPI(), { attempts: 5, delayMs: 500, factor: 2, shouldRetry: (err) => err instanceof TransientError, },);shouldRetry runs after every failed attempt except the last.
Return false to short-circuit — the retry loop exits
immediately with that error, no more attempts.
Use it to differentiate transient and permanent failures:
- Transient (network blip, rate limit, lock-contention) → retry.
- Permanent (validation error, auth failure, 4xx) → don’t retry; the next attempt will fail the same way.
Observability — onAttempt
Section titled “Observability — onAttempt”await retry(factory, { attempts: 3, delayMs: 500, onAttempt: (err, attempt) => { metrics.counter('retry.attempt').inc({ attempt }); log.warn(`attempt ${attempt} failed: ${err.message}`); },});Fires after every failed attempt, including the final one. Use it for retry-aware metrics and logging — counters per attempt, spans for tracing, alerts on “we ran out of retries.”
Testing the backoff — sleep
Section titled “Testing the backoff — sleep”sleep decides how the delay between attempts is awaited. It
defaults to setTimeout, so you never need it in production —
override it in tests to take the retry loop off the wall clock:
import { retry } from 'actor-ts';import { ManualScheduler } from 'actor-ts/testkit';
const scheduler = new ManualScheduler();const attemptTimes: number[] = [];
await retry( async () => { attemptTimes.push(scheduler.now()); throw new Error('fail'); }, { attempts: 3, delayMs: 20, factor: 2, maxDelayMs: 30, sleep: (ms) => new Promise<void>((resolve) => { scheduler.scheduleOnceFunction(ms, resolve); scheduler.advance(ms); }), },).catch(() => { /* expected */ });
// Exactly 20ms, then 40ms clamped to maxDelayMs — and instant.expect(attemptTimes).toEqual([0, 20, 50]);Every sleep resolves the moment virtual time reaches it, so the
schedule is asserted exactly and the test costs no wall-clock
time. Measuring real gaps instead is a flake waiting to happen:
a 30 ms setTimeout lands anywhere between roughly 19 ms and
200 ms depending on the platform’s timer quantum and machine load,
which is wide enough that a capped delay is indistinguishable
from an uncapped one.
Same escape hatch as random above, and as
exponentialBackoff’s — inject the
non-determinism, then pin it.
Compared to BackoffSupervisor
Section titled “Compared to BackoffSupervisor”| Use case | Reach for… |
|---|---|
A single Promise-returning call (HTTP fetch, DB query, ask) | retry |
| An actor that fails and should be respawned | BackoffSupervisor |
| A call protected by short-circuit behavior | CircuitBreaker (often combined with retry inside) |
retry is the call-level primitive. BackoffSupervisor is
the actor-level primitive. They don’t compete — pick by what
you’re protecting.
For an actor that wants to retry its own downstream call,
retry inside onReceive is fine:
class MyActor extends Actor<...> { override async onReceive(message): Promise<void> { const result = await retry( () => this.callDownstream(message), { attempts: 3, delayMs: 200, factor: 2 }, ); // ... }}Awaiting inside onReceive blocks the actor’s mailbox until the
retry completes — same trade-off as any await inside an
onReceive. See
Ask pattern for when this
is a problem.
Compared to circuit breaker
Section titled “Compared to circuit breaker”A circuit breaker is per-dependency state that says “stop trying this thing for a while.” Retry is per-call logic that says “try again right now after a short wait.”
Combine them — retry inside a breaker call:
breaker.call(() => retry( () => fetch('https://flaky.example'), { attempts: 3, delayMs: 100, factor: 2 },));The retry handles transient blips during a single call; the breaker tracks the trend across many calls.
Where to next
Section titled “Where to next”- Backoff supervisor — the actor-restart equivalent of retry.
- Backoff policy — pure delay-calculation primitives for custom retry loops.
- Circuit breaker — the complementary “stop calling for a while” primitive.
The retry API reference covers
the full signature.
