Activities, Retries, And Idempotency

Activities are where side effects belong. Workflow code decides what should happen; activity code talks to the outside world.

defmodule MyApp.Activities.ChargeCard do
  use Continuum.Activity,
    retry: [max_attempts: 5, backoff: :exponential, base_ms: 500],
    timeout: {:seconds, 30}

  @impl true
  def run(%{order_id: order_id, amount: amount}) do
    MyApp.Payments.charge(order_id, amount)
  end

  @impl true
  def idempotency_key([%{order_id: order_id}]) do
    "charge:#{order_id}"
  end
end

Call an activity from a workflow with the activity macro:

{:ok, charge} =
  activity MyApp.Activities.ChargeCard.run(%{order_id: order_id, amount: total}),
    retry: [max_attempts: 5, backoff: :exponential, base_ms: 500],
    idempotency_key: "charge:#{order_id}"

The Postgres runtime inserts a row in continuum_activity_tasks. The activity dispatcher leases available tasks with FOR UPDATE SKIP LOCKED, starts a worker, and the worker journals either activity_completed or activity_failed.

The built-in executor runs at most 10 activities concurrently per Continuum instance by default. Configure the limit globally or for a named instance:

config :continuum, activity_max_concurrency: 25

Continuum.children(
  name: :billing,
  repo: MyApp.Repo,
  activity_max_concurrency: 8
)

The dispatcher claims only currently available capacity. Saturated polls use jittered backpressure and emit queue-age, saturation, and rejected-claim telemetry. Oban-backed instances continue to use their Oban queue limits.

Retry policy is resolved in this order:

1. The activity ... retry: ... option at the call site.
2. The use Continuum.Activity, retry: ... module option.
3. A single attempt.

Activity policy is validated before durable work is scheduled. max_attempts must be positive, backoff must be :constant or :exponential, and base_ms must be non-negative. max_backoff_ms defaults to one minute and caps each delay. max_retry_horizon_ms defaults to 24 hours and must cover the worst-case execution time plus every delay. Per-attempt timeouts must be positive and cannot exceed 24 hours.

backoff: :exponential uses base_ms * 2 ^ (attempt - 1), capped by max_backoff_ms. Use an explicit policy for longer horizons:

retry: [
  max_attempts: 8,
  backoff: :exponential,
  base_ms: 500,
  max_backoff_ms: 60_000,
  max_retry_horizon_ms: 3_600_000
]

Idempotency keys are enforced by the Postgres runtime. Once an activity result is committed for an activity module and key, another task with the same module and key journals that committed result without running the activity body again.

An idempotency key must be a binary or nil, whether it comes from the call site or idempotency_key/1. Invalid keys fail the run before a task is written.

This guarantee starts after Continuum commits success. Activities that perform externally visible writes, such as payments, emails, or third-party API mutations, should still pass their own idempotency key to the external system. That closes the remaining window where a worker can crash after the external write succeeds but before Continuum commits the result.

See guides/idempotency.md for the exact scope.