unify docs and proposal

Author: ph1ps

Evolution/NNNN-retry-backoff.md

@@ -204,12 +204,20 @@ If Swift gains the capability to "store" `inout` variables, the jitter variants
 
 ## Alternatives considered
 
+### Passing attempt number to `BackoffStrategy `
+
 Another option considered was to pass the current attempt number into the `BackoffStrategy`.
 
 Although this initially seems useful, it conflicts with the idea of strategies being stateful. A strategy is supposed to track its own progression (e.g. by counting invocations or storing the last duration). If the attempt number were provided externally, strategies would become "semi-stateful": mutating because of internal components such as a `RandomNumberGenerator`, but at the same time relying on an external counter instead of their own stored history. This dual model is harder to reason about and less consistent, so it was deliberately avoided.  
 
 If adopters require access to the attempt number, they are free to implement this themselves, since the strategy is invoked each time a failure occurs, making it straightforward to maintain an external attempt counter.
 
+### Retry on `AsyncSequence`
+
+An alternative considered was adding retry functionality directly to `AsyncSequence` types, similar to how Combine provides retry on `Publisher`. However, after careful consideration, this was not included in the current proposal due to the lack of compelling real-world use cases.
+
+If specific use cases emerge in the future that demonstrate clear value for async sequence retry functionality, this could be considered in a separate proposal or amended to this proposal.
+
 ## Acknowledgments
 
-Thanks to [Philippe Hausler](https://github.com/phausler), [Franz Busch](https://github.com/FranzBusch) and [Honza Dvorsky](https://github.com/czechboy0) for their thoughtful feedback and suggestions that helped refine the API design and improve its clarity and usability.
+Thanks to [Philippe Hausler](https://github.com/phausler), [Franz Busch](https://github.com/FranzBusch) and [Honza Dvorsky](https://github.com/czechboy0) for their thoughtful feedback and suggestions that helped refine the API design and improve its clarity and usability.

Sources/AsyncAlgorithms/Retry/Backoff.swift

@@ -1,8 +1,12 @@
 #if compiler(>=6.2)
 /// A protocol for defining backoff strategies that generate delays between retry attempts.
 ///
-/// Backoff strategies are stateful and generate progressively changing delays based on their
-/// internal algorithm. Each call to `nextDuration()` returns the delay for the next retry attempt.
+/// Each call to `nextDuration()` returns the delay for the next retry attempt. Strategies are
+/// naturally stateful. For instance, they may track the number of invocations or the previously
+/// returned duration to calculate the next delay.
+///
+/// - Precondition: Strategies should only increase or stay the same over time, never decrease.
+///   Decreasing delays may cause issues with modifiers like jitter which expect non-decreasing values.
 ///
 /// ## Example
 ///
@@ -141,6 +145,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = constant`
   ///
+  /// - Precondition: `constant` must be greater than or equal to zero.
+  ///
   /// - Parameter constant: The fixed duration to wait between retry attempts.
   /// - Returns: A backoff strategy that always returns the constant duration.
   @inlinable public static func constant<Duration: DurationProtocol>(_ constant: Duration) -> some BackoffStrategy<Duration> {
@@ -151,6 +157,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = constant`
   ///
+  /// - Precondition: `constant` must be greater than or equal to zero.
+  ///
   /// - Parameter constant: The fixed duration to wait between retry attempts.
   /// - Returns: A backoff strategy that always returns the constant duration.
   ///
@@ -169,6 +177,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = initial + increment * n`
   ///
+  /// - Precondition: `initial` and `increment` must be greater than or equal to zero.
+  ///
   /// - Parameters:
   ///   - increment: The amount to increase the delay by on each attempt.
   ///   - initial: The initial delay for the first retry attempt.
@@ -181,6 +191,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = initial + increment * n`
   ///
+  /// - Precondition: `initial` and `increment` must be greater than or equal to zero.
+  ///
   /// - Parameters:
   ///   - increment: The amount to increase the delay by on each attempt.
   ///   - initial: The initial delay for the first retry attempt.
@@ -202,6 +214,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = initial * factor^n`
   ///
+  /// - Precondition: `initial` must be greater than or equal to zero.
+  ///
   /// - Parameters:
   ///   - factor: The multiplication factor for each retry attempt.
   ///   - initial: The initial delay for the first retry attempt.
@@ -214,6 +228,8 @@ public enum Backoff {
   ///
   /// Formula: `f(n) = initial * factor^n`
   ///
+  /// - Precondition: `initial` must be greater than or equal to zero.
+  ///
   /// - Parameters:
   ///   - factor: The multiplication factor for each retry attempt.
   ///   - initial: The initial delay for the first retry attempt.
@@ -238,9 +254,11 @@ extension Backoff {
   ///
   /// Formula: `f(n) = random(base, f(n - 1) * factor)` where `f(0) = base`
   ///
-  /// Jitter prevents the "thundering herd" problem where multiple clients retry
+  /// Jitter prevents the thundering herd problem where multiple clients retry
   /// simultaneously, reducing server load spikes and improving system stability.
   ///
+  /// - Precondition: `factor` must be greater than or equal to 1, and `base` must be greater than or equal to zero.
+  ///
   /// - Parameters:
   ///   - factor: The multiplication factor for calculating the upper bound of randomness.
   ///   - base: The base duration used as the minimum delay and initial reference.
@@ -304,7 +322,7 @@ extension BackoffStrategy where Duration == Swift.Duration {
   ///
   /// Formula: `f(n) = random(0, g(n))` where `g(n)` is the base strategy
   ///
-  /// Jitter prevents the "thundering herd" problem where multiple clients retry
+  /// Jitter prevents the thundering herd problem where multiple clients retry
   /// simultaneously, reducing server load spikes and improving system stability.
   ///
   /// - Parameter generator: The random number generator to use. Defaults to `SystemRandomNumberGenerator()`.
@@ -317,7 +335,7 @@ extension BackoffStrategy where Duration == Swift.Duration {
   ///
   /// Formula: `f(n) = random(g(n) / 2, g(n))` where `g(n)` is the base strategy
   ///
-  /// Jitter prevents the "thundering herd" problem where multiple clients retry
+  /// Jitter prevents the thundering herd problem where multiple clients retry
   /// simultaneously, reducing server load spikes and improving system stability.
   ///
   /// - Parameter generator: The random number generator to use. Defaults to `SystemRandomNumberGenerator()`.

Sources/AsyncAlgorithms/Retry/Retry.swift

@@ -18,17 +18,15 @@ public struct RetryAction<Duration: DurationProtocol> {
   /// Indicates that retrying should continue after waiting for the specified duration.
   ///
   /// - Parameter duration: The duration to wait before the next retry attempt.
-  /// - Returns: A retry action that will cause the retry operation to wait.
   @inlinable public static func backoff(_ duration: Duration) -> Self {
     return .init(action: .backoff(duration))
   }
 }
 
 /// Executes an asynchronous operation with retry logic and customizable backoff strategies.
 ///
-/// This function attempts to execute the provided operation up to `maxAttempts` times.
-/// Between failed attempts, it consults the strategy function to determine whether to
-/// continue retrying with a delay or stop immediately.
+/// This function executes an asynchronous operation up to a specified number of attempts,
+/// with customizable delays and error-based retry decisions between attempts.
 ///
 /// The retry logic follows this sequence:
 /// 1. Execute the operation
@@ -40,8 +38,23 @@ public struct RetryAction<Duration: DurationProtocol> {
 ///      - Return to step 1
 /// 4. If failed on the final attempt, rethrow the error without consulting the strategy
 ///
+/// Given this sequence, there are four termination conditions (when retrying will be stopped):
+/// - The operation completes without throwing an error
+/// - The operation has been attempted `maxAttempts` times
+/// - The strategy closure returns `.stop`
+/// - The clock throws
+///
+/// ## Cancellation
+///
+/// `retry` does not introduce special cancellation handling. If your code cooperatively
+/// cancels by throwing, ensure your strategy returns `.stop` for that error. Otherwise,
+/// retries continue unless the clock throws on cancellation (which, at the time of writing,
+/// both `ContinuousClock` and `SuspendingClock` do).
+///
+/// - Precondition: `maxAttempts` must be greater than 0.
+///
 /// - Parameters:
-///   - maxAttempts: The maximum number of attempts to make. Must be greater than 0.
+///   - maxAttempts: The maximum number of attempts to make.
 ///   - tolerance: The tolerance for the sleep operation between retries.
 ///   - clock: The clock to use for timing delays between retries.
 ///   - isolation: The actor isolation to maintain during execution.
@@ -58,7 +71,7 @@ public struct RetryAction<Duration: DurationProtocol> {
 /// let result = try await retry(maxAttempts: 3, clock: ContinuousClock()) {
 ///   try await someNetworkOperation()
 /// } strategy: { error in
-///   .backoff(backoff.nextDuration())
+///   return .backoff(backoff.nextDuration())
 /// }
 /// ```
 @available(iOS 16.0, macCatalyst 16.0, macOS 13.0, tvOS 16.0, visionOS 1.0, watchOS 9.0, *)
@@ -89,9 +102,8 @@ public struct RetryAction<Duration: DurationProtocol> {
 
 /// Executes an asynchronous operation with retry logic and customizable backoff strategies.
 ///
-/// This function attempts to execute the provided operation up to `maxAttempts` times.
-/// Between failed attempts, it consults the strategy function to determine whether to
-/// continue retrying with a delay or stop immediately.
+/// This function executes an asynchronous operation up to a specified number of attempts,
+/// with customizable delays and error-based retry decisions between attempts.
 ///
 /// The retry logic follows this sequence:
 /// 1. Execute the operation
@@ -103,8 +115,23 @@ public struct RetryAction<Duration: DurationProtocol> {
 ///      - Return to step 1
 /// 4. If failed on the final attempt, rethrow the error without consulting the strategy
 ///
+/// Given this sequence, there are four termination conditions (when retrying will be stopped):
+/// - The operation completes without throwing an error
+/// - The operation has been attempted `maxAttempts` times
+/// - The strategy closure returns `.stop`
+/// - The clock throws
+///
+/// ## Cancellation
+///
+/// `retry` does not introduce special cancellation handling. If your code cooperatively
+/// cancels by throwing, ensure your strategy returns `.stop` for that error. Otherwise,
+/// retries continue unless the clock throws on cancellation (which, at the time of writing,
+/// both `ContinuousClock` and `SuspendingClock` do).
+///
+/// - Precondition: `maxAttempts` must be greater than 0.
+///
 /// - Parameters:
-///   - maxAttempts: The maximum number of attempts to make. Must be greater than 0.
+///   - maxAttempts: The maximum number of attempts to make.
 ///   - tolerance: The tolerance for the sleep operation between retries.
 ///   - isolation: The actor isolation to maintain during execution.
 ///   - operation: The asynchronous operation to retry.
@@ -120,7 +147,7 @@ public struct RetryAction<Duration: DurationProtocol> {
 /// let result = try await retry(maxAttempts: 3) {
 ///   try await someNetworkOperation()
 /// } strategy: { error in
-///   .backoff(backoff.nextDuration())
+///   return .backoff(backoff.nextDuration())
 /// }
 /// ```
 @available(iOS 16.0, macCatalyst 16.0, macOS 13.0, tvOS 16.0, visionOS 1.0, watchOS 9.0, *)