feat(network): prevent concurrent token refresh by queueing pending requests

Author: ns-vasilev

Sources/NetworkLayer/Classes/Core/Services/RequestProcessor/RequestProcessor.swift

@@ -41,6 +41,10 @@ actor RequestProcessor {
     /// This applies to all requests processed by this instance.
     private let retryEvaluator: (@Sendable (Error) -> RetryAction)?
 
+    /// A shared in-flight refresh task. All requests that need a token refresh
+    /// will await this single task instead of each triggering their own refresh.
+    private var pendingRefreshTask: Task<Void, Error>?
+
     // MARK: - Initialization
 
     /// Creates a new `RequestProcessor` instance.
@@ -118,26 +122,46 @@ actor RequestProcessor {
         try await interceptor?.adapt(request: &urlRequest, for: session)
     }
 
-    /// Checks if a request requires a credential refresh and performs it if necessary.
+    /// Ensures that only a single token refresh is in flight at any given time.
+    ///
+    /// When the first request detects that a refresh is needed it creates a shared
+    /// `Task` and stores it in `pendingRefreshTask`. Every subsequent request that
+    /// arrives while the refresh is still running will simply `await` that same task
+    /// instead of starting a new one. Once the task completes (successfully or with
+    /// an error) `pendingRefreshTask` is set to `nil` so that the next refresh
+    /// cycle can start fresh.
     ///
     /// - Parameters:
     ///   - urlRequest: The failed or unauthorized request.
     ///   - response: The received network response.
     ///   - session: The current `URLSession`.
-    /// - Returns: `true` if a refresh was triggered, `false` otherwise.
-    private func refresh(
+    /// - Returns: `true` if a refresh was triggered or awaited, `false` otherwise.
+    private func refreshIfNeeded(
         urlRequest: URLRequest,
         response: Response<some Any>,
         session: URLSession
     ) async throws -> Bool {
-        guard let interceptor, let response = response.response as? HTTPURLResponse else { return false }
-
-        if interceptor.isRequireRefresh(urlRequest, response: response) {
-            try await interceptor.refresh(urlRequest, with: response, for: session)
+        guard
+            let interceptor,
+            let httpResponse = response.response as? HTTPURLResponse,
+            interceptor.isRequireRefresh(urlRequest, response: httpResponse)
+        else { return false }
+
+        if let existingTask = pendingRefreshTask {
+            try await existingTask.value
             return true
         }
 
-        return false
+        let refreshTask = Task<Void, Error> {
+            try await interceptor.refresh(urlRequest, with: httpResponse, for: session)
+        }
+
+        pendingRefreshTask = refreshTask
+
+        defer { pendingRefreshTask = nil }
+
+        try await refreshTask.value
+        return true
     }
 
     /// Wraps a request operation with retry logic provided by the `retryPolicyService`.
@@ -237,13 +261,13 @@ actor RequestProcessor {
         response: Response<Data>,
         delegate: URLSessionDelegate?
     ) async throws -> Response<Data> {
-        guard try await refresh(urlRequest: urlRequest, response: response, session: session) else {
+        guard try await refreshIfNeeded(urlRequest: urlRequest, response: response, session: session) else {
             return response
         }
 
         let retryResponse = try await performDataTask(urlRequest: urlRequest, delegate: delegate)
 
-        guard try await !refresh(urlRequest: urlRequest, response: retryResponse, session: session) else {
+        guard try await !refreshIfNeeded(urlRequest: urlRequest, response: retryResponse, session: session) else {
             throw AuthenticatorInterceptorError.missingCredential
         }