feat: Add exponential backoff support to MaxRetryInterceptor (#711)

tokizuoh · gh-action-runner · commit 4c97397853e0 · 2025-08-12T18:25:13.000Z
diff --git a/Tests/ApolloTests/Interceptors/MaxRetryInterceptorTests.swift b/Tests/ApolloTests/Interceptors/MaxRetryInterceptorTests.swift
@@ -100,4 +100,118 @@ class MaxRetryInterceptorTests: XCTestCase {
     
     self.wait(for: [expectation], timeout: 1)
   }
+  
+  func testExponentialBackoffDoesNotBreakInterceptorChain() {
+    // Test that exponential backoff preserves normal interceptor chain behavior
+    class TestProvider: InterceptorProvider {
+      let testInterceptor = RetryToCountThenSucceedInterceptor(timesToCallRetry: 2)
+      let retryCount = 3
+      
+      let mockClient: MockURLSessionClient = {
+        let client = MockURLSessionClient()
+        client.jsonData = [:]
+        client.response = HTTPURLResponse(url: TestURL.mockServer.url,
+                                          statusCode: 200,
+                                          httpVersion: nil,
+                                          headerFields: nil)
+        return client
+      }()
+      
+      func interceptors<Operation: GraphQLOperation>(
+        for operation: Operation
+      ) -> [any ApolloInterceptor] {
+        let config = MaxRetryInterceptor.Configuration(
+          maxRetries: self.retryCount,
+          baseDelay: 0.001, // Very small delay to keep test fast
+          multiplier: 2.0,
+          maxDelay: 0.01,
+          enableExponentialBackoff: true,
+          enableJitter: false
+        )
+        return [
+          MaxRetryInterceptor(configuration: config),
+          self.testInterceptor,
+          NetworkFetchInterceptor(client: self.mockClient),
+          JSONResponseParsingInterceptor()
+        ]
+      }
+    }
+
+    let testProvider = TestProvider()
+    let network = RequestChainNetworkTransport(interceptorProvider: testProvider,
+                                               endpointURL: TestURL.mockServer.url)
+    
+    let expectation = self.expectation(description: "Request completed successfully")
+    
+    let operation = MockQuery.mock()
+    _ = network.send(operation: operation) { result in
+      defer {
+        expectation.fulfill()
+      }
+      
+      switch result {
+      case .success:
+        // Verify that the chain completed successfully even with exponential backoff
+        XCTAssertEqual(testProvider.testInterceptor.timesRetryHasBeenCalled, testProvider.testInterceptor.timesToCallRetry)
+      case .failure(let error):
+        XCTFail("Chain should have succeeded with exponential backoff: \(error)")
+      }
+    }
+    
+    self.wait(for: [expectation], timeout: 2)
+  }
+  
+  func testExponentialBackoffPreservesErrorHandling() {
+    // Test that exponential backoff doesn't interfere with proper error propagation
+    class TestProvider: InterceptorProvider {
+      let testInterceptor = BlindRetryingTestInterceptor()
+      let retryCount = 2
+      
+      func interceptors<Operation: GraphQLOperation>(
+        for operation: Operation
+      ) -> [any ApolloInterceptor] {
+        let config = MaxRetryInterceptor.Configuration(
+          maxRetries: self.retryCount,
+          baseDelay: 0.001,
+          multiplier: 2.0,
+          maxDelay: 0.01,
+          enableExponentialBackoff: true,
+          enableJitter: false
+        )
+        return [
+          MaxRetryInterceptor(configuration: config),
+          self.testInterceptor
+        ]
+      }
+    }
+
+    let testProvider = TestProvider()
+    let network = RequestChainNetworkTransport(interceptorProvider: testProvider,
+                                               endpointURL: TestURL.mockServer.url)
+    
+    let expectation = self.expectation(description: "Request failed as expected")
+    
+    let operation = MockQuery.mock()
+    _ = network.send(operation: operation) { result in
+      defer {
+        expectation.fulfill()
+      }
+      
+      switch result {
+      case .success:
+        XCTFail("This should not have succeeded")
+      case .failure(let error):
+        // Verify that the correct error is propagated even with exponential backoff
+        guard case MaxRetryInterceptor.RetryError.hitMaxRetryCount(let count, _) = error else {
+          XCTFail("Unexpected error type: \(error)")
+          return
+        }
+        XCTAssertEqual(count, testProvider.retryCount)
+        // Verify that retries still happened correctly
+        XCTAssertEqual(testProvider.testInterceptor.hitCount, testProvider.retryCount + 1)
+      }
+    }
+    
+    self.wait(for: [expectation], timeout: 2)
+  }
 }
diff --git a/apollo-ios/Sources/Apollo/MaxRetryInterceptor.swift b/apollo-ios/Sources/Apollo/MaxRetryInterceptor.swift
@@ -3,10 +3,51 @@ import Foundation
 import ApolloAPI
 #endif
 
-/// An interceptor to enforce a maximum number of retries of any `HTTPRequest`
+/// An interceptor to enforce a maximum number of retries of any `HTTPRequest` with optional exponential backoff support
 public class MaxRetryInterceptor: ApolloInterceptor {
   
-  private let maxRetries: Int
+  /// A configuration object that defines behavior for retry logic and exponential backoff.
+  public struct Configuration {
+    /// Maximum number of retries allowed. Defaults to `3`.
+    public let maxRetries: Int
+    /// Initial delay in seconds for exponential backoff. Defaults to `0.3`.
+    public let baseDelay: TimeInterval
+    /// Multiplier for exponential backoff calculation. Defaults to `2.0`.
+    public let multiplier: Double
+    /// Maximum delay cap in seconds to prevent excessive wait times. Defaults to `20.0`.
+    public let maxDelay: TimeInterval
+    /// Whether to enable exponential backoff delays between retries. Defaults to `false`.
+    public let enableExponentialBackoff: Bool
+    /// Whether to add jitter to delays to prevent thundering herd problems. Defaults to `true`.
+    public let enableJitter: Bool
+    
+    /// Designated initializer
+    ///
+    /// - Parameters:
+    ///   - maxRetries: Maximum number of retries allowed.
+    ///   - baseDelay: Initial delay in seconds for exponential backoff.
+    ///   - multiplier: Multiplier for exponential backoff calculation. Should be ≥ 1.0.
+    ///   - maxDelay: Maximum delay cap in seconds to prevent excessive wait times.
+    ///   - enableExponentialBackoff: Whether to enable exponential backoff delays between retries.
+    ///   - enableJitter: Whether to add jitter to delays to prevent thundering herd problems.
+    public init(
+      maxRetries: Int = 3,
+      baseDelay: TimeInterval = 0.3,
+      multiplier: Double = 2.0,
+      maxDelay: TimeInterval = 20.0,
+      enableExponentialBackoff: Bool = false,
+      enableJitter: Bool = true
+    ) {
+      self.maxRetries = maxRetries
+      self.baseDelay = baseDelay
+      self.multiplier = multiplier
+      self.maxDelay = maxDelay
+      self.enableExponentialBackoff = enableExponentialBackoff
+      self.enableJitter = enableJitter
+    }
+  }
+  
+  private let configuration: Configuration
   private var hitCount = 0
 
   public var id: String = UUID().uuidString
@@ -26,17 +67,24 @@ public class MaxRetryInterceptor: ApolloInterceptor {
   ///
   /// - Parameter maxRetriesAllowed: How many times a query can be retried, in addition to the initial attempt before
   public init(maxRetriesAllowed: Int = 3) {
-    self.maxRetries = maxRetriesAllowed
+    self.configuration = Configuration(maxRetries: maxRetriesAllowed)
+  }
+  
+  /// Designated initializer with full configuration support.
+  ///
+  /// - Parameter configuration: Configuration object defining retry behavior and exponential backoff settings.
+  public init(configuration: Configuration) {
+    self.configuration = configuration
   }
   
   public func interceptAsync<Operation: GraphQLOperation>(
     chain: any RequestChain,
     request: HTTPRequest<Operation>,
     response: HTTPResponse<Operation>?,
     completion: @escaping (Result<GraphQLResult<Operation.Data>, any Error>) -> Void) {
-    guard self.hitCount <= self.maxRetries else {
+    guard self.hitCount <= self.configuration.maxRetries else {
       let error = RetryError.hitMaxRetryCount(
-        count: self.maxRetries,
+        count: self.configuration.maxRetries,
         operationName: Operation.operationName
       )
 
@@ -51,11 +99,48 @@ public class MaxRetryInterceptor: ApolloInterceptor {
     }
     
     self.hitCount += 1
-    chain.proceedAsync(
-      request: request,
-      response: response,
-      interceptor: self,
-      completion: completion
-    )
+    
+    // Apply exponential backoff delay if enabled and this is a retry (hitCount > 1)
+    if self.configuration.enableExponentialBackoff && self.hitCount > 1 {
+      let delay = calculateExponentialBackoffDelay()
+      DispatchQueue.global(qos: .userInitiated).asyncAfter(deadline: .now() + delay) { [weak self] in
+        guard let self = self else { return }
+        chain.proceedAsync(
+          request: request,
+          response: response,
+          interceptor: self,
+          completion: completion
+        )
+      }
+    } else {
+      chain.proceedAsync(
+        request: request,
+        response: response,
+        interceptor: self,
+        completion: completion
+      )
+    }
+  }
+  
+  /// Calculates the exponential backoff delay based on current retry attempt.
+  ///
+  /// - Returns: The calculated delay in seconds, including jitter if enabled.
+  private func calculateExponentialBackoffDelay() -> TimeInterval {
+    // Calculate exponential delay: baseDelay * multiplier^(hitCount - 1)
+    // We use (hitCount - 1) because hitCount includes the initial attempt
+    let retryAttempt = hitCount - 1
+    let exponentialDelay = configuration.baseDelay * pow(configuration.multiplier, Double(retryAttempt))
+    
+    // Apply maximum delay cap
+    let cappedDelay = min(exponentialDelay, configuration.maxDelay)
+    
+    // Apply jitter if enabled to prevent thundering herd problems
+    if configuration.enableJitter {
+      // Equal jitter: random value between 50% and 100% of calculated delay
+      let minDelay = cappedDelay / 2
+      return TimeInterval.random(in: minDelay...cappedDelay)
+    } else {
+      return cappedDelay
+    }
   }
 }
