@type async_opts() :: [timeout: integer() | :infinity, supervisor: atom()]

Options for asynchronous transaction stages.

options

Options

• :timeout - a timeout in milliseconds or :infinity for which we will await for the task process to finish the execution, default: 5000. For more details see Task.await/2;

• :supervisor - the name of a Task.Supervisor process that will be used to spawn the async task. Defaults to the Sage.AsyncTransactionSupervisor started by Sage application.

@type compensation() ::
  (effect_to_compensate :: any(), effects_so_far :: effects(), attrs :: any() ->
     :ok | :abort | {:retry, retry_opts :: retry_opts()} | {:continue, any()})
  | :noop
  | mfa()

Compensation callback, can either anonymous function or an {module, function, [arguments]} tuple.

Receives:

• effect created by transaction it's responsible for or nil in case effect is not known due to an error;
• effects created by preceding executed transactions;
• options passed to execute/2 function.

Returns:

• :ok if effect is compensated, Sage will continue to compensate other effects;
• :abort if effect is compensated but should not be created again, Sage will compensate other effects and ignore retries on any stages;
• {:retry, retry_opts} if effect is compensated but transaction can be retried with options retry_opts;
• {:continue, effect} if effect is compensated and execution can be retried with other effect to replace the transaction return. This allows to implement circuit breaker.

circuit-breaker

Circuit Breaker

After receiving a circuit breaker response Sage will continue executing transactions by using returned effect.

Circuit breaking is only allowed if compensation function that returns it is responsible for the failed transaction (they both are parts of for the same execution step). Otherwise circuit breaker would be ignored and Sage will continue applying backward recovery.

The circuit breaker should use data which is local to the sage execution, preferably from list of options which are set via execute/2 2nd argument. This would guarantee that circuit breaker would not fail when response cache is not available.

retries

Retries

After receiving a {:retry, [retry_limit: limit]} Sage will retry the transaction on a stage where retry was received.

Take into account that by doing retires you can increase execution time and block process that executes the Sage, which can produce timeout, eg. when you trying to respond to an HTTP request.

compensation-guidelines

Compensation guidelines

General rule is that irrespectively to what compensate wants to return, effect must be always compensated. No matter what, side effects must not be created from compensating transaction.

A compensating transaction doesn't necessarily return the data in the system to the state it was in at the start of the original operation. Instead, it compensates for the work performed by the steps that completed successfully before the operation failed.

source: https://docs.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction

You should try to make your compensations idempotent, which makes possible to retry if compensating transaction itself fails. According a modern HTTP semantics, the PUT and DELETE verbs are idempotent. Also, some services support idempotent requests via idempotency keys.

Compensation transactions should not rely on effects created by preceding executed transactions, otherwise it will be more likely that your code is not idempotent and harder to maintain. Use them only as a last resort.

@type effects() :: map()

Effects created on Sage execution.

@type final_hook() :: (:ok | :error, attrs :: any() -> no_return()) | mfa()

Final hook.

It receives :ok if all transactions are successfully completed or :error otherwise and options passed to the execute/2.

Return is ignored.

@type retry_opts() :: [
  retry_limit: pos_integer(),
  base_backoff: pos_integer() | nil,
  max_backoff: pos_integer(),
  enable_jitter: boolean()
]

Retry options configure how Sage will retry a transaction.

Retry count for all a sage execution is shared and stored internally, so even through you can increase retry limit - retry count would be never reset to make sure that execution would not be retried infinitely.

options

Options

• :retry_limit - is the maximum number of possible retry attempts;
• :base_backoff - is the base backoff for retries in ms, no backoff is applied if this value is nil or not set;
• :max_backoff - is the maximum backoff value, default: 5_000 ms.;
• :enable_jitter - whatever jitter is applied to backoff value, default: true;

Sage will log an error and give up retrying if options are invalid.

backoff-calculation

Backoff calculation

For exponential backoff this formula is used:

min(max_backoff, (base_backoff * 2) ^ retry_count)

Example:

When jitter is enabled backoff value is randomized:

random(0, min(max_backoff, (base_backoff * 2) ^ retry_count))

Example:

For more reasoning behind using jitter, check out this blog post.

@type stage_name() :: term()

Name of Sage execution stage.

@type tracer() ::
  (stage_name(), Sage.Tracer.action(), state :: any() -> any())
  | module()
  | mfa()

Tracer callback, can be a module that implements Sage.Tracer behaviour, an anonymous function, or an {module, function, [arguments]} tuple.

The tracer callback is called before and after each transaction or compensation. Read Sage.Tracer for more details.

@type transaction() ::
  (effects_so_far :: effects(), attrs :: any() ->
     {:ok | :error | :abort, any()})
  | mfa()

Transaction callback, can either anonymous function or an {module, function, [arguments]} tuple.

Receives effects created by preceding executed transactions and options passed to execute/2 function.

Returns {:ok, effect} if transaction is successfully completed, {:error, reason} if there was an error or {:abort, reason} if there was an unrecoverable error. On receiving {:abort, reason} Sage will compensate all side effects created so far and ignore all retries.

Sage.MalformedTransactionReturnError is raised after compensating all effects if callback returned malformed result.

transaction-guidelines

Transaction guidelines

You should try to make your transactions idempotent, which makes possible to retry if compensating transaction itself fails. According a modern HTTP semantics, the PUT and DELETE verbs are idempotent. Also, some services support idempotent requests via idempotency keys.