retry

io.retry retries unreliable services. Obviously this feature should be used with great care.

Don't forget to consult the cookbook to see working snippets solving simple real-world problems.

Logic

A request is processed only if it explicitly registered: options object should have an integer property retries.

If options.retries is positive, it limits how many times we can retry an external server. Additionally, we can specify a function property continueRetries(), which can terminate retries earlier by returning false. If it returns true and retries are not exhausted yet, the service will continue repeating calls.

If options.retries is non-positive (zero or negative) retries are driven solely by continueRetries() — requests will continue until it returns false.

Every retry is subject to delay, which can be controlled externally. See below for more details.

Options

options.continueRetries(result, retry)

The function takes two parameters:

• result — an io.Result wrapper returned from transport. It can be inspected to terminate retries. For example, result.xhr.status can be used to inspect the returned status code. The other useful property is result.options, which was used to make the request.
• retry — an integer starting with 1 to number retries.

The function should return a truthy value to continue iterations, and a falsy value to terminate them and return whatever we have at this moment.

The default implementation returns a truthy value for all non-2XX status codes continuing retries and returns a truthy value otherwise.

options.initDelay

Since 1.9.1: This is an initial delay in milliseconds. If it is specified it supersedes io.retry.initDelay on a per-request basis. See io.retry.initDelay below for more details.

options.nextDelay(delay, retry, options)

Since 1.9.1: This is a function to calculate an actual delay. If it is specified it supersedes io.retry.nextDelay() on a per-request basis. See io.retry.nextDelay() below for more details.

Exposed properties

Like any service, io.retry works transparently with io, but it exposes some helpers.

io.retry.delay(ms)

This function returns a promise, which is resolved after ms milliseconds.

This function is exposed mostly for reuse and is not meant to be overridden.

io.retry.initDelay

This variable can take integer values, which specify a delay in milliseconds for the first retry. The default: 50.

io.retry.nextDelay(delay, retry, options)

This function takes three parameters:

• delay — an integer value for a previous delay in milliseconds.
  • Important: the very first call will have a value of io.retry.initDelay or options.initDelay. Take it into account if you make computations.
• retry — the same as in options.continueRetries() described above.
• options — the same as in options.continueRetries() described above.

The returned value is an integer number of milliseconds to use to delay this retry.

The default implementation returns delay unchanged, but by overriding this function it is possible to implement more complex retry algorithms like the exponential backoff.

Standard service properties

See Service documentation for more details.