跳转到内容
简体中文

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.

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.

Four knobs cooperate to control the delay between attempts:

SettingWhat it does
delayMsBase delay between attempts. Default 0 (no wait).
factorMultiplier per attempt. Delay on attempt N is delayMs × factor^(N-1). Default 1 (constant).
maxDelayMsUpper 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).
randomFactorJitter 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 });

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.

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.

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.
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.”

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.

Use caseReach for…
A single Promise-returning call (HTTP fetch, DB query, ask)retry
An actor that fails and should be respawnedBackoffSupervisor
A call protected by short-circuit behaviorCircuitBreaker (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.

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.

The retry API reference covers the full signature.