@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/ios-networking/references/background-websocket.md

@@ -1,874 +1,647 @@
-# Background Transfers and WebSocket
+# Background Transfers and WebSockets
 
-Patterns for background URLSession downloads/uploads and
-URLSessionWebSocketTask with structured concurrency.
-
----
+Two things that are often confused. A background URLSession moves HTTP and
+HTTPS uploads and downloads while the app is not running. A WebSocket is a
+live foreground connection. Neither does the other's job.
 
 ## Contents
 
-- [Background URLSession Configuration](#background-urlsession-configuration)
-- [Background Download Tasks](#background-download-tasks)
-- [Handling Background Session Events](#handling-background-session-events)
-- [Background Upload Tasks](#background-upload-tasks)
+- [Setting up a background session](#setting-up-a-background-session)
+- [Downloads that outlive the app](#downloads-that-outlive-the-app)
+- [Relaunch and session event delivery](#relaunch-and-session-event-delivery)
+- [Uploads from a file on disk](#uploads-from-a-file-on-disk)
 - [URLSessionWebSocketTask](#urlsessionwebsockettask)
-- [WebSocket Reconnection Strategy](#websocket-reconnection-strategy)
-- [WebSocket with Codable Messages](#websocket-with-codable-messages)
-- [Background Session Gotchas](#background-session-gotchas)
-- [Combining Background Downloads with SwiftUI Progress](#combining-background-downloads-with-swiftui-progress)
+- [Reconnecting a dropped socket](#reconnecting-a-dropped-socket)
+- [Typed messages over a socket](#typed-messages-over-a-socket)
+- [Pitfalls of background sessions](#pitfalls-of-background-sessions)
+- [Showing download progress in SwiftUI](#showing-download-progress-in-swiftui)
 - [WebSocket Authentication](#websocket-authentication)
-- [WebSocket Subprotocol Negotiation](#websocket-subprotocol-negotiation)
-
-## Background URLSession Configuration
-
-Background sessions allow HTTP/HTTPS upload and download transfers to continue
-when the app is suspended or terminated by the system. The system manages the
-transfer in a separate process and wakes the app on completion.
+- [Choosing a subprotocol](#choosing-a-subprotocol)
 
-### Why Background Sessions
+## Setting up a background session
 
-- Downloads/uploads survive app suspension, system termination, and device restarts.
-- The system handles retries for network failures automatically.
-- Required for any transfer the user expects to complete even if they
-  switch away from the app (e.g., file sync, media downloads).
+A background session hands its transfers to a system process. They carry on
+while the app is suspended, after the system terminates it, and across a
+device restart; the system also retries network failures by itself. When a
+transfer finishes, the app is woken or relaunched to hear about it. Use one
+for anything the user expects to complete after leaving the app: syncing a
+folder, downloading an episode, uploading a video.
 
-If the user force-quits the app from the multitasking screen, iOS cancels the
-background transfers and does not relaunch the app until the user opens it
-again.
+There is one hard limit: a swipe-away in the app switcher. That user
+force-quit cancels every pending background transfer, and the system keeps
+the app closed, with no wake-ups for those transfers, until the person
+launches it by hand.
 
 ### Configuration
 
 ```swift
-@available(iOS 15.0, *)
-final class BackgroundDownloadManager: NSObject, Sendable {
-    static let shared = BackgroundDownloadManager()
+final class BackgroundTransferService: NSObject, @unchecked Sendable {
+    static let shared = BackgroundTransferService()
+    static let identifier = "com.example.reader.transfers"
 
-    /// Use a unique identifier tied to your app's bundle ID.
-    /// The system uses this to reconnect to the session after relaunch.
-    private let sessionID = "com.example.app.background-downloads"
+    @MainActor var systemCompletionHandler: (() -> Void)?
 
-    /// Lazy-initialized background session. Must use a delegate, not async/await,
-    /// because the system delivers events through the delegate after app relaunch.
     lazy var session: URLSession = {
-        let config = URLSessionConfiguration.background(
-            withIdentifier: sessionID
-        )
-        config.isDiscretionary = false          // Start immediately (true = system-scheduled)
-        config.sessionSendsLaunchEvents = true  // Wake app on completion
+        let config = URLSessionConfiguration.background(withIdentifier: Self.identifier)
+        config.isDiscretionary = false
+        config.sessionSendsLaunchEvents = true
         config.allowsExpensiveNetworkAccess = true
-        config.allowsConstrainedNetworkAccess = false  // Respect Low Data Mode
-        config.timeoutIntervalForResource = 24 * 60 * 60  // 24 hours
-
-        return URLSession(
-            configuration: config,
-            delegate: self,
-            delegateQueue: nil  // Use a system-managed serial queue
-        )
+        config.allowsConstrainedNetworkAccess = false
+        config.timeoutIntervalForResource = 24 * 60 * 60
+        let callbackQueue: OperationQueue? = nil
+        return URLSession(configuration: config, delegate: self, delegateQueue: callbackQueue)
     }()
-
-    /// Store completionHandler from AppDelegate for system callback
-    nonisolated(unsafe) var backgroundCompletionHandler: (() -> Void)?
 }
 ```
 
-### Key Configuration Options
+- The identifier is unique per app and prefixed with the bundle ID. After a
+  relaunch, a new session built from that identifier picks up the transfers
+  that were already running.
+- The session needs a delegate. Its events arrive through delegate callbacks,
+  possibly in a process that was just relaunched, so async/await calls on it
+  are not an option.
+- `delegateQueue: nil` gives the session its own serial operation queue.
+- `@unchecked Sendable` is acceptable here because `URLSession` is
+  thread-safe, the lazy session is first touched on the main thread, and the
+  completion handler is main-actor isolated.
+- Background sessions are available since iOS 7; the async APIs used around
+  them need iOS 15.
 
-| Property | Effect |
-|---|---|
-| `isDiscretionary` | `true` = system schedules for optimal battery/network. Use for non-urgent sync. `false` = start immediately. |
-| `sessionSendsLaunchEvents` | Relaunches the app when transfers complete. Required for completion handling. |
-| `allowsConstrainedNetworkAccess` | `false` = honor Low Data Mode. Good for optional downloads. |
-| `allowsExpensiveNetworkAccess` | `false` = Wi-Fi only. Use for large transfers. |
-| `timeoutIntervalForResource` | Maximum time for the entire transfer. Default is 7 days. |
+### Key Configuration Options
 
----
+| Property | Effect | Typical choice |
+|---|---|---|
+| `isDiscretionary` | `true` lets the system wait for power and good network | `true` for optional sync, `false` to start now |
+| `sessionSendsLaunchEvents` | Relaunch the app when transfers finish | `true`; completion handling needs it |
+| `allowsConstrainedNetworkAccess` | `false` respects Low Data Mode | `false` for optional downloads |
+| `allowsExpensiveNetworkAccess` | `false` keeps transfers off cellular and hotspots | `false` for very large files |
+| `timeoutIntervalForResource` | Maximum lifetime of a whole transfer | Default is 7 days |
 
-## Background Download Tasks
+## Downloads that outlive the app
 
-Background downloads must use `downloadTask(with:)`, not `data(for:)`.
-The async/await overloads are not supported for background sessions --
-you must use the delegate pattern.
+Background downloads are `downloadTask(with:)` tasks. The async overloads
+such as `data(for:)` and `download(for:)` are not supported on a background
+session.
 
 ```swift
-extension BackgroundDownloadManager {
-    func startDownload(from url: URL) -> URLSessionDownloadTask {
-        let task = session.downloadTask(with: url)
-        task.earliestBeginDate = Date()  // Start now
-        task.countOfBytesClientExpectsToSend = 0
-        task.countOfBytesClientExpectsToReceive = 50 * 1024 * 1024  // Estimated size
-        task.resume()
-        return task
+extension BackgroundTransferService {
+    func enqueueDownload(of source: URL) {
+        let job = session.downloadTask(with: source)
+        job.earliestBeginDate = .now
+        job.countOfBytesClientExpectsToSend = 0
+        job.countOfBytesClientExpectsToReceive = 80 * 1_048_576
+        job.resume()
     }
 
-    func startDownload(from url: URL, resumeData: Data) -> URLSessionDownloadTask {
-        let task = session.downloadTask(withResumeData: resumeData)
-        task.resume()
-        return task
+    func resumeDownload(with resumeData: Data) {
+        session.downloadTask(withResumeData: resumeData).resume()
     }
 }
 ```
 
+The byte estimates help the scheduler decide when to run the task.
+
 ### Download Delegate
 
 ```swift
-extension BackgroundDownloadManager: URLSessionDownloadDelegate {
-    nonisolated func urlSession(
-        _ session: URLSession,
-        downloadTask: URLSessionDownloadTask,
-        didFinishDownloadingTo location: URL
-    ) {
-        // CRITICAL: Move or open the file before this method returns.
-        // The temporary file is only available until the delegate returns.
-        let destinationDir = FileManager.default.urls(
-            for: .documentDirectory,
-            in: .userDomainMask
-        ).first!
-
-        let filename = downloadTask.originalRequest?.url?.lastPathComponent ?? UUID().uuidString
-        let destination = destinationDir.appendingPathComponent(filename)
-
+extension BackgroundTransferService: URLSessionDownloadDelegate {
+    func urlSession(_: URLSession, downloadTask job: URLSessionDownloadTask,
+                    didFinishDownloadingTo location: URL) {
+        let fileName = job.originalRequest?.url?.lastPathComponent
+        let destination = URL.documentsDirectory.appending(path: fileName ?? UUID().uuidString)
+        let files = FileManager.default
         do {
-            // Remove existing file if present
-            if FileManager.default.fileExists(atPath: destination.path) {
-                try FileManager.default.removeItem(at: destination)
-            }
-            try FileManager.default.moveItem(at: location, to: destination)
-            // Notify the app (post notification, update state, etc.)
+            if files.fileExists(atPath: destination.path()) { try files.removeItem(at: destination) }
+            try files.moveItem(at: location, to: destination)
         } catch {
-            // Handle file move failure
+            Logger.transfers.error("Could not keep download: \(error.localizedDescription)")
         }
     }
 
-    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)
-        // Update progress UI (dispatch to main if needed)
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        task: URLSessionTask,
-        didCompleteWithError error: (any Error)?
-    ) {
-        guard let error else { return }  // Success handled in didFinishDownloadingTo
-
-        // Check for resume data on failure
-        let nsError = error as NSError
-        if let resumeData = nsError.userInfo[NSURLSessionDownloadTaskResumeData] as? Data {
-            // Store resumeData for retry
-            saveResumeData(resumeData, for: task)
-        }
+    func urlSession(_: URLSession, downloadTask job: URLSessionDownloadTask,
+                    didWriteData bytesWritten: Int64, totalBytesWritten: Int64,
+                    totalBytesExpectedToWrite: Int64) {
+        guard totalBytesExpectedToWrite > 0,
+              let url = job.originalRequest?.url else { return }
+        reportProgress(Double(totalBytesWritten) / Double(totalBytesExpectedToWrite), for: url)
     }
 
-    private func saveResumeData(_ data: Data, for task: URLSessionTask) {
-        // Persist resume data to disk for later retry
-        let key = task.originalRequest?.url?.absoluteString ?? ""
-        let path = FileManager.default.temporaryDirectory
-            .appendingPathComponent("resume-\(key.hashValue)")
-        try? data.write(to: path)
+    func urlSession(_: URLSession, task: URLSessionTask, didCompleteWithError failure: (any Error)?) {
+        guard let error = failure else { return }
+        let resumeData = (error as NSError).userInfo[NSURLSessionDownloadTaskResumeData] as? Data
+        if let resumeData, let url = task.originalRequest?.url {
+            let file = URL.temporaryDirectory.appending(path: "resume-\(url.absoluteString.hashValue)")
+            try? resumeData.write(to: file)
+        }
     }
 }
 ```
 
----
+- `location` exists only until `didFinishDownloadingTo` returns, so the move
+  happens inside it.
+- Progress arrives on the session queue; UI updates must hop to the main
+  actor (see the tracker below).
+- `didCompleteWithError` with a `nil` error is the success case, already
+  handled when the file was moved.
+- On failure, the resume data is in the error's `userInfo` under
+  `NSURLSessionDownloadTaskResumeData`. Persist it and pass it to
+  `downloadTask(withResumeData:)` later. `hashValue` is seeded per launch, so
+  a real app should key the file by a stable ID it stores itself.
 
-## Handling Background Session Events
+## Relaunch and session event delivery
 
-When the system completes a background transfer and the app is not
-running, it relaunches the app and calls the `AppDelegate` method. If you use
-the completion-handler overload, call the system's completion handler after
-processing all events.
-
-### UIKit App Delegate
+When a transfer finishes while the app is not running, the system relaunches
+it in the background and calls the app delegate with a completion handler.
+Call that handler once every pending event has been delivered.
 
 ```swift
-class AppDelegate: UIResponder, UIApplicationDelegate {
-    func application(
-        _ application: UIApplication,
-        handleEventsForBackgroundURLSession identifier: String,
-        completionHandler: @escaping () -> Void
-    ) {
-        // Store the completion handler. The BackgroundDownloadManager will
-        // call it after processing all pending events.
-        BackgroundDownloadManager.shared.backgroundCompletionHandler = completionHandler
-
-        // Accessing .session triggers lazy initialization, which reconnects
-        // to the background session and starts delivering delegate events.
-        _ = BackgroundDownloadManager.shared.session
+final class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(_ application: UIApplication,
+                     handleEventsForBackgroundURLSession identifier: String,
+                     completionHandler: @escaping () -> Void) {
+        guard identifier == BackgroundTransferService.identifier else { return completionHandler() }
+        BackgroundTransferService.shared.systemCompletionHandler = completionHandler
+        _ = BackgroundTransferService.shared.session
     }
 }
-```
 
-### Session-Level Delegate
-
-```swift
-extension BackgroundDownloadManager: URLSessionDelegate {
-    nonisolated func urlSessionDidFinishEvents(
-        forBackgroundURLSession session: URLSession
-    ) {
-        // Called after ALL pending delegate events have been delivered.
-        // Call the stored completion handler on the main thread.
+extension BackgroundTransferService {
+    func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
         Task { @MainActor in
-            backgroundCompletionHandler?()
-            backgroundCompletionHandler = nil
+            self.systemCompletionHandler?()
+            self.systemCompletionHandler = nil
         }
     }
 }
-```
-
-### SwiftUI App with AppDelegate Adapter
 
-```swift
 @main
-struct MyApp: App {
-    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
-
+struct ReaderApp: App {
+    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate
     var body: some Scene {
-        WindowGroup {
-            ContentView()
-        }
+        WindowGroup { ShelfView() }
     }
 }
 ```
 
-**Important:** For the handler-based `UIApplicationDelegate` overload, the
-completion handler must be called exactly once and on the main thread. Failing
-to call it causes the system to take a snapshot of the app in the wrong state
-and may waste background runtime.
+- Touching `session` recreates the background session, which is what makes
+  the queued delegate events flow.
+- `urlSessionDidFinishEvents(forBackgroundURLSession:)` fires after the last
+  pending event.
+- Call the stored handler exactly once, on the main thread. It tells the
+  system to take the app-switcher snapshot and suspend the app; skipping it
+  leaves a stale snapshot and wastes background time.
+- SwiftUI apps reach the app delegate through `@UIApplicationDelegateAdaptor`.
 
----
+## Uploads from a file on disk
 
-## Background Upload Tasks
-
-Background uploads require data from a file, not from memory.
+A background upload must come from a file. Uploading `Data` or a stream is
+not supported on a background session.
 
 ```swift
-extension BackgroundDownloadManager {
-    func startUpload(
-        to url: URL,
-        fileURL: URL,
-        method: String = "POST",
-        headers: [String: String] = [:]
-    ) -> URLSessionUploadTask {
-        var request = URLRequest(url: url)
-        request.httpMethod = method
-        for (key, value) in headers {
-            request.setValue(value, forHTTPHeaderField: key)
-        }
-
-        let task = session.uploadTask(with: request, fromFile: fileURL)
-        task.resume()
-        return task
+extension BackgroundTransferService {
+    func enqueueUpload(of stagedFile: URL, to endpoint: URL,
+                       verb: String = "POST", extraHeaders: [String: String] = [:]) {
+        var put = URLRequest(url: endpoint)
+        put.httpMethod = verb
+        put.allHTTPHeaderFields = extraHeaders
+        session.uploadTask(with: put, fromFile: stagedFile).resume()
     }
-}
-```
-
-### Upload Delegate Methods
 
-```swift
-extension BackgroundDownloadManager {
-    nonisolated func urlSession(
-        _ session: URLSession,
-        task: URLSessionTask,
-        didSendBodyData bytesSent: Int64,
-        totalBytesSent: Int64,
-        totalBytesExpectedToSend: Int64
-    ) {
-        guard totalBytesExpectedToSend > 0 else { return }
-        let progress = Double(totalBytesSent) / Double(totalBytesExpectedToSend)
-        // Update progress UI
+    func urlSession(_: URLSession, task: URLSessionTask, didSendBodyData _: Int64,
+                    totalBytesSent: Int64, totalBytesExpectedToSend: Int64) {
+        guard totalBytesExpectedToSend > 0, let url = task.originalRequest?.url else { return }
+        reportProgress(Double(totalBytesSent) / Double(totalBytesExpectedToSend), for: url)
     }
 }
 ```
 
-**Constraints of background uploads:**
-- Data must come from a file (`uploadTask(with:fromFile:)`).
-- `uploadTask(with:from: Data)` is not supported in background sessions.
-- Write multipart form data to a temporary file first, then upload.
-
----
+`uploadTask(with:from:)` with in-memory data fails on a background session.
+For a multipart upload, write the encoded body to a temporary file first and
+upload that file.
 
 ## URLSessionWebSocketTask
 
-`URLSessionWebSocketTask` provides native WebSocket support without
-third-party libraries. Available since iOS 13. WebSockets use `ws:` or `wss:`
-URLs and are foreground/default-session realtime networking; background
-URLSession configuration does not make a WebSocket connection durable after
-suspension.
+`URLSessionWebSocketTask` (iOS 13 and later) is the built-in WebSocket
+client. It connects to `ws:` or `wss:` URLs. It is a foreground, default
+session tool: a background configuration does not keep a socket alive once
+the app is suspended.
 
 ### Basic Connection
 
 ```swift
-@available(iOS 15.0, *)
-final class WebSocketConnection: Sendable {
-    private let task: URLSessionWebSocketTask
-
-    init(url: URL, session: URLSession = .shared) {
-        self.task = session.webSocketTask(with: url)
-    }
+final class SocketLink: Sendable {
+    private let socket: URLSessionWebSocketTask
 
-    func connect() {
-        task.resume()
+    init(address: URL, using session: URLSession) {
+        socket = session.webSocketTask(with: address)
     }
 
-    func disconnect(reason: String? = nil) {
-        task.cancel(with: .normalClosure, reason: reason?.data(using: .utf8))
-    }
+    func open() { socket.resume() }
 
-    func send(_ message: URLSessionWebSocketTask.Message) async throws {
-        try await task.send(message)
+    func close(why: String? = nil) {
+        let note = why.map { Data($0.utf8) }
+        socket.cancel(with: .normalClosure, reason: note)
     }
 
-    func send(text: String) async throws {
-        try await task.send(.string(text))
+    func write(_ line: String) async throws {
+        try await socket.send(.string(line))
     }
-
-    func send(data: Data) async throws {
-        try await task.send(.data(data))
+    func write(_ blob: Data) async throws {
+        try await socket.send(.data(blob))
     }
-
-    func receive() async throws -> URLSessionWebSocketTask.Message {
-        try await task.receive()
+    func read() async throws -> URLSessionWebSocketTask.Message {
+        let incoming = try await socket.receive()
+        return incoming
     }
 }
 ```
 
 ### WebSocket with Structured Concurrency
 
-The key pattern: run a receive loop as an async task that yields
-messages through an `AsyncStream`. This integrates naturally with
-structured concurrency.
+An actor owns the socket and a receive loop that feeds an `AsyncStream`.
 
 ```swift
-@available(iOS 15.0, *)
-actor WebSocketManager {
-    private var task: URLSessionWebSocketTask?
-    private var receiveTask: Task<Void, Never>?
-    private let session: URLSession
-    private let url: URL
-
+actor SocketChannel {
     enum Event: Sendable {
-        case connected
+        case opened
         case text(String)
-        case data(Data)
-        case disconnected(URLSessionWebSocketTask.CloseCode, Data?)
-        case error(Error)
+        case binary(Data)
+        case closed(URLSessionWebSocketTask.CloseCode, Data?)
+        case failed(any Error)
     }
 
-    init(url: URL, session: URLSession = .shared) {
-        self.url = url
+    private let url: URL
+    private let session: URLSession
+    private var socket: URLSessionWebSocketTask?
+    private var receiver: Task<Void, Never>?
+
+    init(address: URL, using session: URLSession = .shared) {
+        url = address
         self.session = session
     }
 
-    /// Returns a stream of WebSocket events. Call `connect()` to start.
     func events() -> AsyncStream<Event> {
-        AsyncStream { continuation in
-            let wsTask = session.webSocketTask(with: url)
-            self.task = wsTask
-
-            wsTask.resume()
-            continuation.yield(.connected)
-
-            // Start the receive loop
-            self.receiveTask = Task { [weak self] in
-                await self?.receiveLoop(continuation: continuation)
-            }
-
-            continuation.onTermination = { _ in
-                Task { [weak self] in
-                    await self?.disconnect()
-                }
-            }
-        }
-    }
-
-    private func receiveLoop(continuation: AsyncStream<Event>.Continuation) async {
-        guard let task else { return }
-
-        while !Task.isCancelled {
-            do {
-                let message = try await task.receive()
-                switch message {
-                case .string(let text):
-                    continuation.yield(.text(text))
-                case .data(let data):
-                    continuation.yield(.data(data))
-                @unknown default:
+        let (stream, continuation) = AsyncStream.makeStream(of: Event.self)
+        let socket = session.webSocketTask(with: url)
+        self.socket = socket
+        socket.resume()
+        continuation.yield(.opened)
+        receiver = Task {
+            while !Task.isCancelled {
+                do {
+                    switch try await socket.receive() {
+                    case .string(let words): continuation.yield(.text(words))
+                    case .data(let blob): continuation.yield(.binary(blob))
+                    @unknown default: break
+                    }
+                } catch {
+                    if socket.closeCode == .invalid {
+                        continuation.yield(.failed(error))
+                    } else {
+                        continuation.yield(.closed(socket.closeCode, socket.closeReason))
+                    }
                     break
                 }
-            } catch {
-                // The receive threw -- connection closed or failed
-                let closeCode = task.closeCode
-                let closeReason = task.closeReason
-                if closeCode == .invalid {
-                    // Unexpected disconnection
-                    continuation.yield(.error(error))
-                } else {
-                    continuation.yield(.disconnected(closeCode, closeReason))
-                }
-                continuation.finish()
-                return
             }
+            continuation.finish()
         }
+        continuation.onTermination = { [weak self] _ in
+            Task { await self?.close() }
+        }
+        return stream
     }
 
-    func send(text: String) async throws {
-        try await task?.send(.string(text))
-    }
-
-    func send(data: Data) async throws {
-        try await task?.send(.data(data))
-    }
-
-    func disconnect() {
-        receiveTask?.cancel()
-        receiveTask = nil
-        task?.cancel(with: .normalClosure, reason: nil)
-        task = nil
+    func send(_ text: String) async throws {
+        try await socket?.send(.string(text))
     }
 
-    /// Send periodic pings to keep the connection alive
-    func startPinging(interval: Duration = .seconds(30)) {
-        Task { [weak self] in
-            while !Task.isCancelled {
-                try? await Task.sleep(for: interval)
-                guard let self else { return }
-                await self.ping()
-            }
-        }
+    func close() {
+        receiver?.cancel()
+        socket?.cancel(with: .normalClosure, reason: nil)
+        receiver = nil
+        socket = nil
     }
 
-    private func ping() {
-        task?.sendPing { error in
-            if let error {
-                // Connection may be dead
-                print("Ping failed: \(error)")
+    func keepAlive(every interval: Duration = .seconds(30)) async {
+        while !Task.isCancelled {
+            do { try await Task.sleep(for: interval) } catch { return }
+            socket?.sendPing { error in
+                if error != nil {
+                    Logger.transfers.notice("Ping failed; the connection is probably gone")
+                }
             }
         }
     }
 }
 ```
 
+- A receive error with `closeCode == .invalid` means the peer never sent a
+  close frame: treat it as an unexpected failure. Any other close code is an
+  orderly close.
+- The receive loop captures only the socket and the continuation, never the
+  actor, and the termination handler holds the actor weakly, so neither keeps
+  the channel alive.
+- `keepAlive` sends a ping on an interval; a failed ping usually means the
+  connection is dead and a reconnect is due.
+
 ### Usage in SwiftUI
 
 ```swift
-@MainActor
-@Observable final class ChatStore {
-    var messages: [ChatMessage] = []
-    var connectionState: ConnectionState = .disconnected
+@MainActor @Observable
+final class RoomModel {
+    enum LinkState { case offline, connecting, online }
 
-    enum ConnectionState { case disconnected, connecting, connected }
+    struct Line: Identifiable { let id = UUID(); let text: String; let isMine: Bool }
 
-    private let wsManager: WebSocketManager
-    private var eventTask: Task<Void, Never>?
+    private(set) var lines: [Line] = []
+    private(set) var state: LinkState = .offline
+    private let channel: SocketChannel
+    private var listener: Task<Void, Never>?
 
-    init(url: URL) {
-        self.wsManager = WebSocketManager(url: url)
-    }
+    init(channel: SocketChannel) { self.channel = channel }
 
     func connect() async {
-        connectionState = .connecting
-        let stream = await wsManager.events()
-
-        eventTask = Task {
-            for await event in stream {
-                await handleEvent(event)
-            }
+        state = .connecting
+        let stream = await channel.events()
+        listener = Task {
+            for await event in stream { handle(event) }
         }
     }
 
-    func sendMessage(_ text: String) async {
+    func post(_ text: String) async {
         do {
-            try await wsManager.send(text: text)
-            messages.append(ChatMessage(text: text, isOutgoing: true))
+            try await channel.send(text)
+            lines.append(Line(text: text, isMine: true))
         } catch {
-            // Handle send failure
+            state = .offline
         }
     }
 
     func disconnect() async {
-        eventTask?.cancel()
-        eventTask = nil
-        await wsManager.disconnect()
-        connectionState = .disconnected
+        listener?.cancel()
+        await channel.close()
+        state = .offline
     }
 
-    private func handleEvent(_ event: WebSocketManager.Event) async {
+    private func handle(_ event: SocketChannel.Event) {
         switch event {
-        case .connected:
-            connectionState = .connected
-        case .text(let text):
-            messages.append(ChatMessage(text: text, isOutgoing: false))
-        case .data(let data):
-            if let text = String(data: data, encoding: .utf8) {
-                messages.append(ChatMessage(text: text, isOutgoing: false))
-            }
-        case .disconnected:
-            connectionState = .disconnected
-        case .error:
-            connectionState = .disconnected
-            // Optionally trigger reconnection
+        case .opened: state = .online
+        case .text(let text): lines.append(Line(text: text, isMine: false))
+        case .binary(let blob):
+            lines.append(Line(text: String(decoding: blob, as: UTF8.self), isMine: false))
+        case .closed, .failed: state = .offline
         }
     }
 }
-```
-
-```swift
-struct ChatView: View {
-    @State var store: ChatStore
 
+struct RoomView: View {
+    let model: RoomModel
     var body: some View {
-        List(store.messages) { message in
-            ChatBubble(message: message)
-        }
-        .task { await store.connect() }
-        .onDisappear { Task { await store.disconnect() } }
+        List(model.lines) { Text($0.text) }
+            .task { await model.connect() }
+            .onDisappear { Task { await model.disconnect() } }
     }
 }
 ```
 
----
+A sent message is appended only after `send` succeeds. On `.closed` or
+`.failed` the model goes offline; reconnecting is the next section.
 
-## WebSocket Reconnection Strategy
+## Reconnecting a dropped socket
 
-Network drops happen. A robust WebSocket client must reconnect
-automatically with exponential backoff.
+Sockets drop. A durable client reconnects on its own with exponential
+backoff.
 
 ```swift
-@available(iOS 15.0, *)
-actor ReconnectingWebSocket {
+actor ResilientChannel {
     private let url: URL
-    private let session: URLSession
-    private let maxReconnectAttempts: Int
-    private let initialDelay: Duration
-    private let maxDelay: Duration
-
-    private var currentManager: WebSocketManager?
-    private var reconnectAttempts = 0
-    private var isIntentionalDisconnect = false
-
-    init(
-        url: URL,
-        session: URLSession = .shared,
-        maxReconnectAttempts: Int = 10,
-        initialDelay: Duration = .seconds(1),
-        maxDelay: Duration = .seconds(60)
-    ) {
-        self.url = url
-        self.session = session
-        self.maxReconnectAttempts = maxReconnectAttempts
-        self.initialDelay = initialDelay
-        self.maxDelay = maxDelay
-    }
+    private let maxAttempts = 10
+    private let firstDelay: Duration = .seconds(1)
+    private let ceiling: Duration = .seconds(60)
+    private var attempts = 0
+    private var stoppedOnPurpose = false
+    private var current: SocketChannel?
 
-    /// Returns a stream that automatically reconnects on disconnection.
-    func events() -> AsyncStream<WebSocketManager.Event> {
-        AsyncStream { continuation in
-            Task {
-                await connectWithReconnection(continuation: continuation)
-            }
-            continuation.onTermination = { _ in
-                Task { [weak self] in
-                    await self?.intentionalDisconnect()
-                }
-            }
-        }
-    }
+    init(url: URL) { self.url = url }
 
-    private func connectWithReconnection(
-        continuation: AsyncStream<WebSocketManager.Event>.Continuation
-    ) async {
-        while !isIntentionalDisconnect && reconnectAttempts < maxReconnectAttempts {
-            guard !Task.isCancelled else { break }
-
-            let manager = WebSocketManager(url: url, session: session)
-            currentManager = manager
-            let stream = await manager.events()
-
-            for await event in stream {
-                switch event {
-                case .connected:
-                    reconnectAttempts = 0  // Reset on successful connection
-                    continuation.yield(event)
-                case .error, .disconnected:
-                    continuation.yield(event)
-                default:
-                    continuation.yield(event)
+    func events() -> AsyncStream<SocketChannel.Event> {
+        AsyncStream { continuation in
+            let loop = Task {
+                while shouldContinue() {
+                    let channel = fresh()
+                    for await event in await channel.events() {
+                        if case .opened = event { resetAttempts() }
+                        continuation.yield(event)
+                    }
+                    if Task.isCancelled || isStopped() { break }
+                    let wait = nextDelay()
+                    if (try? await Task.sleep(for: wait)) == nil { break }
                 }
+                continuation.finish()
             }
-
-            // Stream ended -- attempt reconnection unless intentional
-            guard !isIntentionalDisconnect, !Task.isCancelled else { break }
-
-            reconnectAttempts += 1
-            let delay = calculateBackoff()
-            do {
-                try await Task.sleep(for: delay)
-            } catch {
-                break  // Cancelled during sleep
+            continuation.onTermination = { _ in
+                loop.cancel()
+                Task { await self.stop() }
             }
         }
-
-        continuation.finish()
     }
 
-    private func calculateBackoff() -> Duration {
-        let base = Double(initialDelay.components.seconds) * pow(2.0, Double(reconnectAttempts - 1))
-        let capped = min(base, Double(maxDelay.components.seconds))
-        let jitter = Double.random(in: 0...(capped * 0.25))
-        return .seconds(capped + jitter)
+    func stop() async {
+        stoppedOnPurpose = true
+        await current?.close()
     }
 
-    func send(text: String) async throws {
-        try await currentManager?.send(text: text)
-    }
+    private func shouldContinue() -> Bool { !stoppedOnPurpose && attempts < maxAttempts }
+    private func isStopped() -> Bool { stoppedOnPurpose }
+    private func resetAttempts() { attempts = 0 }
 
-    func send(data: Data) async throws {
-        try await currentManager?.send(data: data)
+    private func fresh() -> SocketChannel {
+        let channel = SocketChannel(address: url)
+        current = channel
+        return channel
     }
 
-    private func intentionalDisconnect() {
-        isIntentionalDisconnect = true
-        Task {
-            await currentManager?.disconnect()
-        }
+    private func nextDelay() -> Duration {
+        attempts += 1
+        let grown = firstDelay * Int(pow(2.0, Double(attempts - 1)))
+        let capped = min(grown, ceiling)
+        return capped + capped * Double.random(in: 0...0.25)
     }
 }
 ```
 
----
+- Each attempt uses a new channel, and every event is passed through.
+- The `Task` made inside `events()` inherits the actor's isolation, so the
+  actor's own helpers are called without `await`; only the other actor
+  (`channel.events()`) needs one.
+- A successful open resets the attempt counter.
+- After a stream ends: stop if the disconnect was intentional or the task
+  was cancelled; otherwise count the attempt and sleep. A cancelled sleep ends
+  the loop.
+- Delay is `firstDelay * 2^(attempt - 1)`, capped at 60 seconds, plus up to
+  25% jitter; at most 10 attempts.
+- Ending the outer stream marks the stop as intentional and closes the live
+  channel.
 
-## WebSocket with Codable Messages
+## Typed messages over a socket
 
-For typed message protocols (common in chat, gaming, real-time apps),
-decode/encode messages automatically.
+Wrap typed messages in an envelope that names the type, so one socket can
+carry many message kinds.
 
 ```swift
-protocol WebSocketMessage: Codable, Sendable {
-    static var messageType: String { get }
+protocol SocketMessage: Codable, Sendable {
+    static var kind: String { get }
 }
 
-struct TypedWebSocketTransport {
-    private let manager: WebSocketManager
-    private let encoder = JSONEncoder()
-    private let decoder = JSONDecoder()
+struct Envelope: Codable, Sendable {
+    let kind: String
+    let payload: Data
+}
 
-    init(manager: WebSocketManager) {
-        self.manager = manager
+struct TypedChannel: Sendable {
+    enum Incoming: Sendable {
+        case opened
+        case message(kind: String, payload: Data)
+        case closed(URLSessionWebSocketTask.CloseCode)
+        case failed(any Error)
     }
 
-    func send<T: WebSocketMessage>(_ message: T) async throws {
-        let envelope = MessageEnvelope(
-            type: T.messageType,
-            payload: try encoder.encode(message)
-        )
-        let data = try encoder.encode(envelope)
-        try await manager.send(data: data)
+    let channel: SocketChannel
+
+    func send<M: SocketMessage>(_ message: M) async throws {
+        let envelope = Envelope(kind: M.kind, payload: try JSONEncoder().encode(message))
+        let frame = try JSONEncoder().encode(envelope)
+        try await channel.send(String(decoding: frame, as: UTF8.self))
     }
 
-    /// Typed event stream that decodes known message types
-    func typedEvents() async -> AsyncStream<DecodedEvent> {
-        let rawEvents = await manager.events()
+    func incoming() async -> AsyncStream<Incoming> {
+        let raw = await channel.events()
         return AsyncStream { continuation in
-            Task {
-                for await event in rawEvents {
+            let pump = Task {
+                for await event in raw {
                     switch event {
-                    case .data(let data):
-                        if let envelope = try? decoder.decode(MessageEnvelope.self, from: data) {
-                            continuation.yield(.message(type: envelope.type, payload: envelope.payload))
-                        }
-                    case .text(let text):
-                        if let data = text.data(using: .utf8),
-                           let envelope = try? decoder.decode(MessageEnvelope.self, from: data) {
-                            continuation.yield(.message(type: envelope.type, payload: envelope.payload))
-                        }
-                    case .connected:
-                        continuation.yield(.connected)
-                    case .disconnected(let code, _):
-                        continuation.yield(.disconnected(code))
-                    case .error(let error):
-                        continuation.yield(.error(error))
+                    case .opened: continuation.yield(.opened)
+                    case .text(let text): yieldEnvelope(Data(text.utf8), to: continuation)
+                    case .binary(let data): yieldEnvelope(data, to: continuation)
+                    case .closed(let code, _): continuation.yield(.closed(code))
+                    case .failed(let problem): continuation.yield(.failed(problem))
                     }
                 }
                 continuation.finish()
             }
+            continuation.onTermination = { _ in pump.cancel() }
         }
     }
 
-    enum DecodedEvent: Sendable {
-        case connected
-        case message(type: String, payload: Data)
-        case disconnected(URLSessionWebSocketTask.CloseCode)
-        case error(Error)
-    }
-
-    private struct MessageEnvelope: Codable, Sendable {
-        let type: String
-        let payload: Data
+    private func yieldEnvelope(_ data: Data, to continuation: AsyncStream<Incoming>.Continuation) {
+        guard let envelope = try? JSONDecoder().decode(Envelope.self, from: data) else { return }
+        continuation.yield(.message(kind: envelope.kind, payload: envelope.payload))
     }
 }
 ```
 
----
-
-## Background Session Gotchas
-
-### The session identifier must be unique per app
-If two sessions share the same identifier, events may be delivered to
-the wrong delegate. Use your bundle identifier as a prefix.
-
-### Background sessions do not support async/await overloads
-The `data(for:)` and `download(for:)` async methods are not available
-on background sessions. Use `downloadTask(with:)` and the delegate.
-
-### Only download and upload tasks are supported
-Data tasks (`dataTask`) are not supported in background sessions. Convert
-data requests to download tasks if needed for background execution.
-WebSocket tasks are not background transfer tasks; reconnect them when the app
-is active again.
-
-### The app may be terminated and relaunched
-Store any state you need (task identifiers, file destinations) to disk.
-Do not rely on in-memory state surviving a background relaunch.
-User force-quit is different from system termination: iOS cancels outstanding
-background transfers and will not relaunch the app automatically.
-
-### File must be moved or opened in didFinishDownloadingTo
-The temporary file at `location` is available until the delegate method
-returns. Move it to preserve it, or open it for reading before returning.
-
-### Call the system completion handler exactly once
-Store the completion handler from
-`application(_:handleEventsForBackgroundURLSession:completionHandler:)`
-and invoke it in `urlSessionDidFinishEvents(forBackgroundURLSession:)`
-on the main thread.
-
-### Test on a real device
-Background session behavior differs significantly between the Simulator
-and real devices. Always test background transfers on hardware.
-
----
-
-## Combining Background Downloads with SwiftUI Progress
-
-Bridge the delegate-based background download to an `@Observable` model
-for live UI updates.
+Frames that are not valid envelopes are dropped. The receiver switches on
+`kind` and decodes `payload` into the matching `SocketMessage` type. The
+channel above sends text frames; add a `send(data:)` to it if the server
+expects binary envelopes.
+
+## Pitfalls of background sessions
+
+- Session identifiers must be unique within the app. Two sessions sharing one
+  can deliver events to the wrong delegate. Prefix with the bundle ID.
+- `data(for:)` and `download(for:)` are not available on a background
+  session.
+- Only download and upload tasks run there. Data tasks do not; turn a data
+  request into a download if it must survive.
+- WebSocket tasks are not background transfers. Reconnect when the app
+  becomes active again.
+- Write task identifiers and planned destinations to disk. Memory does not
+  survive a background relaunch.
+- A user force-quit is not a system termination: transfers are cancelled and
+  the app is not relaunched for them.
+- Move or open the `location` file inside `didFinishDownloadingTo`.
+- The app delegate's background-session callback hands over a completion
+  closure. Hold on to it, then invoke it a single time on the main thread
+  when `urlSessionDidFinishEvents(forBackgroundURLSession:)` arrives.
+- Background scheduling in Simulator does not match a device. Test on
+  hardware.
+
+## Showing download progress in SwiftUI
+
+Delegate callbacks run on the session queue. Bridge them into an observable
+model on the main actor:
 
 ```swift
-@MainActor
-@Observable final class DownloadTracker {
-    var downloads: [URL: DownloadProgress] = [:]
-
-    struct DownloadProgress: Sendable {
-        var fractionCompleted: Double = 0
-        var state: State = .downloading
-
-        enum State: Sendable { case downloading, completed, failed }
-    }
-
-    func updateProgress(for url: URL, fraction: Double) {
-        downloads[url, default: DownloadProgress()].fractionCompleted = fraction
+@MainActor @Observable
+final class TransferBoard {
+    struct Entry {
+        enum Phase { case running, done, failed }
+        var fraction: Double = 0
+        var phase: Phase = .running
     }
 
-    func markCompleted(for url: URL) {
-        downloads[url]?.state = .completed
-        downloads[url]?.fractionCompleted = 1.0
-    }
+    static let shared = TransferBoard()
+    private(set) var entries: [URL: Entry] = [:]
 
-    func markFailed(for url: URL) {
-        downloads[url]?.state = .failed
-    }
+    func update(_ url: URL, fraction: Double) { entries[url, default: Entry()].fraction = fraction }
+    func finish(_ url: URL) { entries[url] = Entry(fraction: 1, phase: .done) }
+    func fail(_ url: URL) { entries[url, default: Entry()].phase = .failed }
 }
-```
-
-Wire the delegate to the tracker:
 
-```swift
-extension BackgroundDownloadManager {
-    // Called from delegate methods; dispatches to MainActor
-    func reportProgress(for url: URL, fraction: Double) {
-        Task { @MainActor in
-            downloadTracker.updateProgress(for: url, fraction: fraction)
-        }
+extension BackgroundTransferService {
+    func reportProgress(_ fraction: Double, for url: URL) {
+        Task { @MainActor in TransferBoard.shared.update(url, fraction: fraction) }
     }
 }
 ```
 
----
-
 ## WebSocket Authentication
 
-WebSocket connections often require authentication via a token in the
-initial handshake (either as a query parameter or a custom header).
+Authenticate during the opening handshake, with either a query parameter or
+a header:
 
 ```swift
-func authenticatedWebSocket(
-    baseURL: URL,
-    token: String
-) -> URLSessionWebSocketTask {
-    // Option 1: Token as query parameter
-    guard var components = URLComponents(url: baseURL, resolvingAgainstBaseURL: true) else {
-        preconditionFailure("Invalid URL components for: \(baseURL)")
-    }
-    components.queryItems = [URLQueryItem(name: "token", value: token)]
-    guard let authenticatedURL = components.url else {
-        preconditionFailure("Failed to construct URL from components")
-    }
-    let task = URLSession.shared.webSocketTask(with: authenticatedURL)
-
-    // Option 2: Token as custom header (use URLRequest)
-    var request = URLRequest(url: baseURL)
-    request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
-    let taskWithHeader = URLSession.shared.webSocketTask(with: request)
-
-    return taskWithHeader
+func socketUsingQuery(_ base: URL, token: String, session: URLSession) -> URLSessionWebSocketTask? {
+    guard var parts = URLComponents(url: base, resolvingAgainstBaseURL: false) else { return nil }
+    parts.queryItems = [URLQueryItem(name: "access_token", value: token)]
+    guard let url = parts.url else { return nil }
+    return session.webSocketTask(with: url)
 }
-```
 
-**Prefer the header approach** when the server supports it. Query
-parameters may appear in server access logs, which is a security
-concern for tokens.
+func socketUsingHeader(_ url: URL, token: String, session: URLSession) -> URLSessionWebSocketTask {
+    var handshake = URLRequest(url: url)
+    handshake.allHTTPHeaderFields = ["Authorization": "Bearer " + token]
+    return session.webSocketTask(with: handshake)
+}
+```
 
----
+Prefer the header. Query strings tend to end up in server and proxy access
+logs.
 
-## WebSocket Subprotocol Negotiation
+## Choosing a subprotocol
 
 ```swift
-// Request a specific subprotocol (e.g., graphql-ws)
-let task = URLSession.shared.webSocketTask(
-    with: url,
-    protocols: ["graphql-transport-ws"]
-)
-task.resume()
-
-// After connection, verify the negotiated protocol
-// via the URLSessionWebSocketDelegate
-```
+let socket = session.webSocketTask(with: endpoint, protocols: ["graphql-transport-ws"])
 
-```swift
-extension WebSocketConnection: URLSessionWebSocketDelegate {
-    nonisolated func urlSession(
-        _ session: URLSession,
-        webSocketTask: URLSessionWebSocketTask,
-        didOpenWithProtocol protocol: String?
-    ) {
-        print("Connected with protocol: \(`protocol` ?? "none")")
-    }
-
-    nonisolated func urlSession(
-        _ session: URLSession,
-        webSocketTask: URLSessionWebSocketTask,
-        didCloseWith closeCode: URLSessionWebSocketTask.CloseCode,
-        reason: Data?
-    ) {
-        let reasonString = reason.flatMap { String(data: $0, encoding: .utf8) }
-        print("Closed: \(closeCode) - \(reasonString ?? "no reason")")
+final class SocketObserver: NSObject, URLSessionWebSocketDelegate {
+    func urlSession(_: URLSession, webSocketTask socket: URLSessionWebSocketTask,
+                    didOpenWithProtocol chosen: String?) {
+        if chosen != "graphql-transport-ws" { socket.cancel(with: .protocolError, reason: nil) }
+    }
+
+    func urlSession(_: URLSession, webSocketTask _: URLSessionWebSocketTask,
+                    didCloseWith code: URLSessionWebSocketTask.CloseCode, reason _: Data?) {
+        Logger.transfers.info("Socket closed with code \(code.rawValue)")
     }
 }
 ```
+
+Check the protocol the server actually chose in `didOpenWithProtocol`. Close
+events report a `CloseCode` and optional reason data.
+
+The snippets on this page log through a shared logger:
+
+```swift
+import OSLog
+extension Logger { static let transfers = Logger(subsystem: "app.networking", category: "transfers") }
+```