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

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

Usage

defmodule MyApp.HandleStartAssessment do
  use Orkestra.CommandHandler,
    command: MyApp.Tasks.Commands.StartAssessment

  @impl true
  def execute(command, metadata) do
    # command.params contains the validated params
    # metadata contains correlation_id, actor_id, etc.
    {:ok, %{task_id: "123"}}
  end
end

Then add to your supervision tree:

MyApp.HandleStartAssessment

Callbacks

• execute(command, metadata) — your business logic
  • Return {:ok, result} to ack
  • Return :ok to ack without result
  • Return {:error, reason} to nack (triggers retry/dead-letter)

Options

• :command (required) — the command module this handler processes
• :max_retries — override max retries for this handler (default: from envelope)