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

package/src/.agents/skills/ui-ux-pro-custom/data/swift-ios-skills/background-processing/references/background-task-patterns.md

@@ -1,390 +1,390 @@
-# Background Task Patterns — Extended Reference
-
-Overflow reference for the background-processing skill. Contains debugging tips,
-advanced background URLSession patterns, background push best practices, and
-SwiftUI integration patterns.
-
-## Debugging Background Tasks
-
-### Simulating Task Launches in Xcode
-
-Use the LLDB console to trigger tasks instantly during development. The app must
-be running in the debugger with a breakpoint hit or paused.
-
-```swift
-e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.refresh"]
-```
-
-For processing tasks:
-
-```swift
-e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.db-cleanup"]
-```
-
-To simulate early termination (expiration):
-
-```swift
-e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.example.app.refresh"]
-```
-
-### Verifying Pending Tasks
-
-Check what tasks are currently scheduled:
-
-```swift
-BGTaskScheduler.shared.getPendingTaskRequests { requests in
-    for request in requests {
-        print("Pending: \(request.identifier), earliest: \(String(describing: request.earliestBeginDate))")
-    }
-}
-```
-
-### Common Debugging Issues
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Task never fires | Identifier not in Info.plist | Add to `BGTaskSchedulerPermittedIdentifiers` |
-| Task never fires | Background modes not enabled | Enable `fetch` and/or `processing` in capabilities |
-| Task never fires on device | Device in Low Power Mode | Low Power Mode suppresses background tasks |
-| `.notPermitted` error | Identifier mismatch | Verify exact string match between code and plist |
-| `.unavailable` error | Running in extension | BGTaskScheduler not available in app extensions |
-| `.tooManyPendingTaskRequests` | Over 10 pending refresh or 1 processing per identifier | Cancel old requests before submitting new ones |
-
-## Advanced BGProcessingTask Patterns
-
-### Conditional Requirements
-
-Use `requiresExternalPower` and `requiresNetworkConnectivity` to ensure the
-system only launches your task when conditions are met:
-
-```swift
-func scheduleSyncTask() {
-    let request = BGProcessingTaskRequest(
-        identifier: "com.example.app.full-sync"
-    )
-    // Only run when charging and connected to network
-    request.requiresExternalPower = true
-    request.requiresNetworkConnectivity = true
-    // Don't run before 2 AM
-    var components = DateComponents()
-    components.hour = 2
-    if let twoAM = Calendar.current.nextDate(
-        after: Date(),
-        matching: components,
-        matchingPolicy: .nextTime
-    ) {
-        request.earliestBeginDate = twoAM
-    }
-
-    do {
-        try BGTaskScheduler.shared.submit(request)
-    } catch {
-        print("Failed to schedule sync: \(error)")
-    }
-}
-```
-
-### Incremental Work with Checkpointing
-
-Design tasks to save progress so they can resume if terminated:
-
-```swift
-func handleMigration(task: BGProcessingTask) {
-    let work = Task {
-        let lastProcessed = UserDefaults.standard.integer(
-            forKey: "migrationLastIndex"
-        )
-        let items = try await loadItems()
-
-        for (index, item) in items.dropFirst(lastProcessed).enumerated() {
-            try Task.checkCancellation()
-            try await migrate(item)
-            // Checkpoint progress
-            UserDefaults.standard.set(
-                lastProcessed + index + 1,
-                forKey: "migrationLastIndex"
-            )
-        }
-
-        task.setTaskCompleted(success: true)
-    }
-
-    task.expirationHandler = {
-        work.cancel()
-        // Progress is saved -- next launch picks up where we left off
-        task.setTaskCompleted(success: false)
-    }
-}
-```
-
-## Background URLSession — Extended Patterns
-
-### Configuration Best Practices
-
-```swift
-let config = URLSessionConfiguration.background(
-    withIdentifier: "com.example.app.background-transfer"
-)
-
-// isDiscretionary = true: system picks optimal time (WiFi, power)
-// Use for non-urgent transfers
-config.isDiscretionary = true
-
-// sessionSendsLaunchEvents = true: app relaunched when transfer completes
-config.sessionSendsLaunchEvents = true
-
-// Set reasonable timeouts
-config.timeoutIntervalForResource = 60 * 60 * 24 * 7  // 7 days
-
-// Allow cellular (default is true)
-config.allowsCellularAccess = true
-```
-
-### Upload with Background Session
-
-```swift
-func uploadFile(at fileURL: URL) {
-    var request = URLRequest(url: URL(string: "https://api.example.com/upload")!)
-    request.httpMethod = "POST"
-    let uploadTask = session.uploadTask(with: request, fromFile: fileURL)
-    uploadTask.resume()
-}
-```
-
-**Important:** Background sessions only support `uploadTask(with:fromFile:)` and
-`downloadTask(with:)`. Data tasks, `uploadTask(with:from:)` (Data), and
-closure/async-based tasks are **not** supported.
-
-### Handling App Relaunch
-
-When the system completes a background transfer and your app is not running, it
-relaunches the app. You must:
-
-1. Store the completion handler from
-   `application(_:handleEventsForBackgroundURLSession:completionHandler:)`
-2. Recreate the `URLSession` with the **same identifier**
-3. Call the stored completion handler in `urlSessionDidFinishEvents`
-
-```swift
-// AppDelegate
-func application(
-    _ application: UIApplication,
-    handleEventsForBackgroundURLSession identifier: String,
-    completionHandler: @escaping () -> Void
-) {
-    // Recreating session with the same identifier reconnects to the transfer
-    _ = DownloadManager.shared.session  // trigger lazy init
-    DownloadManager.shared.completionHandler = completionHandler
-}
-
-// In your URLSessionDelegate
-func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
-    Task { @MainActor in
-        self.completionHandler?()
-        self.completionHandler = nil
-    }
-}
-```
-
-### Handling Download Errors and Retries
-
-```swift
-func urlSession(
-    _ session: URLSession,
-    task: URLSessionTask,
-    didCompleteWithError error: (any Error)?
-) {
-    guard let error else { return }  // Success handled in didFinishDownloadingTo
-
-    let nsError = error as NSError
-
-    // Check if download can be resumed
-    if let resumeData = nsError.userInfo[NSURLSessionDownloadTaskResumeData] as? Data {
-        // Store resumeData and retry later
-        let downloadTask = session.downloadTask(withResumeData: resumeData)
-        downloadTask.resume()
-        return
-    }
-
-    // Non-resumable error -- retry from scratch or notify user
-    if nsError.code == NSURLErrorNetworkConnectionLost {
-        // Re-enqueue the download
-        if let url = task.originalRequest?.url {
-            let newTask = session.downloadTask(with: url)
-            newTask.resume()
-        }
-    }
-}
-```
-
-### Progress Tracking
-
-```swift
-func urlSession(
-    _ session: URLSession,
-    downloadTask: URLSessionDownloadTask,
-    didWriteData bytesWritten: Int64,
-    totalBytesWritten: Int64,
-    totalBytesExpectedToWrite: Int64
-) {
-    let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
-    // Update UI on main actor if app is in foreground
-    Task { @MainActor in
-        DownloadProgressStore.shared.update(
-            taskID: downloadTask.taskIdentifier,
-            progress: progress
-        )
-    }
-}
-```
-
-## Background Push — Extended Patterns
-
-### Push Payload Requirements
-
-The `content-available: 1` flag is required. You can include custom data:
-
-```json
-{
-    "aps": {
-        "content-available": 1
-    },
-    "type": "new-message",
-    "conversation-id": "abc-123"
-}
-```
-
-**Do not** include `alert`, `badge`, or `sound` if you only want a silent push.
-Including visual notification keys changes the push behavior.
-
-### Rate Limiting
-
-Apple throttles background push delivery. Guidelines:
-
-- System limits to a few pushes per hour per app
-- If the user force-quits the app, background pushes stop entirely until next
-  manual launch
-- High-priority pushes (`apns-priority: 10`) are delivered immediately but must
-  only be used when the notification triggers user-visible content
-- Low-priority pushes (`apns-priority: 5`) are batched and delivered
-  opportunistically
-
-### Handling Push with Async Work
-
-```swift
-func application(
-    _ application: UIApplication,
-    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
-    fetchCompletionHandler completionHandler:
-        @escaping (UIBackgroundFetchResult) -> Void
-) {
-    guard let type = userInfo["type"] as? String else {
-        completionHandler(.noData)
-        return
-    }
-
-    Task {
-        do {
-            switch type {
-            case "new-message":
-                let conversationID = userInfo["conversation-id"] as? String
-                let fetched = try await MessageService.shared
-                    .fetchMessages(for: conversationID)
-                completionHandler(fetched ? .newData : .noData)
-
-            case "config-update":
-                try await ConfigService.shared.refreshConfig()
-                completionHandler(.newData)
-
-            default:
-                completionHandler(.noData)
-            }
-        } catch {
-            completionHandler(.failed)
-        }
-    }
-}
-```
-
-**Important:** You have approximately 30 seconds to call `completionHandler`.
-Failure to do so causes the system to penalize your app's background push
-budget.
-
-## SwiftUI BackgroundTask Modifier
-
-SwiftUI provides a `.backgroundTask` modifier as an alternative to manual
-`BGTaskScheduler` registration:
-
-```swift
-@main
-struct MyApp: App {
-    var body: some Scene {
-        WindowGroup { ContentView() }
-            .backgroundTask(.appRefresh("com.example.app.refresh")) {
-                await refreshFeed()
-                // Schedule the next one
-                scheduleAppRefresh()
-            }
-    }
-}
-```
-
-This is a convenience wrapper. Under the hood it registers with
-`BGTaskScheduler`. You still need the Info.plist identifiers and background
-modes.
-
-## BGContinuedProcessingTask — Extended Patterns
-
-### Checking Supported Resources
-
-Before requesting GPU or other resources, verify the device supports them:
-
-```swift
-let supported = BGTaskScheduler.shared.supportedResources
-if supported.contains(.gpu) {
-    request.requiredResources = .gpu
-}
-```
-
-### Submission Strategies
-
-`BGContinuedProcessingTaskRequest.SubmissionStrategy` controls behavior when the
-system cannot run the task immediately:
-
-| Strategy | Behavior |
-|---|---|
-| `.queue` | Task is queued and starts as soon as possible |
-| `.fail` | Submission fails immediately if can't run now |
-
-Use `.fail` when the work is only relevant in the current moment (e.g., a user
-is waiting). Use `.queue` for work that can start whenever the system allows.
-
-### Cancellation by the User
-
-The system shows a Live Activity for continued processing tasks. The user can
-cancel the task from there. Handle this in your expiration handler:
-
-```swift
-task.expirationHandler = {
-    // Clean up partial work
-    cleanupPartialExport()
-    task.setTaskCompleted(success: false)
-}
-```
-
-### Progress Reporting
-
-The system uses your `Progress` object to decide termination priority. Tasks
-with no progress updates are terminated first under resource pressure:
-
-```swift
-// Report fine-grained progress
-let progress = task.progress
-progress.totalUnitCount = Int64(totalItems)
-
-for (index, item) in items.enumerated() {
-    try Task.checkCancellation()
-    await process(item)
-    progress.completedUnitCount = Int64(index + 1)
-}
-```
+# Background Task Patterns — Extended Reference
+
+Overflow reference for the background-processing skill. Contains debugging tips,
+advanced background URLSession patterns, background push best practices, and
+SwiftUI integration patterns.
+
+## Debugging Background Tasks
+
+### Simulating Task Launches in Xcode
+
+Use the LLDB console to trigger tasks instantly during development. The app must
+be running in the debugger with a breakpoint hit or paused.
+
+```swift
+e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.refresh"]
+```
+
+For processing tasks:
+
+```swift
+e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateLaunchForTaskWithIdentifier:@"com.example.app.db-cleanup"]
+```
+
+To simulate early termination (expiration):
+
+```swift
+e -l objc -- (void)[[BGTaskScheduler sharedScheduler] _simulateExpirationForTaskWithIdentifier:@"com.example.app.refresh"]
+```
+
+### Verifying Pending Tasks
+
+Check what tasks are currently scheduled:
+
+```swift
+BGTaskScheduler.shared.getPendingTaskRequests { requests in
+    for request in requests {
+        print("Pending: \(request.identifier), earliest: \(String(describing: request.earliestBeginDate))")
+    }
+}
+```
+
+### Common Debugging Issues
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Task never fires | Identifier not in Info.plist | Add to `BGTaskSchedulerPermittedIdentifiers` |
+| Task never fires | Background modes not enabled | Enable `fetch` and/or `processing` in capabilities |
+| Task never fires on device | Device in Low Power Mode | Low Power Mode suppresses background tasks |
+| `.notPermitted` error | Identifier mismatch | Verify exact string match between code and plist |
+| `.unavailable` error | Running in extension | BGTaskScheduler not available in app extensions |
+| `.tooManyPendingTaskRequests` | Over 10 pending refresh or 1 processing per identifier | Cancel old requests before submitting new ones |
+
+## Advanced BGProcessingTask Patterns
+
+### Conditional Requirements
+
+Use `requiresExternalPower` and `requiresNetworkConnectivity` to ensure the
+system only launches your task when conditions are met:
+
+```swift
+func scheduleSyncTask() {
+    let request = BGProcessingTaskRequest(
+        identifier: "com.example.app.full-sync"
+    )
+    // Only run when charging and connected to network
+    request.requiresExternalPower = true
+    request.requiresNetworkConnectivity = true
+    // Don't run before 2 AM
+    var components = DateComponents()
+    components.hour = 2
+    if let twoAM = Calendar.current.nextDate(
+        after: Date(),
+        matching: components,
+        matchingPolicy: .nextTime
+    ) {
+        request.earliestBeginDate = twoAM
+    }
+
+    do {
+        try BGTaskScheduler.shared.submit(request)
+    } catch {
+        print("Failed to schedule sync: \(error)")
+    }
+}
+```
+
+### Incremental Work with Checkpointing
+
+Design tasks to save progress so they can resume if terminated:
+
+```swift
+func handleMigration(task: BGProcessingTask) {
+    let work = Task {
+        let lastProcessed = UserDefaults.standard.integer(
+            forKey: "migrationLastIndex"
+        )
+        let items = try await loadItems()
+
+        for (index, item) in items.dropFirst(lastProcessed).enumerated() {
+            try Task.checkCancellation()
+            try await migrate(item)
+            // Checkpoint progress
+            UserDefaults.standard.set(
+                lastProcessed + index + 1,
+                forKey: "migrationLastIndex"
+            )
+        }
+
+        task.setTaskCompleted(success: true)
+    }
+
+    task.expirationHandler = {
+        work.cancel()
+        // Progress is saved -- next launch picks up where we left off
+        task.setTaskCompleted(success: false)
+    }
+}
+```
+
+## Background URLSession — Extended Patterns
+
+### Configuration Best Practices
+
+```swift
+let config = URLSessionConfiguration.background(
+    withIdentifier: "com.example.app.background-transfer"
+)
+
+// isDiscretionary = true: system picks optimal time (WiFi, power)
+// Use for non-urgent transfers
+config.isDiscretionary = true
+
+// sessionSendsLaunchEvents = true: app relaunched when transfer completes
+config.sessionSendsLaunchEvents = true
+
+// Set reasonable timeouts
+config.timeoutIntervalForResource = 60 * 60 * 24 * 7  // 7 days
+
+// Allow cellular (default is true)
+config.allowsCellularAccess = true
+```
+
+### Upload with Background Session
+
+```swift
+func uploadFile(at fileURL: URL) {
+    var request = URLRequest(url: URL(string: "https://api.example.com/upload")!)
+    request.httpMethod = "POST"
+    let uploadTask = session.uploadTask(with: request, fromFile: fileURL)
+    uploadTask.resume()
+}
+```
+
+**Important:** Background sessions only support `uploadTask(with:fromFile:)` and
+`downloadTask(with:)`. Data tasks, `uploadTask(with:from:)` (Data), and
+closure/async-based tasks are **not** supported.
+
+### Handling App Relaunch
+
+When the system completes a background transfer and your app is not running, it
+relaunches the app. You must:
+
+1. Store the completion handler from
+   `application(_:handleEventsForBackgroundURLSession:completionHandler:)`
+2. Recreate the `URLSession` with the **same identifier**
+3. Call the stored completion handler in `urlSessionDidFinishEvents`
+
+```swift
+// AppDelegate
+func application(
+    _ application: UIApplication,
+    handleEventsForBackgroundURLSession identifier: String,
+    completionHandler: @escaping () -> Void
+) {
+    // Recreating session with the same identifier reconnects to the transfer
+    _ = DownloadManager.shared.session  // trigger lazy init
+    DownloadManager.shared.completionHandler = completionHandler
+}
+
+// In your URLSessionDelegate
+func urlSessionDidFinishEvents(forBackgroundURLSession session: URLSession) {
+    Task { @MainActor in
+        self.completionHandler?()
+        self.completionHandler = nil
+    }
+}
+```
+
+### Handling Download Errors and Retries
+
+```swift
+func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    didCompleteWithError error: (any Error)?
+) {
+    guard let error else { return }  // Success handled in didFinishDownloadingTo
+
+    let nsError = error as NSError
+
+    // Check if download can be resumed
+    if let resumeData = nsError.userInfo[NSURLSessionDownloadTaskResumeData] as? Data {
+        // Store resumeData and retry later
+        let downloadTask = session.downloadTask(withResumeData: resumeData)
+        downloadTask.resume()
+        return
+    }
+
+    // Non-resumable error -- retry from scratch or notify user
+    if nsError.code == NSURLErrorNetworkConnectionLost {
+        // Re-enqueue the download
+        if let url = task.originalRequest?.url {
+            let newTask = session.downloadTask(with: url)
+            newTask.resume()
+        }
+    }
+}
+```
+
+### Progress Tracking
+
+```swift
+func urlSession(
+    _ session: URLSession,
+    downloadTask: URLSessionDownloadTask,
+    didWriteData bytesWritten: Int64,
+    totalBytesWritten: Int64,
+    totalBytesExpectedToWrite: Int64
+) {
+    let progress = Double(totalBytesWritten) / Double(totalBytesExpectedToWrite)
+    // Update UI on main actor if app is in foreground
+    Task { @MainActor in
+        DownloadProgressStore.shared.update(
+            taskID: downloadTask.taskIdentifier,
+            progress: progress
+        )
+    }
+}
+```
+
+## Background Push — Extended Patterns
+
+### Push Payload Requirements
+
+The `content-available: 1` flag is required. You can include custom data:
+
+```json
+{
+    "aps": {
+        "content-available": 1
+    },
+    "type": "new-message",
+    "conversation-id": "abc-123"
+}
+```
+
+**Do not** include `alert`, `badge`, or `sound` if you only want a silent push.
+Including visual notification keys changes the push behavior.
+
+### Rate Limiting
+
+Apple throttles background push delivery. Guidelines:
+
+- System limits to a few pushes per hour per app
+- If the user force-quits the app, background pushes stop entirely until next
+  manual launch
+- High-priority pushes (`apns-priority: 10`) are delivered immediately but must
+  only be used when the notification triggers user-visible content
+- Low-priority pushes (`apns-priority: 5`) are batched and delivered
+  opportunistically
+
+### Handling Push with Async Work
+
+```swift
+func application(
+    _ application: UIApplication,
+    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+    fetchCompletionHandler completionHandler:
+        @escaping (UIBackgroundFetchResult) -> Void
+) {
+    guard let type = userInfo["type"] as? String else {
+        completionHandler(.noData)
+        return
+    }
+
+    Task {
+        do {
+            switch type {
+            case "new-message":
+                let conversationID = userInfo["conversation-id"] as? String
+                let fetched = try await MessageService.shared
+                    .fetchMessages(for: conversationID)
+                completionHandler(fetched ? .newData : .noData)
+
+            case "config-update":
+                try await ConfigService.shared.refreshConfig()
+                completionHandler(.newData)
+
+            default:
+                completionHandler(.noData)
+            }
+        } catch {
+            completionHandler(.failed)
+        }
+    }
+}
+```
+
+**Important:** You have approximately 30 seconds to call `completionHandler`.
+Failure to do so causes the system to penalize your app's background push
+budget.
+
+## SwiftUI BackgroundTask Modifier
+
+SwiftUI provides a `.backgroundTask` modifier as an alternative to manual
+`BGTaskScheduler` registration:
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup { ContentView() }
+            .backgroundTask(.appRefresh("com.example.app.refresh")) {
+                await refreshFeed()
+                // Schedule the next one
+                scheduleAppRefresh()
+            }
+    }
+}
+```
+
+This is a convenience wrapper. Under the hood it registers with
+`BGTaskScheduler`. You still need the Info.plist identifiers and background
+modes.
+
+## BGContinuedProcessingTask — Extended Patterns
+
+### Checking Supported Resources
+
+Before requesting GPU or other resources, verify the device supports them:
+
+```swift
+let supported = BGTaskScheduler.shared.supportedResources
+if supported.contains(.gpu) {
+    request.requiredResources = .gpu
+}
+```
+
+### Submission Strategies
+
+`BGContinuedProcessingTaskRequest.SubmissionStrategy` controls behavior when the
+system cannot run the task immediately:
+
+| Strategy | Behavior |
+|---|---|
+| `.queue` | Task is queued and starts as soon as possible |
+| `.fail` | Submission fails immediately if can't run now |
+
+Use `.fail` when the work is only relevant in the current moment (e.g., a user
+is waiting). Use `.queue` for work that can start whenever the system allows.
+
+### Cancellation by the User
+
+The system shows a Live Activity for continued processing tasks. The user can
+cancel the task from there. Handle this in your expiration handler:
+
+```swift
+task.expirationHandler = {
+    // Clean up partial work
+    cleanupPartialExport()
+    task.setTaskCompleted(success: false)
+}
+```
+
+### Progress Reporting
+
+The system uses your `Progress` object to decide termination priority. Tasks
+with no progress updates are terminated first under resource pressure:
+
+```swift
+// Report fine-grained progress
+let progress = task.progress
+progress.totalUnitCount = Int64(totalItems)
+
+for (index, item) in items.enumerated() {
+    try Task.checkCancellation()
+    await process(item)
+    progress.completedUnitCount = Int64(index + 1)
+}
+```