What it is
A durable task-retry module that runs inside a SpacetimeDB server module, scheduling background work to be attempted repeatedly until it succeeds or exhausts a configured attempt limit, with exponential backoff between attempts and an admin-accessible history of pending tasks and past outcomes.
Where it fits
- Transactional email delivery: Sending order receipts or notifications that may fail due to transient downstream errors and need automatic re-attempts without manual intervention.
- External webhook dispatch: Pushing events to third-party services where the remote endpoint may be temporarily unavailable.
- Payment processing follow-up: Retrying settlement or confirmation steps that are safe to repeat and must eventually complete or be explicitly abandoned.
- Background data enrichment: Kicking off work that depends on an external API, where a single failure should not permanently block the operation.
- Admin-monitored job queues: Any background task where operators need visibility into what is pending and what has failed, without building a separate monitoring layer.
How it works
When a task is submitted, it is stored with its arguments, a maximum attempt count, and a base wait time. The first attempt runs immediately. If the attempt fails, whether by returning an error or throwing an unexpected exception, the module records the outcome and schedules the next attempt after a delay that doubles with each retry. This continues until the task succeeds or the attempt limit is reached.
Handlers are expected to be safe to run more than once for the same input, because the module may execute them multiple times. If a handler determines that the task's arguments are fundamentally invalid rather than transiently failing, it can signal that the task should be abandoned entirely. The module then records the outcome as a permanent give-up and schedules nothing further. Any writes the handler made before signaling failure are still committed as part of that attempt's transaction.
An admin role controls who can submit tasks directly, view pending work, and inspect the attempt history. The history keeps a rolling window of the most recent attempts across all task types, visible to admins newest-first. The publishing identity is automatically seeded as the first admin when the module initializes, and additional admins can be added or removed over time.
