external_service v0.8.7 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
Strategy controlling fuse behavior
Options used for controlling circuit breaker and rate-limiting behavior
A tuple specifying rate-limiting 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
error() :: retries_exhausted() | fuse_blown() | fuse_not_found()
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
fuse_not_found() :: {:error, {:fuse_not_found, fuse_name()}}
Error tuple returned when a fuse has not been initialized with ExternalService.start/1
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.
options() :: [fuse_strategy: fuse_strategy(), fuse_refresh: pos_integer(), rate_limit: rate_limit()]
Options used for controlling circuit breaker and rate-limiting behavior.
See the fuse docs for further information about available fuse options.
rate_limit() :: {limit :: pos_integer(), time_window :: pos_integer()}
A tuple specifying rate-limiting behavior.
The first element of the tuple is the number of calls to allow in a given time window. The second element is the time window in milliseconds.
retriable_function() :: (() -> retriable_function_result())
retries_exhausted() :: {:error, {:retries_exhausted, reason :: any()}}
Error tuple returned when the allowable number of retries has been exceeded
Link to this section Functions
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
.
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.
call_async(fuse_name(), ExternalService.RetryOptions.t(), retriable_function()) :: Task.t()
Asynchronous version of ExternalService.call
.
Returns a Task
that may be used to retrieve the result of the async call.
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.
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.
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
.
Initializes a new fuse for a specific service.
The fuse_name
is an atom that uniquely identifies an external service within the scope of
an application.
The options
argument allows for controlling the circuit breaker behavior and rate-limiting
behavior when making calls to the external service. See options/0
for details.