ExternalService.RetryOptions (ExternalService v2.0.0)

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 (function of arity 1) - A predicate run on the return value of the call. When it returns a truthy value the call is retried, exactly as if the function had returned :retry (the result itself is used as the retry reason, and the circuit breaker melts). Lets you drive retries from a function that was not written to return :retry/{:retry, reason}. Defaults to no predicate. An explicit :retry/{:retry, reason} return always takes precedence over the predicate.
:retry_exceptions (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, or the :retry_on predicate, 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_exceptions: [module()],
  retry_on: (term() -> as_boolean(term())) | nil
}

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.