external_service v0.7.1 ExternalService View Source

ExternalService handles all retry and circuit breaker logic for calls to external services.

Link to this section Summary

Types

Union type representing all the possible error tuple return values

Error tuple returned when a fuse has been melted enough times that the fuse is blown

Name of a fuse

Error tuple returned when a fuse has not been initialized with ExternalService.start/1

Options used for controlling circuit breaker behavior

Strategy controlling fuse behavior

Error tuple returned when the allowable number of retries has been exceeded

Functions

Given a fuse name and retry options execute a function handling any retry and circuit breaker logic

Like call/3, but raises an exception if retries are exhausted or the fuse is blown

Asynchronous version of ExternalService.call

Parallel, streaming version of ExternalService.call

Parallel, streaming version of ExternalService.call

Parallel, streaming version of ExternalService.call

Initializes a new fuse for a specific service

Link to this section Types

Union type representing all the possible error tuple return values

Link to this type fuse_blown() View Source
fuse_blown() :: {:error, {:fuse_blown, fuse_name()}}

Error tuple returned when a fuse has been melted enough times that the fuse is blown

Link to this type fuse_name() View Source
fuse_name() :: atom()

Name of a fuse

Link to this type fuse_not_found() View Source
fuse_not_found() :: {:error, {:fuse_not_found, fuse_name()}}

Error tuple returned when a fuse has not been initialized with ExternalService.start/1

Link to this type fuse_options() View Source
fuse_options() :: [fuse_strategy: fuse_strategy(), fuse_refresh: pos_integer()]

Options used for controlling circuit breaker behavior.

See the fuse docs for further information about available fuse options.

Link to this type fuse_strategy() View Source
fuse_strategy() ::
  {:standard, max_melt_attempts :: pos_integer(), time_window :: pos_integer()}
  | {:fault_injection, rate :: float(), max_melt_attempts :: pos_integer(),
     time_window :: pos_integer()}

Strategy controlling fuse behavior.

Link to this type retriable_function() View Source
retriable_function() :: (() -> retriable_function_result())
Link to this type retriable_function_result() View Source
retriable_function_result() ::
  :retry | {:retry, reason :: any()} | function_result() :: any()
Link to this type retries_exhausted() View Source
retries_exhausted() :: {:error, {:retries_exhausted, reason :: any()}}

Error tuple returned when the allowable number of retries has been exceeded

Link to this section Functions

Link to this function call(fuse_name, retry_opts \\ %RetryOptions{}, function) View Source
call(fuse_name(), ExternalService.RetryOptions.t(), retriable_function()) ::
  error() | function_result() :: any()

Given a fuse name and retry options execute a function handling any retry and circuit breaker logic.

ExternalService.start must be run with the fuse name before using call.

The provided function can indicate that a retry should be performed by returning the atom :retry or a tuple of the form {:retry, reason}, where reason is any arbitrary term, or by raising a RuntimeError. Any other result is considered successful so the operation will not be retried and the result of the function will be returned as the result of call.

Link to this function call!(fuse_name, retry_opts \\ %RetryOptions{}, function) View Source
call!(fuse_name(), ExternalService.RetryOptions.t(), retriable_function()) ::
  function_result :: any() | no_return()

Like call/3, but raises an exception if retries are exhausted or the fuse is blown.

Link to this function call_async(fuse_name, retry_opts \\ %RetryOptions{}, function) View Source

Asynchronous version of ExternalService.call.

Returns a Task that may be used to retrieve the result of the async call.

Link to this function call_async_stream(enumerable, fuse_name, function) View Source
call_async_stream(
  Enumerable.t(),
  fuse_name(),
  (any() -> retriable_function_result())
) :: Enumerable.t()

Parallel, streaming version of ExternalService.call.

See call_async_stream/5 for full documentation.

Link to this function call_async_stream(enumerable, fuse_name, retry_opts, function) View Source
call_async_stream(
  Enumerable.t(),
  fuse_name(),
  ExternalService.RetryOptions.t() | async_opts() :: list(),
  (any() -> retriable_function_result())
) :: Enumerable.t()

Parallel, streaming version of ExternalService.call.

See call_async_stream/5 for full documentation.

Link to this function call_async_stream(enumerable, fuse_name, retry_opts, async_opts, function) View Source
call_async_stream(
  Enumerable.t(),
  fuse_name(),
  ExternalService.RetryOptions.t(),
  async_opts :: list(),
  (any() -> retriable_function_result())
) :: Enumerable.t()

Parallel, streaming version of ExternalService.call.

This function uses Elixir’s built-in Task.async_stream/3 function and the description below is taken from there.

Returns a stream that runs the given function function concurrently on each item in enumerable.

Each enumerable item is passed as argument to the given function function and processed by its own task. The tasks will be linked to the current process, similarly to async/1.

Link to this function start(fuse_name, fuse_options \\ []) View Source
start(fuse_name(), fuse_options()) :: :ok

Initializes a new fuse for a specific service.