evoq_error_handler behaviour (evoq v1.8.1)

Error handler behavior for evoq.

Defines how to handle errors during event processing. Supports multiple strategies: retry, skip, stop, dead_letter.

Error Actions

- retry: Retry immediately - {retry, DelayMs}: Retry after delay - skip: Skip this event and continue - stop: Stop the handler - {dead_letter, Reason}: Send to dead letter queue

Default Behavior

Without implementing on_error/4, handlers use exponential backoff with max 5 retries, then dead letter.

Summary

Types

error_action/0

Callbacks

backoff_ms/1

max_retries/0

on_error/4

Functions

default_action(HandlerModule, Evoq_failure_context)

Get the default error action based on retry count.

handle_error(HandlerModule, Error, Event, Evoq_failure_context, HandlerState)

Handle an error using the handler's error strategy.

should_retry(HandlerModule, Evoq_failure_context)

Check if we should retry based on the failure context.

Types

error_action/0

-type error_action() ::
          retry | {retry, DelayMs :: pos_integer()} | skip | stop | {dead_letter, Reason :: term()}.

Callbacks

backoff_ms/1

(optional)

-callback backoff_ms(AttemptNumber :: pos_integer()) -> pos_integer().

max_retries/0

(optional)

-callback max_retries() -> pos_integer().

on_error/4

(optional)

-callback on_error(Error :: term(),
                   Event :: map(),
                   FailureContext ::
                       #evoq_failure_context{handler_module :: atom(),
                                             event :: map(),
                                             error :: term(),
                                             attempt_number :: pos_integer(),
                                             first_failure_at :: integer(),
                                             last_failure_at :: integer(),
                                             stacktrace :: list()},
                   State :: term()) ->
                      error_action().

Functions

default_action(HandlerModule, Evoq_failure_context)

-spec default_action(atom(),
                     #evoq_failure_context{handler_module :: atom(),
                                           event :: map(),
                                           error :: term(),
                                           attempt_number :: pos_integer(),
                                           first_failure_at :: integer(),
                                           last_failure_at :: integer(),
                                           stacktrace :: list()}) ->
                        {dead_letter, max_retries_exceeded} | {retry, pos_integer()}.

Get the default error action based on retry count.

handle_error(HandlerModule, Error, Event, Evoq_failure_context, HandlerState)

-spec handle_error(atom(),
                   term(),
                   map(),
                   #evoq_failure_context{handler_module :: atom(),
                                         event :: map(),
                                         error :: term(),
                                         attempt_number :: pos_integer(),
                                         first_failure_at :: integer(),
                                         last_failure_at :: integer(),
                                         stacktrace :: list()},
                   term()) ->
                      error_action().

Handle an error using the handler's error strategy.

should_retry(HandlerModule, Evoq_failure_context)

-spec should_retry(atom(),
                   #evoq_failure_context{handler_module :: atom(),
                                         event :: map(),
                                         error :: term(),
                                         attempt_number :: pos_integer(),
                                         first_failure_at :: integer(),
                                         last_failure_at :: integer(),
                                         stacktrace :: list()}) ->
                      boolean().

Check if we should retry based on the failure context.