Macro for defining event handlers with automatic subscription and ack/nack.

The handler auto-subscribes to the correct topic derived from the event module, unwraps the envelope, and passes the clean event + metadata to your callback.

Supports subscribing to multiple events and wildcard topics.

Usage — single event

defmodule MyApp.OnAssessmentCompleted do
  use Orkestra.EventHandler,
    event: MyApp.Tasks.Events.AssessmentCompleted

  @impl true
  def handle_event(event, metadata) do
    # event.data contains the event fields
    :ok
  end
end

Usage — multiple events

defmodule MyApp.AuditLogger do
  use Orkestra.EventHandler,
    events: [
      MyApp.Tasks.Events.AssessmentCompleted,
      MyApp.Tasks.Events.AssessmentFailed
    ]

  @impl true
  def handle_event(event, metadata) do
    Logger.info("Audit: #{event.type}")
    :ok
  end
end

Usage — wildcard topic

defmodule MyApp.TaskActivityLogger do
  use Orkestra.EventHandler,
    topic: "tasks.events.#"

  @impl true
  def handle_event(event, metadata) do
    :ok
  end
end

Callbacks

• handle_event(event, metadata) — your reaction logic
  • Return :ok to ack
  • Return {:error, reason} to nack (triggers retry/dead-letter)

Options

• :event — single event module
• :events — list of event modules
• :topic — explicit topic pattern (supports * and # wildcards)
• :max_retries — retry attempts before dead-letter (default: 3)

Exactly one of :event, :events, or :topic must be provided.