Skip to content

BackoffSupervisor — restart with exponential backoff + jitter #48

@pathosDev

Description

@pathosDev

Today an actor that crashes restarts immediately under the default `SupervisorStrategy`. Akka has `BackoffSupervisor.props(...)` for the common case where you want exponential backoff between restarts — typically because the failure is transient (DB hiccup, broker reconnect window) and immediate restart just hammers the broken dependency.

API:

```ts
const supervisor = system.actorOf(
BackoffSupervisor.props({
childProps: Props.create(() => new MyFlaky()),
minBackoff: 200, // ms
maxBackoff: 10_000, // ms
randomFactor: 0.2, // ±20% jitter
resetCounter: 'after-success', // or 'after-time:60s'
}),
'flaky-supervisor',
);
```

The supervisor wraps a single child, watches it, and on `Terminated` reschedules a restart according to the backoff policy. Counter resets after a successful run window OR after the next message (configurable).

Components:

File Task
`src/pattern/BackoffSupervisor.ts` (new) Public class + factory.
`src/pattern/BackoffPolicy.ts` (new) Pure policy object: `(retryCount, lastFailureTs) => delayMs`. Two built-ins: `exponential` and `linear`.
`tests/unit/pattern/BackoffSupervisor.test.ts` (new) Restart-after-delay, jitter is bounded, counter reset works.

Estimate: 2 days.

Verification:

  • Round-trip: child crashes 3× in a row, observed restart delays are ~ `min × 2^n` ± jitter.
  • Counter reset: child runs successfully for `resetCounter` window, then crashes — first restart uses `minBackoff` again.

Out of scope:

  • Cluster-aware backoff (not needed — supervision is local to the parent).

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority: highTop priority — high impact, plan next

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions