Library Modulefumoboy007.swift-retry 0.2.4Retry

Retry

Retries with sensible defaults and powerful flexibility.

Retry.md
import Retry

Module information

Declarations
47
Symbols
50

Coverage

85.1 percent of the declarations in Retry are fully documented14.9 percent of the declarations in Retry are indirectly documented

Declarations

8.5 percent of the declarations in Retry are global functions or variables38.3 percent of the declarations in Retry are initializers, type members, or enum cases27.7 percent of the declarations in Retry are instance members4.3 percent of the declarations in Retry are protocols8.5 percent of the declarations in Retry are protocol requirements12.8 percent of the declarations in Retry are structures

Interfaces

100.0 percent of the declarations in Retry are unrestricted
Module stats and coverage details

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 with Retryable or NotRetryable.

  • 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 custom BackoffAlgorithm implementation if needed.

  • The clock that is used to sleep in between attempts can be replaced. For example, one might use a fake Clock 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

Configuring the Retry Behavior

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