ExternalService.RetryOptions (ExternalService v2.0.0-rc.1)

Options that control retry logic for calls to external services.

Retry options can be given either as this struct or as a plain keyword list (which is validated and converted with new/1). The available options are:

:backoff - The backoff strategy used to grow the delay between retries. The default value is :exponential.
:base (non_neg_integer/0) - The initial delay between retries, in milliseconds (0 for no delay). The default value is 10.
:factor (pos_integer/0) - Growth factor applied on each retry. Only used for :linear backoff. The default value is 1.
:cap (pos_integer/0) - Caps the delay between retries to at most this many milliseconds.
:expiry (pos_integer/0) - Total time budget for retries, in milliseconds. Retrying stops once exceeded.
:max_attempts (pos_integer/0) - Maximum number of attempts (the initial attempt plus retries). Defaults to no limit, bounded only by :expiry and/or the circuit breaker.
:jitter - Random jitter applied to delays. true applies +/- 10%; a float (e.g. 0.25) applies that proportion. Helps avoid retrying in lockstep (thundering herd). The default value is false.
:retry_on (list of atom/0) - Exception modules that should trigger a retry when raised. Defaults to [], meaning raised exceptions are not retried; use :retry/{:retry, reason} return values to drive retries instead. The default value is [].

Summary

Functions

merge(base, retry_options)

Layers a keyword list of per-call overrides onto a base struct.

new(retry_options)

Builds a validated RetryOptions struct from a keyword list (or returns an existing struct unchanged).

Types

t()

@type t() :: %ExternalService.RetryOptions{
  backoff: :exponential | :linear,
  base: non_neg_integer(),
  cap: pos_integer() | nil,
  expiry: pos_integer() | nil,
  factor: pos_integer(),
  jitter: boolean() | float(),
  max_attempts: pos_integer() | nil,
  retry_on: [module()]
}

Functions

merge(base, retry_options)

@spec merge(t(), t() | keyword()) :: t()

Layers a keyword list of per-call overrides onto a base struct.

Only the keys actually present in opts are overridden; every other field is taken from base. This is how per-call retry options tweak — rather than reset — a service's configured defaults. A %RetryOptions{} given in place of the keyword list replaces base wholesale, since a struct is already a complete set of options.

Raises NimbleOptions.ValidationError if opts is invalid.

new(retry_options)

@spec new(t() | keyword()) :: t()

Builds a validated RetryOptions struct from a keyword list (or returns an existing struct unchanged).

Raises NimbleOptions.ValidationError if the options are invalid.