# gen_errand

`gen_errand` is a behavior module to simplify interaction with unreliable external services.

The primary use case is fetching resources, eg a connection to a remote database which may be temporarily down or overloaded: while the first connection attempt may fail, it may succeed when retried at a later time.
It is not limited to resource fetching tasks, however, in fact most use cases that need some form of retrying can be modeled, like posting a message to your favorite social network and retrying if it happens to be down.

`gen_errand` relieves users of the burden of implementing retry and backoff logic over and over again, and to focus on the actual interaction logic instead.

## Internals

Under the hood, `gen_errand` is a simplified state machine, with only four possible states:
* `idle`: The errand is ready to start its a task.
* `sleeping`: The errand is waiting in backoff before starting another attempt at doing its task.
* `executing`: The errand is performing its task.
* `done`: The errand has finished its task.

## Callbacks

* `init(Args)` (Mandatory): Called to initialize the errand. Must return either an `ok` tuple with the initial data, the atom `ignore`, or a `stop` tuple with the stop reason.
* `sleep_time(Attempt, Data)` (Mandatory): Called to determine the backoff time before starting the next attempt. Must return either an `ok` tuple with the backoff time and optionally updated data, or `stop` or a `stop` tuple with the stop reason and optionally updated data.
* `handle_execute(Data)` (Mandatory): Called when the errand starts performing its task. Must return an instruction or instruction tuple (see below).
* `handle_event(EventType, Event, State, Data)` (Mandatory): Called when the errand receives a message. Must return an instruction or instruction tuple (see below).
* `terminate(Reason, State, Data)` (Optional): Called when the errand is shutting down. The return value is ignored.
* `code_change(OldVsn, State, Data, Extra)` (Optional): Called when the errand code is updated by a release upgrade. Must return an `ok` tuple with the new errand state and data.

### Instructions

The `handle_execute/1` and `handle_event/4` callbacks must return an instruction or instruction tuple to tell the errand how to proceed.

#### Perform

This instruction is only allowed when the errand is in the `idle` state.

* `perform`: The errand will reset the attempt counter to `0`, transition to the `sleeping` state, wait for the time returned from the callback modules' `sleep_time/2` function, then transition to the `executing` state and start performing its task.
* `{perform, NewData}`: The errand will update its data, reset the attempt counter to `0`, transition to the `sleeping` state, wait for the time returned from the callback modules' `sleep_time/2` function, then transition to the `executing` state and start performing its task.

#### Idle

* `idle`: The errand will transition to the `idle` state.
* `{idle, NewData}`: The errand will update its data and transition to the `idle` state.

#### Continue

* `continue`: The errand will continue in the same state.
* `{continue, NewData}`: The errand will update its data and continue in the same state.
* `{continue, NewData, {Timeout, TimeoutMessage}}`: The errand will update its data and continue in the same state.
  If the given `Timeout` expires before another event occurs, an event of type `timeout` and the given `TimeoutMessage` is passed to `handle_event/4`.

#### Stop

* `stop`: The errand will terminate with reason `normal`.
* `{stop, Reason}`: The errand will terminate with the given reason.
* `{stop, Reason, NewData}`: The errand will update its data and terminate with the given reason.

#### Done

* `done`: The errand will transition to the `done` state.
* `{done, NewData}`: The errand will update its data and transition to the `done` state.

#### Repeat

* `repeat`: The errand will transition to the `executing` state and retry immediately.
* `{repeat, NewData}`: The errand will update its data, transition to the `executing` state, and retry immediately.

#### Retry

* `retry`: The errand will increment the attempt counter, transition to the `sleeping` state, and retry after the respective backoff time has elapsed.
* `{retry, NewData}`: The errand will update its data, increment the attempt counter, transition to the `sleeping` state, and retry after the respective backoff time has elapsed.

## API functions

* `start/3,4`: Starts a standalone errand which is not linked to the calling process. Will return the errand pid in an `ok` tuple, or fail.
* `start_link/3,4`: Starts an errand which is linked to the calling process. Will return the errand pid in an `ok` tuple, or fail.
* `start_monitor/3,4` : Starts an errand which is monitored by the calling process. Will return the errand pid in an `ok` tuple, or fail.
* `wait/2,3`: Wait for the errand to enter a given state within an optional timeout and return `ok`, or fail when the timeout expires.
* `call/2,3`: Send a synchronous call to the errand and wait for a reply within an optional timeout, or fail when the timeout expires.
* `cast/2`: Send an asynchronous cast to the errand. Always returns `ok`.
* `reply/2`: Reply to a message received via a synchronous call message. Always returns `ok`.
* `stop/1,3`: Stops the errand with an optional reason and timeout. Will always return `ok`, or fail when the timeout expires.

## Convenience functions

* `cooldown/5`: Calculates a backoff time from the `Attempt` number, a constant `Delay`, a `Backoff` time which exponentially grows by `Growth`, and a random `Jitter`.

## Usage

See the `examples` directory for examples how `gen_errand` can be implemented and used.

* The `tcp_errand` example is simple, it tries to establish a TCP connection to a given host and port.
* The `smtp_errand` example is more complex, as it not only involves connecting to a server but also some initial communication and possibly a socket upgrade to TLS.

## Authors

* Maria Scott (Maria-12648430)
* Jan Uhlig (juhlig)