Retry
Retries with sensible defaults and powerful flexibility.
import Retry
Module information
- Declarations
- 47
- Symbols
- 50
Overview
Designed for Swift Concurrency
The retry(maxAttempts:backoff:appleLogger:logger:operation:recoverFromFailure:)
function is an async
function that runs the given async
closure repeatedly until it succeeds or until the failure is no longer retryable. The function sleeps in between attempts while respecting task cancellation.
Sensible Defaults
The library uses similar defaults as Amazon Web Services and Google Cloud.
An important but often overlooked default is the choice of backoff algorithm, which determines how long to sleep in between attempts. This library chooses an exponential backoff algorithm by default, which is suitable for most use cases. Most retry use cases involve a resource, such as a server, with potentially many clients where an exponential backoff algorithm would be ideal to avoid DDoSing the resource.
Powerful Flexibility
The API provides several customization points to accommodate any use case:
Retries can be selectively enabled or disabled for specific error cases by providing a custom
recoverFromFailure
closure. Retries can also be selectively enabled or disabled for specific code paths by wrapping thrown errors withRetryable
orNotRetryable
.The
RetryConfiguration
type encapsulates the retry behavior so that it can be reused across multiple call sites without duplicating code.The
Backoff
type represents the choice of algorithm that will be used to determine how long to sleep in between attempts. It has built-in support for common algorithms but can be initialized with a customBackoffAlgorithm
implementation if needed.The
clock
that is used to sleep in between attempts can be replaced. For example, one might use a fakeClock
implementation in automated tests to ensure the tests are deterministic and efficient.
Safe Retries
The module exposes a RetryableRequest
protocol to add safe retry methods to a conforming request type. The retry methods in the protocol are similar to the top-level retry functions, but safer. The retry methods in the protocol enforce that the request is idempotent since it is unsafe to retry a non-idempotent request.
To retry HTTP requests, consider using the swift-http-error-handling
package, which adds RetryableRequest
conformance to the standard HTTPRequest
type.
Examples
Retrying Operations
retry(maxAttempts:backoff:appleLogger:logger:operation:recoverFromFailure:)
retry(maxAttempts:clock:backoff:appleLogger:logger:operation:recoverFromFailure:)-6s251
retry(maxAttempts:clock:backoff:appleLogger:logger:operation:recoverFromFailure:)-2e9va
func retry<ClockType, ReturnType>(with: RetryConfiguration<ClockType>, operation: () async throws -> ReturnType
) async throws -> ReturnType Attempts the given operation until it succeeds or until the failure is no longer retryable.
Configuring the Retry Behavior
struct RetryConfiguration<ClockType>
Configures the retry behavior.
enum RecoveryAction<ClockType>
The action to take after an attempt fails.
struct Backoff<ClockType>
The choice of algorithm that will be used to determine how long to sleep in between attempts.
protocol BackoffAlgorithm
Determines how long to sleep in between attempts.
Enabling/Disabling Retries for Specific Code Paths
struct Retryable
A concrete error type that is always retryable and wraps an underlying error.
struct NotRetryable
A concrete error type that is never retryable and wraps an underlying error.
Safely Retrying Requests
protocol RetryableRequest
A protocol that adds safe retry methods to a conforming request type.