@callback async?(step :: t()) :: boolean()

Detect if the step can be run asynchronously at runtime.

This callback is automatically defined by use Reactor.Step however you're free to override it if you need a specific behaviour.

This callback is called when Reactor is deciding whether to run a step asynchronously.

The default implementation of this callback checks returns the the value of the steps's async? key if it is boolean, or calls it with the steps's options if it is a function.

@callback can?(step :: t(), capability()) :: boolean()

Detect the capabilities of the step at runtime.

This callback is automatically defined by use Reactor.Step however you're free to override it if you need specific behaviour.

Whenever Reactor would like to either undo a change made by the step, or compensate a step failure this callback is called to detect whether the step module is capable of the desired action.

The default implementation of this callback checks to see if the optional callback is defined on the current module.

@callback compensate(
  reason :: any(),
  arguments :: Reactor.inputs(),
  context :: Reactor.context(),
  options :: keyword()
) :: compensate_result()

Compensate for the failure of the step.

Do not implement this callback if your step doesn't support compensation.

If run/3 returned an error then this callback will be called the error reason and the original arguments.

This provides you the opportunity to handle the error in a number of ways and direct the reactor as to what to do next.

Arguments

• reason - the error reason returned from run/3.
• arguments - the arguments passed to the step.
• context - the reactor context.
• options - a keyword list of options provided to the step (if any).

Return values

• {:continue, value} if you're able to provide a valid result for the step (perhaps by re-running the original computation) then return that within a :continue tuple and execution will continue as planned.
• :ok the step was successfully compensated and the reactor should continue undoing upstream changes.
• :retry or {:retry, reason} if you would like the reactor to attempt to re-run the step. You can optionally supply an error reason which will be used in the event that the step runs out of retries, otherwise a Reactor.Error.Invalid.RetriesExceededError will be used.
• {:error, reason} if compensation was unsuccessful.

@callback run(
  arguments :: Reactor.inputs(),
  context :: Reactor.context(),
  options :: keyword()
) :: run_result()

Execute the step.

This is the function that implements the behaviour you wish to execute. You will receive arguments as per the t:Step.t definition along with their corresponding values as a map and a copy of the current reactor context.

Arguments

• arguments - A map of arguments as per the t:Step.t definition we're called from.
• context - The reactor context.
• options - A keyword list of options provided to the step (if any).

Return values

• {:ok, value} the step completed successfully it returns the value in an ok tuple.
• {:ok, value, [step]} the step completed successfully and wants to add new steps to the reactor.
• {:error, reason} the if step failed, return an error tuple.
• :retry or {:retry, reason} the step failed, but is retryable. You can optionally supply an error reason which will be used in the event that the step runs out of retries, otherwise a Reactor.Error.RetriesExceededError will be used.
• {:halt, reason} terminate (or pause) reactor execution. If there are actively running steps the reactor will wait for them to finish and then return the incomplete state for later resumption.

@callback undo(
  value :: any(),
  arguments :: Reactor.inputs(),
  Reactor.context(),
  options :: keyword()
) :: undo_result()

Undo a previously successful execution of the step.

Do not implement this callback if your step doesn't support undoing.

This callback is called when the reactor encounters an unhandled error later in it's execution run and must undo the work previously done.

Arguments

• value - the return value of the previously successful call to run/3.
• arguments - the arguments passed to the step.
• context - the reactor context.
• options - a keyword list of options provided to the step (if any).

Return values

• :ok the step was successfully undo and the reactor should continue rolling back.
• {:error, reason} there was an error while attempting to compensate. The reactor will collect the error and continue rolling back.
• :retry if you would like the reactor to attempt to undo the again later
  • possibly in the case of a network failure for example.