Process manager command dispatch error handling

[slashdotdash]

Process managers handle events and return commands to be dispatched in response (they may return no commands, as nil or []).

Currently, the commands must be successfully dispatched or the process manager will crash.

To allow you to configure how command dispatch errors are handled a new error/3 callback is proposed for the Commanded.ProcessManagers.ProcessManager behaviour. This callback function is used to handle any errors returned from command dispatch. You can use pattern matching on the error and/or command to explicitly handle certain errors or commands.

The proposed error handling options are:

• {:retry, context} - retry the failed command, provide a context map to provide state to subsequent failures. This could be used to count the number of retries, failing after too many attempts.
• {:retry, delay, context} - retry the failed command, after sleeping for the requested delay (in milliseconds). Context is a map, the same as {:retry, context} above.
• {:skip, :discard_pending} - discard the failed command and any pending commands.
• {:skip, :continue_pending} - skip the failed command and continue dispatching any pending commands.
• {:continue, commands, context} - continue dispatching the given commands. This allows you to retry the failed command, modify it and retry, drop it, or drop all pending commands by passing an empty list [].
• {:stop, reason} - stop the process manager with the given reason.

The default behaviour will be to stop the process manager using the error reason returned from the failed command dispatch.

Example

defmodule ExampleProcessManager do
  use Commanded.ProcessManagers.ProcessManager,
    name: "ExampleProcessManager",
    router: ExampleRouter

  # stop process manager after third failed attempt
  def error({:error, _failure}, _failed_command, _pending_commands, %{attempts: attempts})
    when attempts >= 2
  do
    {:stop, :too_many_attempts}
  end

  # retry command, record attempt count in context map
  def error({:error, _failure}, _failed_command, _pending_commands, context) do
    context = Map.update(context, :attempts, 1, fn attempts -> attempts + 1 end)

    {:retry, context}
  end
end

[slashdotdash]

Done by #94.