GenServer-based poller for external resources during command execution.

ResourcePoller enables adapters to start background polling of external resources during execute/2, injecting events as the resource status changes. This allows commands to return immediately with an initial event while a poller monitors the resource for subsequent state changes.

Usage Pattern

In an adapter's execute/2, use ctx.start_poller.(opts) to spawn a poller:

def execute(%CreateAuthorization{} = cmd, ctx) do
  {:ok, %{body: %{"id" => id}}} = Req.post(ctx.client, ...)

  _poller = ctx.start_poller.(
    poll_fn: fn -> Req.get(ctx.client, url: "/authorizations/#{id}") end,
    interval_ms: 500,
    timeout_ms: 30_000,
    handler: fn response ->
      case response.body["status"] do
        "processing" -> :continue
        "pending_review" -> {:inject, %AuthorizationPendingReview{id: id}}
        "approved" -> {:done, %AuthorizationApproved{id: id}}
        "declined" -> {:done, %AuthorizationDeclined{id: id}}
      end
    end
  )

  {:ok, [%AuthorizationCreated{id: id, status: :processing}]}
end

Handler Return Values

The reason in {:error, reason} can be any term, including an exception struct for structured error reporting:

# Simple string error
{:error, "Payment gateway timeout"}

# Exception for structured errors
{:error, %PaymentError{code: :gateway_timeout, details: response}}

When an exception is used, the framework will use Exception.message/1 for cleaner log output in :log assertion mode.

Timeout Handling

The on_timeout option controls behavior when polling exceeds timeout_ms:

The timeout info passed to the function:

%{
  elapsed_ms: non_neg_integer(),     # Total time elapsed
  poll_count: non_neg_integer(),     # Number of poll attempts
  last_poll_result: term() | nil     # Result of last poll_fn call
}

Like handler errors, on_timeout can return {:error, exception} for structured error reporting:

on_timeout: fn info ->
  {:error, %ResourceTimeout{
    resource: "authorization",
    elapsed_ms: info.elapsed_ms,
    poll_count: info.poll_count
  }}
end

Lifecycle

1. Adapter calls ctx.start_poller.(opts) during execute/2
2. Poller spawns, begins polling immediately
3. Handler processes each poll result, may inject events
4. At sequence end, executor awaits all active pollers
5. Errors handled based on assertion_mode

Error Handling

Errors are captured with stacktraces where applicable:

• poll_fn raises → {:error, {:poll_fn_error, exception, stacktrace}}
• handler raises → {:error, {:handler_error, exception, stacktrace}}
• on_timeout fn raises → {:error, {:on_timeout_error, exception, stacktrace}}
• handler returns {:error, reason} → {:error, reason} (no stacktrace)
• on_timeout returns {:error, reason} → {:error, reason} (no stacktrace)
• Timeout with :fail → {:error, {:timeout, timeout_info}}

In :log assertion mode, exceptions are formatted using Exception.message/1 for cleaner output. In :halt and :record modes, full error details including stacktraces (when available) are preserved in the failure report.