@devo-bmad-custom/agent-orchestration 1.0.2 → 1.0.4

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/ios-networking/references/urlsession-patterns.md

@@ -1,1116 +1,1116 @@
-# URLSession Patterns Reference
-
-Complete implementation patterns for URLSession-based networking. Each
-section is self-contained with production-ready code.
-
----
-
-## Contents
-
-- [Complete API Client with Protocol](#complete-api-client-with-protocol)
-- [Request Builder Pattern](#request-builder-pattern)
-- [Multipart Form Upload](#multipart-form-upload)
-- [Download with Progress Tracking](#download-with-progress-tracking)
-- [Cursor-Based Pagination](#cursor-based-pagination)
-- [Offset-Based Pagination](#offset-based-pagination)
-- [URLProtocol Mock for Testing](#urlprotocol-mock-for-testing)
-- [Retry with Exponential Backoff](#retry-with-exponential-backoff)
-- [Certificate Pinning (URLSessionDelegate)](#certificate-pinning-urlsessiondelegate)
-- [Request Logging / Debugging Middleware](#request-logging-debugging-middleware)
-- [Request Caching Strategies](#request-caching-strategies)
-- [Server-Sent Events (SSE) Parsing](#server-sent-events-sse-parsing)
-- [Configured URLSession for Production](#configured-urlsession-for-production)
-
-## Complete API Client with Protocol
-
-A full-featured client with middleware support, configurable decoding,
-and response validation.
-
-### Protocol
-
-```swift
-protocol APIClientProtocol: Sendable {
-    func request<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint
-    ) async throws -> T
-
-    func request(endpoint: Endpoint) async throws
-
-    func upload<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint,
-        body: Data
-    ) async throws -> T
-}
-```
-
-### Endpoint Definition
-
-```swift
-struct Endpoint: Sendable {
-    let path: String
-    var method: HTTPMethod = .get
-    var queryItems: [URLQueryItem] = []
-    var headers: [String: String] = [:]
-    var body: Data? = nil
-    var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
-    var timeoutInterval: TimeInterval = 30
-
-    enum HTTPMethod: String, Sendable {
-        case get = "GET"
-        case post = "POST"
-        case put = "PUT"
-        case patch = "PATCH"
-        case delete = "DELETE"
-    }
-
-    func urlRequest(relativeTo baseURL: URL) -> URLRequest {
-        var components = URLComponents(
-            url: baseURL.appendingPathComponent(path),
-            resolvingAgainstBaseURL: true
-        )!
-        if !queryItems.isEmpty {
-            components.queryItems = queryItems
-        }
-        var request = URLRequest(url: components.url!)
-        request.httpMethod = method.rawValue
-        request.httpBody = body
-        request.cachePolicy = cachePolicy
-        request.timeoutInterval = timeoutInterval
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-        return request
-    }
-}
-```
-
-### Client Implementation
-
-```swift
-final class APIClient: APIClientProtocol {
-    private let baseURL: URL
-    private let session: URLSession
-    private let decoder: JSONDecoder
-    private let encoder: JSONEncoder
-    private let middlewares: [any RequestMiddleware]
-
-    init(
-        baseURL: URL,
-        session: URLSession = .shared,
-        decoder: JSONDecoder = {
-            let d = JSONDecoder()
-            d.dateDecodingStrategy = .iso8601
-            d.keyDecodingStrategy = .convertFromSnakeCase
-            return d
-        }(),
-        encoder: JSONEncoder = {
-            let e = JSONEncoder()
-            e.dateEncodingStrategy = .iso8601
-            e.keyEncodingStrategy = .convertToSnakeCase
-            return e
-        }(),
-        middlewares: [any RequestMiddleware] = []
-    ) {
-        self.baseURL = baseURL
-        self.session = session
-        self.decoder = decoder
-        self.encoder = encoder
-        self.middlewares = middlewares
-    }
-
-    func request<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint
-    ) async throws -> T {
-        let request = try await prepareRequest(for: endpoint)
-        let (data, response) = try await session.data(for: request)
-        try validateResponse(response, data: data)
-        return try decoder.decode(T.self, from: data)
-    }
-
-    func request(endpoint: Endpoint) async throws {
-        let request = try await prepareRequest(for: endpoint)
-        let (data, response) = try await session.data(for: request)
-        try validateResponse(response, data: data)
-    }
-
-    func upload<T: Decodable & Sendable>(
-        _ type: T.Type,
-        endpoint: Endpoint,
-        body: Data
-    ) async throws -> T {
-        var request = try await prepareRequest(for: endpoint)
-        request.httpBody = body
-        let (data, response) = try await session.upload(for: request, from: body)
-        try validateResponse(response, data: data)
-        return try decoder.decode(T.self, from: data)
-    }
-
-    // MARK: - Convenience methods
-
-    func get<T: Decodable & Sendable>(
-        _ type: T.Type,
-        path: String,
-        queryItems: [URLQueryItem] = []
-    ) async throws -> T {
-        try await request(type, endpoint: Endpoint(
-            path: path,
-            method: .get,
-            queryItems: queryItems
-        ))
-    }
-
-    func post<T: Decodable & Sendable, B: Encodable & Sendable>(
-        _ type: T.Type,
-        path: String,
-        body: B
-    ) async throws -> T {
-        let bodyData = try encoder.encode(body)
-        return try await request(type, endpoint: Endpoint(
-            path: path,
-            method: .post,
-            headers: ["Content-Type": "application/json"],
-            body: bodyData
-        ))
-    }
-
-    func delete(path: String) async throws {
-        try await request(endpoint: Endpoint(path: path, method: .delete))
-    }
-
-    // MARK: - Internal
-
-    private func prepareRequest(for endpoint: Endpoint) async throws -> URLRequest {
-        var request = endpoint.urlRequest(relativeTo: baseURL)
-        for middleware in middlewares {
-            request = try await middleware.prepare(request)
-        }
-        return request
-    }
-
-    private func validateResponse(_ response: URLResponse, data: Data) throws {
-        guard let http = response as? HTTPURLResponse else {
-            throw NetworkError.invalidResponse
-        }
-        guard (200..<300).contains(http.statusCode) else {
-            let apiError = try? decoder.decode(APIErrorBody.self, from: data)
-            throw NetworkError.httpError(
-                statusCode: http.statusCode,
-                data: data,
-                message: apiError?.message
-            )
-        }
-    }
-}
-```
-
-### Error Types
-
-```swift
-enum NetworkError: Error, Sendable, LocalizedError {
-    case invalidResponse
-    case httpError(statusCode: Int, data: Data, message: String? = nil)
-    case noConnection
-    case timedOut
-    case cancelled
-
-    var errorDescription: String? {
-        switch self {
-        case .invalidResponse:
-            return "Invalid server response"
-        case .httpError(let code, _, let message):
-            return message ?? "HTTP error \(code)"
-        case .noConnection:
-            return "No internet connection"
-        case .timedOut:
-            return "Request timed out"
-        case .cancelled:
-            return nil
-        }
-    }
-
-    static func from(_ urlError: URLError) -> NetworkError {
-        switch urlError.code {
-        case .notConnectedToInternet, .networkConnectionLost:
-            return .noConnection
-        case .timedOut:
-            return .timedOut
-        case .cancelled:
-            return .cancelled
-        default:
-            return .invalidResponse
-        }
-    }
-}
-
-struct APIErrorBody: Decodable, Sendable {
-    let code: String?
-    let message: String?
-}
-```
-
----
-
-## Request Builder Pattern
-
-For complex request construction, a builder provides a fluent API that
-reduces errors.
-
-```swift
-struct RequestBuilder: Sendable {
-    private var method: String = "GET"
-    private var path: String
-    private var baseURL: URL
-    private var queryItems: [URLQueryItem] = []
-    private var headers: [String: String] = [:]
-    private var body: Data?
-    private var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
-    private var timeout: TimeInterval = 30
-
-    init(baseURL: URL, path: String) {
-        self.baseURL = baseURL
-        self.path = path
-    }
-
-    func method(_ method: String) -> RequestBuilder {
-        var copy = self
-        copy.method = method
-        return copy
-    }
-
-    func query(_ name: String, _ value: String?) -> RequestBuilder {
-        guard let value else { return self }
-        var copy = self
-        copy.queryItems.append(URLQueryItem(name: name, value: value))
-        return copy
-    }
-
-    func header(_ name: String, _ value: String) -> RequestBuilder {
-        var copy = self
-        copy.headers[name] = value
-        return copy
-    }
-
-    func jsonBody<T: Encodable>(_ value: T) throws -> RequestBuilder {
-        var copy = self
-        copy.body = try JSONEncoder().encode(value)
-        copy.headers["Content-Type"] = "application/json"
-        return copy
-    }
-
-    func timeout(_ interval: TimeInterval) -> RequestBuilder {
-        var copy = self
-        copy.timeout = interval
-        return copy
-    }
-
-    func cachePolicy(_ policy: URLRequest.CachePolicy) -> RequestBuilder {
-        var copy = self
-        copy.cachePolicy = policy
-        return copy
-    }
-
-    func build() -> URLRequest {
-        var components = URLComponents(
-            url: baseURL.appendingPathComponent(path),
-            resolvingAgainstBaseURL: true
-        )!
-        if !queryItems.isEmpty {
-            components.queryItems = queryItems
-        }
-        var request = URLRequest(url: components.url!)
-        request.httpMethod = method
-        request.httpBody = body
-        request.cachePolicy = cachePolicy
-        request.timeoutInterval = timeout
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-        return request
-    }
-}
-
-// Usage
-let request = try RequestBuilder(baseURL: apiURL, path: "users")
-    .method("POST")
-    .header("X-Request-ID", UUID().uuidString)
-    .jsonBody(CreateUserRequest(name: "Alice", email: "alice@example.com"))
-    .timeout(15)
-    .build()
-```
-
----
-
-## Multipart Form Upload
-
-Multipart/form-data uploads are common for file attachments. Build the
-body manually -- no third-party library needed.
-
-```swift
-struct MultipartFormData: Sendable {
-    private let boundary: String
-    private var parts: [Part] = []
-
-    init(boundary: String = UUID().uuidString) {
-        self.boundary = boundary
-    }
-
-    var contentType: String {
-        "multipart/form-data; boundary=\(boundary)"
-    }
-
-    mutating func addField(name: String, value: String) {
-        parts.append(Part(
-            headers: "Content-Disposition: form-data; name=\"\(name)\"",
-            body: Data(value.utf8)
-        ))
-    }
-
-    mutating func addFile(
-        name: String,
-        filename: String,
-        mimeType: String,
-        data: Data
-    ) {
-        parts.append(Part(
-            headers: """
-            Content-Disposition: form-data; name="\(name)"; filename="\(filename)"\r
-            Content-Type: \(mimeType)
-            """,
-            body: data
-        ))
-    }
-
-    func encode() -> Data {
-        var data = Data()
-        let crlf = "\r\n"
-        for part in parts {
-            data.append("--\(boundary)\(crlf)")
-            data.append("\(part.headers)\(crlf)\(crlf)")
-            data.append(part.body)
-            data.append(crlf)
-        }
-        data.append("--\(boundary)--\(crlf)")
-        return data
-    }
-
-    private struct Part: Sendable {
-        let headers: String
-        let body: Data
-    }
-}
-
-extension Data {
-    mutating func append(_ string: String) {
-        append(Data(string.utf8))
-    }
-}
-
-// Usage
-var form = MultipartFormData()
-form.addField(name: "title", value: "Profile Photo")
-form.addFile(
-    name: "image",
-    filename: "photo.jpg",
-    mimeType: "image/jpeg",
-    data: imageData
-)
-
-var request = URLRequest(url: uploadURL)
-request.httpMethod = "POST"
-request.setValue(form.contentType, forHTTPHeaderField: "Content-Type")
-request.httpBody = form.encode()
-
-let (data, response) = try await URLSession.shared.upload(
-    for: request,
-    from: form.encode()
-)
-```
-
----
-
-## Download with Progress Tracking
-
-Use `bytes(for:)` for real-time progress. The response includes
-`expectedContentLength` for calculating percentage.
-
-```swift
-@available(iOS 15.0, *)
-func downloadWithProgress(
-    from url: URL,
-    progressHandler: @Sendable (Double) -> Void
-) async throws -> Data {
-    let (bytes, response) = try await URLSession.shared.bytes(from: url)
-
-    let expectedLength = response.expectedContentLength
-    var receivedData = Data()
-    if expectedLength > 0 {
-        receivedData.reserveCapacity(Int(expectedLength))
-    }
-
-    var receivedLength: Int64 = 0
-    for try await byte in bytes {
-        receivedData.append(byte)
-        receivedLength += 1
-        if expectedLength > 0 {
-            let progress = Double(receivedLength) / Double(expectedLength)
-            progressHandler(progress)
-        }
-    }
-
-    return receivedData
-}
-```
-
-For large files, prefer `URLSessionDownloadTask` with a delegate for
-better memory efficiency and background support. See
-`references/background-websocket.md`.
-
-### Download to File with Progress (Delegate-Based)
-
-```swift
-@available(iOS 15.0, *)
-final class DownloadManager: NSObject, URLSessionDownloadDelegate, Sendable {
-    private let continuation: AsyncStream<DownloadEvent>.Continuation
-
-    enum DownloadEvent: Sendable {
-        case progress(Double)
-        case completed(URL)
-        case failed(Error)
-    }
-
-    static func download(from url: URL) -> AsyncStream<DownloadEvent> {
-        AsyncStream { continuation in
-            let manager = DownloadManager(continuation: continuation)
-            let session = URLSession(
-                configuration: .default,
-                delegate: manager,
-                delegateQueue: nil
-            )
-            session.downloadTask(with: url).resume()
-        }
-    }
-
-    private init(continuation: AsyncStream<DownloadEvent>.Continuation) {
-        self.continuation = continuation
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didFinishDownloadingTo location: URL
-    ) {
-        // Move file to permanent location before this method returns
-        let destination = FileManager.default.temporaryDirectory
-            .appendingPathComponent(UUID().uuidString)
-        do {
-            try FileManager.default.moveItem(at: location, to: destination)
-            continuation.yield(.completed(destination))
-        } catch {
-            continuation.yield(.failed(error))
-        }
-        continuation.finish()
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didWriteData bytesWritten: Int64,
-        totalBytesWritten: Int64,
-        totalBytesExpectedToWrite: Int64
-    ) {
-        guard totalBytesExpectedToWrite > 0 else { return }
-        let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
-        continuation.yield(.progress(progress))
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        task: URLSessionTask,
-        didCompleteWithError error: (any Error)?
-    ) {
-        if let error {
-            continuation.yield(.failed(error))
-            continuation.finish()
-        }
-    }
-}
-```
-
----
-
-## Cursor-Based Pagination
-
-A reusable paginator that conforms to `AsyncSequence`, yielding pages
-of results until the server indicates no more data.
-
-```swift
-struct PageResponse<T: Decodable & Sendable>: Decodable, Sendable {
-    let data: [T]
-    let pagination: PaginationInfo
-}
-
-struct PaginationInfo: Decodable, Sendable {
-    let nextCursor: String?
-    let hasMore: Bool
-}
-
-struct CursorPaginator<T: Decodable & Sendable>: AsyncSequence {
-    typealias Element = [T]
-
-    private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
-
-    init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
-        self.fetchPage = fetchPage
-    }
-
-    func makeAsyncIterator() -> Iterator {
-        Iterator(fetchPage: fetchPage)
-    }
-
-    struct Iterator: AsyncIteratorProtocol {
-        private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
-        private var cursor: String?
-        private var exhausted = false
-
-        init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
-            self.fetchPage = fetchPage
-        }
-
-        mutating func next() async throws -> [T]? {
-            guard !exhausted else { return nil }
-            try Task.checkCancellation()
-
-            let response = try await fetchPage(cursor)
-            cursor = response.pagination.nextCursor
-            exhausted = !response.pagination.hasMore
-
-            return response.data.isEmpty ? nil : response.data
-        }
-    }
-}
-
-// Usage
-let paginator = CursorPaginator<User> { cursor in
-    var queryItems = [URLQueryItem(name: "limit", value: "50")]
-    if let cursor {
-        queryItems.append(URLQueryItem(name: "cursor", value: cursor))
-    }
-    return try await client.get(
-        PageResponse<User>.self,
-        path: "users",
-        queryItems: queryItems
-    )
-}
-
-var allUsers: [User] = []
-for try await batch in paginator {
-    allUsers.append(contentsOf: batch)
-}
-```
-
----
-
-## Offset-Based Pagination
-
-```swift
-struct OffsetPaginator<T: Decodable & Sendable>: AsyncSequence {
-    typealias Element = [T]
-
-    private let pageSize: Int
-    private let fetchPage: @Sendable (Int, Int) async throws -> [T]
-
-    init(
-        pageSize: Int = 20,
-        fetchPage: @escaping @Sendable (_ offset: Int, _ limit: Int) async throws -> [T]
-    ) {
-        self.pageSize = pageSize
-        self.fetchPage = fetchPage
-    }
-
-    func makeAsyncIterator() -> Iterator {
-        Iterator(pageSize: pageSize, fetchPage: fetchPage)
-    }
-
-    struct Iterator: AsyncIteratorProtocol {
-        private let pageSize: Int
-        private let fetchPage: @Sendable (Int, Int) async throws -> [T]
-        private var offset = 0
-        private var exhausted = false
-
-        init(
-            pageSize: Int,
-            fetchPage: @escaping @Sendable (Int, Int) async throws -> [T]
-        ) {
-            self.pageSize = pageSize
-            self.fetchPage = fetchPage
-        }
-
-        mutating func next() async throws -> [T]? {
-            guard !exhausted else { return nil }
-            try Task.checkCancellation()
-
-            let items = try await fetchPage(offset, pageSize)
-            offset += items.count
-            if items.count < pageSize { exhausted = true }
-
-            return items.isEmpty ? nil : items
-        }
-    }
-}
-```
-
----
-
-## URLProtocol Mock for Testing
-
-`URLProtocol` is the correct way to mock network responses at the
-transport level. It works with any URLSession configuration and does
-not require changing production code.
-
-```swift
-final class MockURLProtocol: URLProtocol {
-    nonisolated(unsafe) static var requestHandler: ((URLRequest) throws -> (HTTPURLResponse, Data))?
-
-    override class func canInit(with request: URLRequest) -> Bool { true }
-
-    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
-
-    override func startLoading() {
-        guard let handler = Self.requestHandler else {
-            fatalError("MockURLProtocol.requestHandler is not set")
-        }
-
-        do {
-            let (response, data) = try handler(request)
-            client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
-            client?.urlProtocol(self, didLoad: data)
-            client?.urlProtocolDidFinishLoading(self)
-        } catch {
-            client?.urlProtocol(self, didFailWithError: error)
-        }
-    }
-
-    override func stopLoading() {}
-}
-```
-
-### Test Setup
-
-```swift
-import Testing
-
-@Suite struct APIClientTests {
-    let client: APIClient
-    let session: URLSession
-
-    init() {
-        let config = URLSessionConfiguration.ephemeral
-        config.protocolClasses = [MockURLProtocol.self]
-        session = URLSession(configuration: config)
-        client = APIClient(
-            baseURL: URL(string: "https://api.example.com")!,
-            session: session
-        )
-    }
-
-    @Test func fetchUsersDecodesCorrectly() async throws {
-        let usersJSON = """
-        [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
-        """
-        MockURLProtocol.requestHandler = { request in
-            #expect(request.url?.path == "/users")
-            let response = HTTPURLResponse(
-                url: request.url!,
-                statusCode: 200,
-                httpVersion: nil,
-                headerFields: ["Content-Type": "application/json"]
-            )!
-            return (response, Data(usersJSON.utf8))
-        }
-
-        let users: [User] = try await client.get([User].self, path: "users")
-        #expect(users.count == 2)
-        #expect(users[0].name == "Alice")
-    }
-
-    @Test func fetchReturnsHTTPError() async throws {
-        MockURLProtocol.requestHandler = { request in
-            let response = HTTPURLResponse(
-                url: request.url!,
-                statusCode: 404,
-                httpVersion: nil,
-                headerFields: nil
-            )!
-            return (response, Data())
-        }
-
-        await #expect(throws: NetworkError.self) {
-            let _: [User] = try await client.get([User].self, path: "missing")
-        }
-    }
-
-    @Test func requestIncludesAuthHeader() async throws {
-        let authClient = APIClient(
-            baseURL: URL(string: "https://api.example.com")!,
-            session: session,
-            middlewares: [AuthMiddleware { "test-token" }]
-        )
-
-        MockURLProtocol.requestHandler = { request in
-            #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer test-token")
-            let response = HTTPURLResponse(
-                url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil
-            )!
-            return (response, Data("{}".utf8))
-        }
-
-        let _: EmptyResponse = try await authClient.get(EmptyResponse.self, path: "me")
-    }
-}
-
-struct EmptyResponse: Decodable, Sendable {}
-```
-
----
-
-## Retry with Exponential Backoff
-
-Respect cancellation. Do not retry client errors (4xx except 429 rate
-limiting). Include jitter to prevent thundering herd.
-
-```swift
-func withRetry<T: Sendable>(
-    maxAttempts: Int = 3,
-    initialDelay: Duration = .seconds(1),
-    maxDelay: Duration = .seconds(30),
-    shouldRetry: @Sendable (Error) -> Bool = { error in
-        if error is CancellationError { return false }
-        if case NetworkError.httpError(let code, _, _) = error {
-            return code >= 500 || code == 429
-        }
-        if let urlError = error as? URLError {
-            return [.timedOut, .networkConnectionLost, .notConnectedToInternet]
-                .contains(urlError.code)
-        }
-        return false
-    },
-    operation: @Sendable () async throws -> T
-) async throws -> T {
-    var lastError: Error?
-
-    for attempt in 0..<maxAttempts {
-        try Task.checkCancellation()
-        do {
-            return try await operation()
-        } catch {
-            lastError = error
-            guard shouldRetry(error), attempt < maxAttempts - 1 else {
-                throw error
-            }
-            // Exponential backoff with jitter
-            let base = Double(initialDelay.components.seconds) * pow(2.0, Double(attempt))
-            let capped = min(base, Double(maxDelay.components.seconds))
-            let jitter = Double.random(in: 0...(capped * 0.1))
-            let delay = Duration.seconds(capped + jitter)
-            try await Task.sleep(for: delay)
-        }
-    }
-
-    throw lastError!
-}
-
-// Usage
-let users = try await withRetry {
-    try await client.get([User].self, path: "users")
-}
-```
-
----
-
-## Certificate Pinning (URLSessionDelegate)
-
-Pin the server's public key hash rather than the certificate itself.
-Certificates rotate; public keys are more stable. Always include a
-backup pin.
-
-```swift
-import CryptoKit
-
-final class PinningDelegate: NSObject, URLSessionDelegate, Sendable {
-    /// SHA-256 hashes of Subject Public Key Info (SPKI) in base64
-    private let pinnedKeyHashes: Set<String>
-
-    init(pinnedKeyHashes: Set<String>) {
-        self.pinnedKeyHashes = pinnedKeyHashes
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        didReceive challenge: URLAuthenticationChallenge
-    ) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
-        guard challenge.protectionSpace.authenticationMethod
-                == NSURLAuthenticationMethodServerTrust,
-              let trust = challenge.protectionSpace.serverTrust else {
-            return (.performDefaultHandling, nil)
-        }
-
-        // Evaluate the trust chain
-        var error: CFError?
-        guard SecTrustEvaluateWithError(trust, &error) else {
-            return (.cancelAuthenticationChallenge, nil)
-        }
-
-        // Extract the leaf certificate's public key
-        guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
-              let leafCert = chain.first,
-              let publicKey = SecCertificateCopyKey(leafCert),
-              let publicKeyData = SecKeyCopyExternalRepresentation(
-                  publicKey, nil
-              ) as Data? else {
-            return (.cancelAuthenticationChallenge, nil)
-        }
-
-        let keyHash = SHA256.hash(data: publicKeyData)
-        let hashString = Data(keyHash).base64EncodedString()
-
-        if pinnedKeyHashes.contains(hashString) {
-            return (.useCredential, URLCredential(trust: trust))
-        }
-
-        return (.cancelAuthenticationChallenge, nil)
-    }
-}
-
-// Usage
-let delegate = PinningDelegate(pinnedKeyHashes: [
-    "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",  // Primary
-    "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",  // Backup
-])
-
-let session = URLSession(
-    configuration: .default,
-    delegate: delegate,
-    delegateQueue: nil
-)
-```
-
-**Important considerations:**
-- Pin at least two keys (primary + backup) to avoid lockout during rotation.
-- Have a remote kill switch (feature flag) to disable pinning in emergencies.
-- Test certificate rotation in staging before deploying to production.
-- Do not pin intermediate CA certificates -- they rotate more frequently.
-
----
-
-## Request Logging / Debugging Middleware
-
-Log outgoing requests and incoming responses for debugging. Disable or
-reduce verbosity in release builds.
-
-```swift
-struct LoggingMiddleware: RequestMiddleware {
-    let logger: Logger
-
-    func prepare(_ request: URLRequest) async throws -> URLRequest {
-        #if DEBUG
-        let method = request.httpMethod ?? "GET"
-        let url = request.url?.absoluteString ?? "unknown"
-        logger.debug("[\(method)] \(url)")
-        if let headers = request.allHTTPHeaderFields {
-            for (key, value) in headers where key != "Authorization" {
-                logger.debug("  \(key): \(value)")
-            }
-        }
-        if let body = request.httpBody, body.count < 10_000 {
-            logger.debug("  Body: \(String(data: body, encoding: .utf8) ?? "<binary>")")
-        }
-        #endif
-        return request
-    }
-}
-```
-
-### Response Logging
-
-To log responses, wrap the transport call rather than using middleware:
-
-```swift
-func loggedRequest<T: Decodable & Sendable>(
-    _ type: T.Type,
-    endpoint: Endpoint,
-    logger: Logger
-) async throws -> T {
-    let start = ContinuousClock().now
-    do {
-        let result: T = try await request(type, endpoint: endpoint)
-        let elapsed = ContinuousClock().now - start
-        logger.debug("[\(endpoint.method.rawValue)] \(endpoint.path) -> 200 (\(elapsed))")
-        return result
-    } catch {
-        let elapsed = ContinuousClock().now - start
-        logger.error("[\(endpoint.method.rawValue)] \(endpoint.path) -> ERROR (\(elapsed)): \(error)")
-        throw error
-    }
-}
-```
-
----
-
-## Request Caching Strategies
-
-### URLCache Configuration
-
-```swift
-// 50 MB memory / 200 MB disk cache
-let cache = URLCache(
-    memoryCapacity: 50 * 1024 * 1024,
-    diskCapacity: 200 * 1024 * 1024,
-    directory: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)
-        .first?.appendingPathComponent("URLCache")
-)
-
-let config = URLSessionConfiguration.default
-config.urlCache = cache
-config.requestCachePolicy = .returnCacheDataElseLoad
-
-let session = URLSession(configuration: config)
-```
-
-### Per-Request Cache Control
-
-```swift
-// Force fresh data
-var request = URLRequest(url: url)
-request.cachePolicy = .reloadIgnoringLocalCacheData
-
-// Use cached if available
-request.cachePolicy = .returnCacheDataElseLoad
-
-// Cache only (offline mode)
-request.cachePolicy = .returnCacheDataDontLoad
-```
-
-### ETag / If-None-Match
-
-```swift
-func fetchWithETag<T: Decodable & Sendable>(
-    _ type: T.Type,
-    url: URL,
-    cachedETag: String?,
-    cachedData: Data?
-) async throws -> (T, String?) {
-    var request = URLRequest(url: url)
-    if let etag = cachedETag {
-        request.setValue(etag, forHTTPHeaderField: "If-None-Match")
-    }
-
-    let (data, response) = try await URLSession.shared.data(for: request)
-    guard let http = response as? HTTPURLResponse else {
-        throw NetworkError.invalidResponse
-    }
-
-    if http.statusCode == 304, let cachedData {
-        // Not modified -- use cached data
-        let decoded = try JSONDecoder().decode(T.self, from: cachedData)
-        return (decoded, cachedETag)
-    }
-
-    let newETag = http.value(forHTTPHeaderField: "ETag")
-    let decoded = try JSONDecoder().decode(T.self, from: data)
-    return (decoded, newETag)
-}
-```
-
----
-
-## Server-Sent Events (SSE) Parsing
-
-Use `bytes(for:)` to consume a streaming SSE endpoint.
-
-```swift
-struct ServerSentEvent: Sendable {
-    var event: String?
-    var data: String
-    var id: String?
-}
-
-func sseStream(from url: URL) -> AsyncThrowingStream<ServerSentEvent, Error> {
-    AsyncThrowingStream { continuation in
-        let task = Task {
-            do {
-                var request = URLRequest(url: url)
-                request.setValue("text/event-stream", forHTTPHeaderField: "Accept")
-
-                let (bytes, _) = try await URLSession.shared.bytes(for: request)
-
-                var currentEvent: String?
-                var currentData = ""
-                var currentId: String?
-
-                for try await line in bytes.lines {
-                    if line.isEmpty {
-                        // Empty line = dispatch event
-                        if !currentData.isEmpty {
-                            continuation.yield(ServerSentEvent(
-                                event: currentEvent,
-                                data: currentData.trimmingCharacters(in: .newlines),
-                                id: currentId
-                            ))
-                        }
-                        currentEvent = nil
-                        currentData = ""
-                        currentId = nil
-                    } else if line.hasPrefix("event:") {
-                        currentEvent = String(line.dropFirst(6)).trimmingCharacters(in: .whitespaces)
-                    } else if line.hasPrefix("data:") {
-                        let value = String(line.dropFirst(5)).trimmingCharacters(in: .whitespaces)
-                        currentData += currentData.isEmpty ? value : "\n" + value
-                    } else if line.hasPrefix("id:") {
-                        currentId = String(line.dropFirst(3)).trimmingCharacters(in: .whitespaces)
-                    }
-                }
-                continuation.finish()
-            } catch {
-                continuation.finish(throwing: error)
-            }
-        }
-        continuation.onTermination = { _ in task.cancel() }
-    }
-}
-```
-
----
-
-## Configured URLSession for Production
-
-```swift
-enum SessionFactory {
-    static func makeDefault(delegate: (any URLSessionDelegate)? = nil) -> URLSession {
-        let config = URLSessionConfiguration.default
-        config.timeoutIntervalForRequest = 30
-        config.timeoutIntervalForResource = 300
-        config.waitsForConnectivity = true
-        config.httpMaximumConnectionsPerHost = 6
-        config.requestCachePolicy = .useProtocolCachePolicy
-        config.httpAdditionalHeaders = [
-            "Accept": "application/json",
-            "Accept-Encoding": "gzip, deflate, br",
-        ]
-
-        let cache = URLCache(
-            memoryCapacity: 25 * 1024 * 1024,
-            diskCapacity: 100 * 1024 * 1024
-        )
-        config.urlCache = cache
-
-        return URLSession(
-            configuration: config,
-            delegate: delegate,
-            delegateQueue: nil
-        )
-    }
-}
-```
+# URLSession Patterns Reference
+
+Complete implementation patterns for URLSession-based networking. Each
+section is self-contained with production-ready code.
+
+---
+
+## Contents
+
+- [Complete API Client with Protocol](#complete-api-client-with-protocol)
+- [Request Builder Pattern](#request-builder-pattern)
+- [Multipart Form Upload](#multipart-form-upload)
+- [Download with Progress Tracking](#download-with-progress-tracking)
+- [Cursor-Based Pagination](#cursor-based-pagination)
+- [Offset-Based Pagination](#offset-based-pagination)
+- [URLProtocol Mock for Testing](#urlprotocol-mock-for-testing)
+- [Retry with Exponential Backoff](#retry-with-exponential-backoff)
+- [Certificate Pinning (URLSessionDelegate)](#certificate-pinning-urlsessiondelegate)
+- [Request Logging / Debugging Middleware](#request-logging-debugging-middleware)
+- [Request Caching Strategies](#request-caching-strategies)
+- [Server-Sent Events (SSE) Parsing](#server-sent-events-sse-parsing)
+- [Configured URLSession for Production](#configured-urlsession-for-production)
+
+## Complete API Client with Protocol
+
+A full-featured client with middleware support, configurable decoding,
+and response validation.
+
+### Protocol
+
+```swift
+protocol APIClientProtocol: Sendable {
+    func request<T: Decodable & Sendable>(
+        _ type: T.Type,
+        endpoint: Endpoint
+    ) async throws -> T
+
+    func request(endpoint: Endpoint) async throws
+
+    func upload<T: Decodable & Sendable>(
+        _ type: T.Type,
+        endpoint: Endpoint,
+        body: Data
+    ) async throws -> T
+}
+```
+
+### Endpoint Definition
+
+```swift
+struct Endpoint: Sendable {
+    let path: String
+    var method: HTTPMethod = .get
+    var queryItems: [URLQueryItem] = []
+    var headers: [String: String] = [:]
+    var body: Data? = nil
+    var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
+    var timeoutInterval: TimeInterval = 30
+
+    enum HTTPMethod: String, Sendable {
+        case get = "GET"
+        case post = "POST"
+        case put = "PUT"
+        case patch = "PATCH"
+        case delete = "DELETE"
+    }
+
+    func urlRequest(relativeTo baseURL: URL) -> URLRequest {
+        var components = URLComponents(
+            url: baseURL.appendingPathComponent(path),
+            resolvingAgainstBaseURL: true
+        )!
+        if !queryItems.isEmpty {
+            components.queryItems = queryItems
+        }
+        var request = URLRequest(url: components.url!)
+        request.httpMethod = method.rawValue
+        request.httpBody = body
+        request.cachePolicy = cachePolicy
+        request.timeoutInterval = timeoutInterval
+        for (key, value) in headers {
+            request.setValue(value, forHTTPHeaderField: key)
+        }
+        return request
+    }
+}
+```
+
+### Client Implementation
+
+```swift
+final class APIClient: APIClientProtocol {
+    private let baseURL: URL
+    private let session: URLSession
+    private let decoder: JSONDecoder
+    private let encoder: JSONEncoder
+    private let middlewares: [any RequestMiddleware]
+
+    init(
+        baseURL: URL,
+        session: URLSession = .shared,
+        decoder: JSONDecoder = {
+            let d = JSONDecoder()
+            d.dateDecodingStrategy = .iso8601
+            d.keyDecodingStrategy = .convertFromSnakeCase
+            return d
+        }(),
+        encoder: JSONEncoder = {
+            let e = JSONEncoder()
+            e.dateEncodingStrategy = .iso8601
+            e.keyEncodingStrategy = .convertToSnakeCase
+            return e
+        }(),
+        middlewares: [any RequestMiddleware] = []
+    ) {
+        self.baseURL = baseURL
+        self.session = session
+        self.decoder = decoder
+        self.encoder = encoder
+        self.middlewares = middlewares
+    }
+
+    func request<T: Decodable & Sendable>(
+        _ type: T.Type,
+        endpoint: Endpoint
+    ) async throws -> T {
+        let request = try await prepareRequest(for: endpoint)
+        let (data, response) = try await session.data(for: request)
+        try validateResponse(response, data: data)
+        return try decoder.decode(T.self, from: data)
+    }
+
+    func request(endpoint: Endpoint) async throws {
+        let request = try await prepareRequest(for: endpoint)
+        let (data, response) = try await session.data(for: request)
+        try validateResponse(response, data: data)
+    }
+
+    func upload<T: Decodable & Sendable>(
+        _ type: T.Type,
+        endpoint: Endpoint,
+        body: Data
+    ) async throws -> T {
+        var request = try await prepareRequest(for: endpoint)
+        request.httpBody = body
+        let (data, response) = try await session.upload(for: request, from: body)
+        try validateResponse(response, data: data)
+        return try decoder.decode(T.self, from: data)
+    }
+
+    // MARK: - Convenience methods
+
+    func get<T: Decodable & Sendable>(
+        _ type: T.Type,
+        path: String,
+        queryItems: [URLQueryItem] = []
+    ) async throws -> T {
+        try await request(type, endpoint: Endpoint(
+            path: path,
+            method: .get,
+            queryItems: queryItems
+        ))
+    }
+
+    func post<T: Decodable & Sendable, B: Encodable & Sendable>(
+        _ type: T.Type,
+        path: String,
+        body: B
+    ) async throws -> T {
+        let bodyData = try encoder.encode(body)
+        return try await request(type, endpoint: Endpoint(
+            path: path,
+            method: .post,
+            headers: ["Content-Type": "application/json"],
+            body: bodyData
+        ))
+    }
+
+    func delete(path: String) async throws {
+        try await request(endpoint: Endpoint(path: path, method: .delete))
+    }
+
+    // MARK: - Internal
+
+    private func prepareRequest(for endpoint: Endpoint) async throws -> URLRequest {
+        var request = endpoint.urlRequest(relativeTo: baseURL)
+        for middleware in middlewares {
+            request = try await middleware.prepare(request)
+        }
+        return request
+    }
+
+    private func validateResponse(_ response: URLResponse, data: Data) throws {
+        guard let http = response as? HTTPURLResponse else {
+            throw NetworkError.invalidResponse
+        }
+        guard (200..<300).contains(http.statusCode) else {
+            let apiError = try? decoder.decode(APIErrorBody.self, from: data)
+            throw NetworkError.httpError(
+                statusCode: http.statusCode,
+                data: data,
+                message: apiError?.message
+            )
+        }
+    }
+}
+```
+
+### Error Types
+
+```swift
+enum NetworkError: Error, Sendable, LocalizedError {
+    case invalidResponse
+    case httpError(statusCode: Int, data: Data, message: String? = nil)
+    case noConnection
+    case timedOut
+    case cancelled
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidResponse:
+            return "Invalid server response"
+        case .httpError(let code, _, let message):
+            return message ?? "HTTP error \(code)"
+        case .noConnection:
+            return "No internet connection"
+        case .timedOut:
+            return "Request timed out"
+        case .cancelled:
+            return nil
+        }
+    }
+
+    static func from(_ urlError: URLError) -> NetworkError {
+        switch urlError.code {
+        case .notConnectedToInternet, .networkConnectionLost:
+            return .noConnection
+        case .timedOut:
+            return .timedOut
+        case .cancelled:
+            return .cancelled
+        default:
+            return .invalidResponse
+        }
+    }
+}
+
+struct APIErrorBody: Decodable, Sendable {
+    let code: String?
+    let message: String?
+}
+```
+
+---
+
+## Request Builder Pattern
+
+For complex request construction, a builder provides a fluent API that
+reduces errors.
+
+```swift
+struct RequestBuilder: Sendable {
+    private var method: String = "GET"
+    private var path: String
+    private var baseURL: URL
+    private var queryItems: [URLQueryItem] = []
+    private var headers: [String: String] = [:]
+    private var body: Data?
+    private var cachePolicy: URLRequest.CachePolicy = .useProtocolCachePolicy
+    private var timeout: TimeInterval = 30
+
+    init(baseURL: URL, path: String) {
+        self.baseURL = baseURL
+        self.path = path
+    }
+
+    func method(_ method: String) -> RequestBuilder {
+        var copy = self
+        copy.method = method
+        return copy
+    }
+
+    func query(_ name: String, _ value: String?) -> RequestBuilder {
+        guard let value else { return self }
+        var copy = self
+        copy.queryItems.append(URLQueryItem(name: name, value: value))
+        return copy
+    }
+
+    func header(_ name: String, _ value: String) -> RequestBuilder {
+        var copy = self
+        copy.headers[name] = value
+        return copy
+    }
+
+    func jsonBody<T: Encodable>(_ value: T) throws -> RequestBuilder {
+        var copy = self
+        copy.body = try JSONEncoder().encode(value)
+        copy.headers["Content-Type"] = "application/json"
+        return copy
+    }
+
+    func timeout(_ interval: TimeInterval) -> RequestBuilder {
+        var copy = self
+        copy.timeout = interval
+        return copy
+    }
+
+    func cachePolicy(_ policy: URLRequest.CachePolicy) -> RequestBuilder {
+        var copy = self
+        copy.cachePolicy = policy
+        return copy
+    }
+
+    func build() -> URLRequest {
+        var components = URLComponents(
+            url: baseURL.appendingPathComponent(path),
+            resolvingAgainstBaseURL: true
+        )!
+        if !queryItems.isEmpty {
+            components.queryItems = queryItems
+        }
+        var request = URLRequest(url: components.url!)
+        request.httpMethod = method
+        request.httpBody = body
+        request.cachePolicy = cachePolicy
+        request.timeoutInterval = timeout
+        for (key, value) in headers {
+            request.setValue(value, forHTTPHeaderField: key)
+        }
+        return request
+    }
+}
+
+// Usage
+let request = try RequestBuilder(baseURL: apiURL, path: "users")
+    .method("POST")
+    .header("X-Request-ID", UUID().uuidString)
+    .jsonBody(CreateUserRequest(name: "Alice", email: "alice@example.com"))
+    .timeout(15)
+    .build()
+```
+
+---
+
+## Multipart Form Upload
+
+Multipart/form-data uploads are common for file attachments. Build the
+body manually -- no third-party library needed.
+
+```swift
+struct MultipartFormData: Sendable {
+    private let boundary: String
+    private var parts: [Part] = []
+
+    init(boundary: String = UUID().uuidString) {
+        self.boundary = boundary
+    }
+
+    var contentType: String {
+        "multipart/form-data; boundary=\(boundary)"
+    }
+
+    mutating func addField(name: String, value: String) {
+        parts.append(Part(
+            headers: "Content-Disposition: form-data; name=\"\(name)\"",
+            body: Data(value.utf8)
+        ))
+    }
+
+    mutating func addFile(
+        name: String,
+        filename: String,
+        mimeType: String,
+        data: Data
+    ) {
+        parts.append(Part(
+            headers: """
+            Content-Disposition: form-data; name="\(name)"; filename="\(filename)"\r
+            Content-Type: \(mimeType)
+            """,
+            body: data
+        ))
+    }
+
+    func encode() -> Data {
+        var data = Data()
+        let crlf = "\r\n"
+        for part in parts {
+            data.append("--\(boundary)\(crlf)")
+            data.append("\(part.headers)\(crlf)\(crlf)")
+            data.append(part.body)
+            data.append(crlf)
+        }
+        data.append("--\(boundary)--\(crlf)")
+        return data
+    }
+
+    private struct Part: Sendable {
+        let headers: String
+        let body: Data
+    }
+}
+
+extension Data {
+    mutating func append(_ string: String) {
+        append(Data(string.utf8))
+    }
+}
+
+// Usage
+var form = MultipartFormData()
+form.addField(name: "title", value: "Profile Photo")
+form.addFile(
+    name: "image",
+    filename: "photo.jpg",
+    mimeType: "image/jpeg",
+    data: imageData
+)
+
+var request = URLRequest(url: uploadURL)
+request.httpMethod = "POST"
+request.setValue(form.contentType, forHTTPHeaderField: "Content-Type")
+request.httpBody = form.encode()
+
+let (data, response) = try await URLSession.shared.upload(
+    for: request,
+    from: form.encode()
+)
+```
+
+---
+
+## Download with Progress Tracking
+
+Use `bytes(for:)` for real-time progress. The response includes
+`expectedContentLength` for calculating percentage.
+
+```swift
+@available(iOS 15.0, *)
+func downloadWithProgress(
+    from url: URL,
+    progressHandler: @Sendable (Double) -> Void
+) async throws -> Data {
+    let (bytes, response) = try await URLSession.shared.bytes(from: url)
+
+    let expectedLength = response.expectedContentLength
+    var receivedData = Data()
+    if expectedLength > 0 {
+        receivedData.reserveCapacity(Int(expectedLength))
+    }
+
+    var receivedLength: Int64 = 0
+    for try await byte in bytes {
+        receivedData.append(byte)
+        receivedLength += 1
+        if expectedLength > 0 {
+            let progress = Double(receivedLength) / Double(expectedLength)
+            progressHandler(progress)
+        }
+    }
+
+    return receivedData
+}
+```
+
+For large files, prefer `URLSessionDownloadTask` with a delegate for
+better memory efficiency and background support. See
+`references/background-websocket.md`.
+
+### Download to File with Progress (Delegate-Based)
+
+```swift
+@available(iOS 15.0, *)
+final class DownloadManager: NSObject, URLSessionDownloadDelegate, Sendable {
+    private let continuation: AsyncStream<DownloadEvent>.Continuation
+
+    enum DownloadEvent: Sendable {
+        case progress(Double)
+        case completed(URL)
+        case failed(Error)
+    }
+
+    static func download(from url: URL) -> AsyncStream<DownloadEvent> {
+        AsyncStream { continuation in
+            let manager = DownloadManager(continuation: continuation)
+            let session = URLSession(
+                configuration: .default,
+                delegate: manager,
+                delegateQueue: nil
+            )
+            session.downloadTask(with: url).resume()
+        }
+    }
+
+    private init(continuation: AsyncStream<DownloadEvent>.Continuation) {
+        self.continuation = continuation
+    }
+
+    nonisolated func urlSession(
+        _ session: URLSession,
+        downloadTask: URLSessionDownloadTask,
+        didFinishDownloadingTo location: URL
+    ) {
+        // Move file to permanent location before this method returns
+        let destination = FileManager.default.temporaryDirectory
+            .appendingPathComponent(UUID().uuidString)
+        do {
+            try FileManager.default.moveItem(at: location, to: destination)
+            continuation.yield(.completed(destination))
+        } catch {
+            continuation.yield(.failed(error))
+        }
+        continuation.finish()
+    }
+
+    nonisolated func urlSession(
+        _ session: URLSession,
+        downloadTask: URLSessionDownloadTask,
+        didWriteData bytesWritten: Int64,
+        totalBytesWritten: Int64,
+        totalBytesExpectedToWrite: Int64
+    ) {
+        guard totalBytesExpectedToWrite > 0 else { return }
+        let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
+        continuation.yield(.progress(progress))
+    }
+
+    nonisolated func urlSession(
+        _ session: URLSession,
+        task: URLSessionTask,
+        didCompleteWithError error: (any Error)?
+    ) {
+        if let error {
+            continuation.yield(.failed(error))
+            continuation.finish()
+        }
+    }
+}
+```
+
+---
+
+## Cursor-Based Pagination
+
+A reusable paginator that conforms to `AsyncSequence`, yielding pages
+of results until the server indicates no more data.
+
+```swift
+struct PageResponse<T: Decodable & Sendable>: Decodable, Sendable {
+    let data: [T]
+    let pagination: PaginationInfo
+}
+
+struct PaginationInfo: Decodable, Sendable {
+    let nextCursor: String?
+    let hasMore: Bool
+}
+
+struct CursorPaginator<T: Decodable & Sendable>: AsyncSequence {
+    typealias Element = [T]
+
+    private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
+
+    init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
+        self.fetchPage = fetchPage
+    }
+
+    func makeAsyncIterator() -> Iterator {
+        Iterator(fetchPage: fetchPage)
+    }
+
+    struct Iterator: AsyncIteratorProtocol {
+        private let fetchPage: @Sendable (String?) async throws -> PageResponse<T>
+        private var cursor: String?
+        private var exhausted = false
+
+        init(fetchPage: @escaping @Sendable (String?) async throws -> PageResponse<T>) {
+            self.fetchPage = fetchPage
+        }
+
+        mutating func next() async throws -> [T]? {
+            guard !exhausted else { return nil }
+            try Task.checkCancellation()
+
+            let response = try await fetchPage(cursor)
+            cursor = response.pagination.nextCursor
+            exhausted = !response.pagination.hasMore
+
+            return response.data.isEmpty ? nil : response.data
+        }
+    }
+}
+
+// Usage
+let paginator = CursorPaginator<User> { cursor in
+    var queryItems = [URLQueryItem(name: "limit", value: "50")]
+    if let cursor {
+        queryItems.append(URLQueryItem(name: "cursor", value: cursor))
+    }
+    return try await client.get(
+        PageResponse<User>.self,
+        path: "users",
+        queryItems: queryItems
+    )
+}
+
+var allUsers: [User] = []
+for try await batch in paginator {
+    allUsers.append(contentsOf: batch)
+}
+```
+
+---
+
+## Offset-Based Pagination
+
+```swift
+struct OffsetPaginator<T: Decodable & Sendable>: AsyncSequence {
+    typealias Element = [T]
+
+    private let pageSize: Int
+    private let fetchPage: @Sendable (Int, Int) async throws -> [T]
+
+    init(
+        pageSize: Int = 20,
+        fetchPage: @escaping @Sendable (_ offset: Int, _ limit: Int) async throws -> [T]
+    ) {
+        self.pageSize = pageSize
+        self.fetchPage = fetchPage
+    }
+
+    func makeAsyncIterator() -> Iterator {
+        Iterator(pageSize: pageSize, fetchPage: fetchPage)
+    }
+
+    struct Iterator: AsyncIteratorProtocol {
+        private let pageSize: Int
+        private let fetchPage: @Sendable (Int, Int) async throws -> [T]
+        private var offset = 0
+        private var exhausted = false
+
+        init(
+            pageSize: Int,
+            fetchPage: @escaping @Sendable (Int, Int) async throws -> [T]
+        ) {
+            self.pageSize = pageSize
+            self.fetchPage = fetchPage
+        }
+
+        mutating func next() async throws -> [T]? {
+            guard !exhausted else { return nil }
+            try Task.checkCancellation()
+
+            let items = try await fetchPage(offset, pageSize)
+            offset += items.count
+            if items.count < pageSize { exhausted = true }
+
+            return items.isEmpty ? nil : items
+        }
+    }
+}
+```
+
+---
+
+## URLProtocol Mock for Testing
+
+`URLProtocol` is the correct way to mock network responses at the
+transport level. It works with any URLSession configuration and does
+not require changing production code.
+
+```swift
+final class MockURLProtocol: URLProtocol {
+    nonisolated(unsafe) static var requestHandler: ((URLRequest) throws -> (HTTPURLResponse, Data))?
+
+    override class func canInit(with request: URLRequest) -> Bool { true }
+
+    override class func canonicalRequest(for request: URLRequest) -> URLRequest { request }
+
+    override func startLoading() {
+        guard let handler = Self.requestHandler else {
+            fatalError("MockURLProtocol.requestHandler is not set")
+        }
+
+        do {
+            let (response, data) = try handler(request)
+            client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
+            client?.urlProtocol(self, didLoad: data)
+            client?.urlProtocolDidFinishLoading(self)
+        } catch {
+            client?.urlProtocol(self, didFailWithError: error)
+        }
+    }
+
+    override func stopLoading() {}
+}
+```
+
+### Test Setup
+
+```swift
+import Testing
+
+@Suite struct APIClientTests {
+    let client: APIClient
+    let session: URLSession
+
+    init() {
+        let config = URLSessionConfiguration.ephemeral
+        config.protocolClasses = [MockURLProtocol.self]
+        session = URLSession(configuration: config)
+        client = APIClient(
+            baseURL: URL(string: "https://api.example.com")!,
+            session: session
+        )
+    }
+
+    @Test func fetchUsersDecodesCorrectly() async throws {
+        let usersJSON = """
+        [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
+        """
+        MockURLProtocol.requestHandler = { request in
+            #expect(request.url?.path == "/users")
+            let response = HTTPURLResponse(
+                url: request.url!,
+                statusCode: 200,
+                httpVersion: nil,
+                headerFields: ["Content-Type": "application/json"]
+            )!
+            return (response, Data(usersJSON.utf8))
+        }
+
+        let users: [User] = try await client.get([User].self, path: "users")
+        #expect(users.count == 2)
+        #expect(users[0].name == "Alice")
+    }
+
+    @Test func fetchReturnsHTTPError() async throws {
+        MockURLProtocol.requestHandler = { request in
+            let response = HTTPURLResponse(
+                url: request.url!,
+                statusCode: 404,
+                httpVersion: nil,
+                headerFields: nil
+            )!
+            return (response, Data())
+        }
+
+        await #expect(throws: NetworkError.self) {
+            let _: [User] = try await client.get([User].self, path: "missing")
+        }
+    }
+
+    @Test func requestIncludesAuthHeader() async throws {
+        let authClient = APIClient(
+            baseURL: URL(string: "https://api.example.com")!,
+            session: session,
+            middlewares: [AuthMiddleware { "test-token" }]
+        )
+
+        MockURLProtocol.requestHandler = { request in
+            #expect(request.value(forHTTPHeaderField: "Authorization") == "Bearer test-token")
+            let response = HTTPURLResponse(
+                url: request.url!, statusCode: 200, httpVersion: nil, headerFields: nil
+            )!
+            return (response, Data("{}".utf8))
+        }
+
+        let _: EmptyResponse = try await authClient.get(EmptyResponse.self, path: "me")
+    }
+}
+
+struct EmptyResponse: Decodable, Sendable {}
+```
+
+---
+
+## Retry with Exponential Backoff
+
+Respect cancellation. Do not retry client errors (4xx except 429 rate
+limiting). Include jitter to prevent thundering herd.
+
+```swift
+func withRetry<T: Sendable>(
+    maxAttempts: Int = 3,
+    initialDelay: Duration = .seconds(1),
+    maxDelay: Duration = .seconds(30),
+    shouldRetry: @Sendable (Error) -> Bool = { error in
+        if error is CancellationError { return false }
+        if case NetworkError.httpError(let code, _, _) = error {
+            return code >= 500 || code == 429
+        }
+        if let urlError = error as? URLError {
+            return [.timedOut, .networkConnectionLost, .notConnectedToInternet]
+                .contains(urlError.code)
+        }
+        return false
+    },
+    operation: @Sendable () async throws -> T
+) async throws -> T {
+    var lastError: Error?
+
+    for attempt in 0..<maxAttempts {
+        try Task.checkCancellation()
+        do {
+            return try await operation()
+        } catch {
+            lastError = error
+            guard shouldRetry(error), attempt < maxAttempts - 1 else {
+                throw error
+            }
+            // Exponential backoff with jitter
+            let base = Double(initialDelay.components.seconds) * pow(2.0, Double(attempt))
+            let capped = min(base, Double(maxDelay.components.seconds))
+            let jitter = Double.random(in: 0...(capped * 0.1))
+            let delay = Duration.seconds(capped + jitter)
+            try await Task.sleep(for: delay)
+        }
+    }
+
+    throw lastError!
+}
+
+// Usage
+let users = try await withRetry {
+    try await client.get([User].self, path: "users")
+}
+```
+
+---
+
+## Certificate Pinning (URLSessionDelegate)
+
+Pin the server's public key hash rather than the certificate itself.
+Certificates rotate; public keys are more stable. Always include a
+backup pin.
+
+```swift
+import CryptoKit
+
+final class PinningDelegate: NSObject, URLSessionDelegate, Sendable {
+    /// SHA-256 hashes of Subject Public Key Info (SPKI) in base64
+    private let pinnedKeyHashes: Set<String>
+
+    init(pinnedKeyHashes: Set<String>) {
+        self.pinnedKeyHashes = pinnedKeyHashes
+    }
+
+    nonisolated func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge
+    ) async -> (URLSession.AuthChallengeDisposition, URLCredential?) {
+        guard challenge.protectionSpace.authenticationMethod
+                == NSURLAuthenticationMethodServerTrust,
+              let trust = challenge.protectionSpace.serverTrust else {
+            return (.performDefaultHandling, nil)
+        }
+
+        // Evaluate the trust chain
+        var error: CFError?
+        guard SecTrustEvaluateWithError(trust, &error) else {
+            return (.cancelAuthenticationChallenge, nil)
+        }
+
+        // Extract the leaf certificate's public key
+        guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
+              let leafCert = chain.first,
+              let publicKey = SecCertificateCopyKey(leafCert),
+              let publicKeyData = SecKeyCopyExternalRepresentation(
+                  publicKey, nil
+              ) as Data? else {
+            return (.cancelAuthenticationChallenge, nil)
+        }
+
+        let keyHash = SHA256.hash(data: publicKeyData)
+        let hashString = Data(keyHash).base64EncodedString()
+
+        if pinnedKeyHashes.contains(hashString) {
+            return (.useCredential, URLCredential(trust: trust))
+        }
+
+        return (.cancelAuthenticationChallenge, nil)
+    }
+}
+
+// Usage
+let delegate = PinningDelegate(pinnedKeyHashes: [
+    "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=",  // Primary
+    "CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",  // Backup
+])
+
+let session = URLSession(
+    configuration: .default,
+    delegate: delegate,
+    delegateQueue: nil
+)
+```
+
+**Important considerations:**
+- Pin at least two keys (primary + backup) to avoid lockout during rotation.
+- Have a remote kill switch (feature flag) to disable pinning in emergencies.
+- Test certificate rotation in staging before deploying to production.
+- Do not pin intermediate CA certificates -- they rotate more frequently.
+
+---
+
+## Request Logging / Debugging Middleware
+
+Log outgoing requests and incoming responses for debugging. Disable or
+reduce verbosity in release builds.
+
+```swift
+struct LoggingMiddleware: RequestMiddleware {
+    let logger: Logger
+
+    func prepare(_ request: URLRequest) async throws -> URLRequest {
+        #if DEBUG
+        let method = request.httpMethod ?? "GET"
+        let url = request.url?.absoluteString ?? "unknown"
+        logger.debug("[\(method)] \(url)")
+        if let headers = request.allHTTPHeaderFields {
+            for (key, value) in headers where key != "Authorization" {
+                logger.debug("  \(key): \(value)")
+            }
+        }
+        if let body = request.httpBody, body.count < 10_000 {
+            logger.debug("  Body: \(String(data: body, encoding: .utf8) ?? "<binary>")")
+        }
+        #endif
+        return request
+    }
+}
+```
+
+### Response Logging
+
+To log responses, wrap the transport call rather than using middleware:
+
+```swift
+func loggedRequest<T: Decodable & Sendable>(
+    _ type: T.Type,
+    endpoint: Endpoint,
+    logger: Logger
+) async throws -> T {
+    let start = ContinuousClock().now
+    do {
+        let result: T = try await request(type, endpoint: endpoint)
+        let elapsed = ContinuousClock().now - start
+        logger.debug("[\(endpoint.method.rawValue)] \(endpoint.path) -> 200 (\(elapsed))")
+        return result
+    } catch {
+        let elapsed = ContinuousClock().now - start
+        logger.error("[\(endpoint.method.rawValue)] \(endpoint.path) -> ERROR (\(elapsed)): \(error)")
+        throw error
+    }
+}
+```
+
+---
+
+## Request Caching Strategies
+
+### URLCache Configuration
+
+```swift
+// 50 MB memory / 200 MB disk cache
+let cache = URLCache(
+    memoryCapacity: 50 * 1024 * 1024,
+    diskCapacity: 200 * 1024 * 1024,
+    directory: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)
+        .first?.appendingPathComponent("URLCache")
+)
+
+let config = URLSessionConfiguration.default
+config.urlCache = cache
+config.requestCachePolicy = .returnCacheDataElseLoad
+
+let session = URLSession(configuration: config)
+```
+
+### Per-Request Cache Control
+
+```swift
+// Force fresh data
+var request = URLRequest(url: url)
+request.cachePolicy = .reloadIgnoringLocalCacheData
+
+// Use cached if available
+request.cachePolicy = .returnCacheDataElseLoad
+
+// Cache only (offline mode)
+request.cachePolicy = .returnCacheDataDontLoad
+```
+
+### ETag / If-None-Match
+
+```swift
+func fetchWithETag<T: Decodable & Sendable>(
+    _ type: T.Type,
+    url: URL,
+    cachedETag: String?,
+    cachedData: Data?
+) async throws -> (T, String?) {
+    var request = URLRequest(url: url)
+    if let etag = cachedETag {
+        request.setValue(etag, forHTTPHeaderField: "If-None-Match")
+    }
+
+    let (data, response) = try await URLSession.shared.data(for: request)
+    guard let http = response as? HTTPURLResponse else {
+        throw NetworkError.invalidResponse
+    }
+
+    if http.statusCode == 304, let cachedData {
+        // Not modified -- use cached data
+        let decoded = try JSONDecoder().decode(T.self, from: cachedData)
+        return (decoded, cachedETag)
+    }
+
+    let newETag = http.value(forHTTPHeaderField: "ETag")
+    let decoded = try JSONDecoder().decode(T.self, from: data)
+    return (decoded, newETag)
+}
+```
+
+---
+
+## Server-Sent Events (SSE) Parsing
+
+Use `bytes(for:)` to consume a streaming SSE endpoint.
+
+```swift
+struct ServerSentEvent: Sendable {
+    var event: String?
+    var data: String
+    var id: String?
+}
+
+func sseStream(from url: URL) -> AsyncThrowingStream<ServerSentEvent, Error> {
+    AsyncThrowingStream { continuation in
+        let task = Task {
+            do {
+                var request = URLRequest(url: url)
+                request.setValue("text/event-stream", forHTTPHeaderField: "Accept")
+
+                let (bytes, _) = try await URLSession.shared.bytes(for: request)
+
+                var currentEvent: String?
+                var currentData = ""
+                var currentId: String?
+
+                for try await line in bytes.lines {
+                    if line.isEmpty {
+                        // Empty line = dispatch event
+                        if !currentData.isEmpty {
+                            continuation.yield(ServerSentEvent(
+                                event: currentEvent,
+                                data: currentData.trimmingCharacters(in: .newlines),
+                                id: currentId
+                            ))
+                        }
+                        currentEvent = nil
+                        currentData = ""
+                        currentId = nil
+                    } else if line.hasPrefix("event:") {
+                        currentEvent = String(line.dropFirst(6)).trimmingCharacters(in: .whitespaces)
+                    } else if line.hasPrefix("data:") {
+                        let value = String(line.dropFirst(5)).trimmingCharacters(in: .whitespaces)
+                        currentData += currentData.isEmpty ? value : "\n" + value
+                    } else if line.hasPrefix("id:") {
+                        currentId = String(line.dropFirst(3)).trimmingCharacters(in: .whitespaces)
+                    }
+                }
+                continuation.finish()
+            } catch {
+                continuation.finish(throwing: error)
+            }
+        }
+        continuation.onTermination = { _ in task.cancel() }
+    }
+}
+```
+
+---
+
+## Configured URLSession for Production
+
+```swift
+enum SessionFactory {
+    static func makeDefault(delegate: (any URLSessionDelegate)? = nil) -> URLSession {
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 30
+        config.timeoutIntervalForResource = 300
+        config.waitsForConnectivity = true
+        config.httpMaximumConnectionsPerHost = 6
+        config.requestCachePolicy = .useProtocolCachePolicy
+        config.httpAdditionalHeaders = [
+            "Accept": "application/json",
+            "Accept-Encoding": "gzip, deflate, br",
+        ]
+
+        let cache = URLCache(
+            memoryCapacity: 25 * 1024 * 1024,
+            diskCapacity: 100 * 1024 * 1024
+        )
+        config.urlCache = cache
+
+        return URLSession(
+            configuration: config,
+            delegate: delegate,
+            delegateQueue: nil
+        )
+    }
+}
+```