Behaviour module for handling dead letters (events that failed permanent processing).

Use this to capture events that could not be processed after all retries, log them for investigation, send alerts, or store them for later analysis.

Configuration

Set the dead_letter field in Forja.Config to your handler module:

Forja.Config.new(
  name: :my_forja,
  repo: MyApp.Repo,
  pubsub: MyApp.PubSub,
  dead_letter: MyApp.DeadLetterHandler
)

Example Implementation

defmodule MyApp.DeadLetterHandler do
  @behaviour Forja.DeadLetter

  @impl true
  def handle_dead_letter(%Forja.Event{} = event, reason) do
    Logger.error("Event failed after retries",
      event_id: event.id,
      event_type: event.type,
      reason: reason
    )

    # Optionally store to a dead letter table, send to Sentry, etc.
    :ok
  end
end