View Source Reactor.Step behaviour (reactor v0.2.0)

The struct used to store steps.

Link to this section Summary

Types

Optional capabilities which may be implemented by the step module.

Possible valid return values for the compensate/4 callback.

Possible valid return values for the run/3 callback.

t()

Possible valid return values for the undo/4 callback.

Callbacks

Capability discovery callback.

Compensate for the failure of the step.

Undo a previously successful execution of the step.

Link to this section Types

@type capability() :: :compensate | :undo

Optional capabilities which may be implemented by the step module.

This allows us to optimise out calls steps which cannot be undone, etc.

@type compensate_result() :: {:continue, value :: any()} | :ok | :retry

Possible valid return values for the compensate/4 callback.

@type run_result() ::
  {:ok, value :: any()}
  | {:ok, value :: any(), [t()]}
  | {:halt | :error, reason :: any()}

Possible valid return values for the run/3 callback.

@type t() :: %Reactor.Step{
  arguments: [Reactor.Argument.t()],
  async?: boolean(),
  impl: module() | {module(), keyword()},
  max_retries: non_neg_integer() | :infinity,
  name: any(),
  ref: nil | reference()
}
@type undo_result() :: :ok | :retry | {:error, any()}

Possible valid return values for the undo/4 callback.

Link to this section Callbacks

@callback can?(capability()) :: boolean()

Capability discovery callback.

Return true for the capabilities that your step supports. See t:capability for a list of all capabilities.

Link to this callback

compensate(reason, arguments, context, options)

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

Compensate for the failure of the step.

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.

This callback is only called if can?/1 returns true for the :compensate capability.

arguments

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

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 if you would like the reactor to attempt to re-run the step.
Link to this callback

run(arguments, context, options)

View Source
@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

  • 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

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.
  • {: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.
Link to this callback

undo(value, arguments, context, options)

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

Undo a previously successful execution of the step.

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

This callback is only called if can?/1 returns true for the :undo capability.

arguments

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

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.

Link to this section Functions

@spec can?(t(), capability()) :: boolean()

Find out of a step has a capability.

Link to this function

compensate(map, reason, arguments, context)

View Source
@spec compensate(
  t(),
  reason :: any(),
  arguments :: Reactor.inputs(),
  context :: Reactor.context()
) :: compensate_result()

Compensate a step

Link to this function

run(map, arguments, context)

View Source
@spec run(t(), arguments :: Reactor.inputs(), context :: Reactor.context()) ::
  run_result()

Execute a step.

Link to this function

undo(map, value, arguments, context)

View Source
@spec undo(
  t(),
  value :: any(),
  arguments :: Reactor.inputs(),
  context :: Reactor.context()
) ::
  undo_result()

Undo a step