@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/ios-networking/references/file-storage-patterns.md

@@ -1,354 +1,212 @@
 # File Storage Patterns
 
-Guidance on choosing the right directory, applying file protection, managing
-backup exclusions, and handling storage pressure on iOS.
-
-## Contents
-
-- [Directory Selection Guide](#directory-selection-guide)
-- [FileProtectionType Levels](#fileprotectiontype-levels)
-- [Backup Exclusion (isExcludedFromBackup)](#backup-exclusion-isexcludedfrombackup)
-- [Storage Pressure Handling](#storage-pressure-handling)
+Downloaded and uploaded data has to live somewhere. Where it lives decides
+whether it is backed up, whether the system may delete it, and when it can be
+read.
 
 ## Directory Selection Guide
 
-iOS provides four primary directories for app data. Choose based on whether
-the data is user-generated, re-creatable, or temporary.
+Ask three questions: did the user create it, can the app recreate it, and is
+it only needed for the next few minutes?
 
-| Directory | Backed Up | Purged by System | Use For |
+| Directory | Backed up | System may purge | Put here |
 |---|---|---|---|
-| `Documents/` | Yes | No | User-generated content (documents, exports, user files) |
-| `Library/Application Support/` | Yes | No | App-generated supporting files (databases, config, caches that should survive updates) |
-| `Library/Caches/` | No | Yes (low storage) | Re-creatable data (downloaded images, API responses, computed data) |
-| `tmp/` | No | Yes (anytime) | Truly temporary files (in-progress uploads, scratch files) |
+| `Documents/` | Yes | No | Things the user made or explicitly saved |
+| `Library/Application Support/` | Yes | No | Data the app itself owns: databases, configuration, caches that must survive an update |
+| `Library/Caches/` | No | Yes, when storage runs low | Anything that can be downloaded or rebuilt |
+| `tmp/` | No | Yes, at any time | Scratch files, in-flight upload bodies |
 
-### Accessing Standard Directories
-
-Use `FileManager.default.urls(for:in:)` to get the correct path. Never
-hardcode paths.
+Ask `FileManager` for the location; never build these paths by hand.
 
 ```swift
-import Foundation
-
-// Documents/  -  user-generated content, backed up by iCloud/iTunes
-let documentsURL = FileManager.default.urls(
-    for: .documentDirectory, in: .userDomainMask
-).first!
-
-// Library/Application Support/  -  app-generated supporting data, backed up
-let appSupportURL = FileManager.default.urls(
-    for: .applicationSupportDirectory, in: .userDomainMask
-).first!
-// Create if it doesn't exist (not auto-created)
-try FileManager.default.createDirectory(
-    at: appSupportURL, withIntermediateDirectories: true
-)
-
-// Library/Caches/  -  re-creatable data, not backed up, may be purged
-let cachesURL = FileManager.default.urls(
-    for: .cachesDirectory, in: .userDomainMask
-).first!
-
-// tmp/  -  temporary files, purged by system periodically
-let tmpURL = FileManager.default.temporaryDirectory
+let fm = FileManager.default
+let documents = try fm.url(for: .documentDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
+let support = try fm.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true)
+let caches = try fm.url(for: .cachesDirectory, in: .userDomainMask, appropriateFor: nil, create: false)
+let scratch = fm.temporaryDirectory
+
+let exportedInvoice = documents.appending(path: "invoice-2031.pdf")
+let catalogDatabase = support.appending(path: "catalog.sqlite")
+let coverThumbnail = caches.appending(path: "covers/1182.jpg")
+let pendingUpload = scratch.appending(path: "upload-\(UUID().uuidString).bin")
 ```
 
-### Choosing the Right Directory
-
-```swift
-// User's exported PDF  -  Documents/
-let exportURL = documentsURL.appendingPathComponent("Report.pdf")
-try pdfData.write(to: exportURL)
-
-// App's SQLite database  -  Library/Application Support/
-let dbURL = appSupportURL.appendingPathComponent("AppData.sqlite")
-
-// Downloaded thumbnail cache  -  Library/Caches/
-let thumbURL = cachesURL.appendingPathComponent("thumbnails/\(imageID).jpg")
-
-// In-progress upload  -  tmp/
-let uploadURL = tmpURL.appendingPathComponent(UUID().uuidString + ".tmp")
-```
+`FileManager.default.urls(for:in:)` returns the same locations as an array.
+Application Support does not exist on a fresh install. Pass `create: true`
+as above, or call `createDirectory(at:withIntermediateDirectories: true)`
+before writing into it.
 
 ## FileProtectionType Levels
 
-iOS encrypts files at rest using Data Protection. The protection level
-determines when the file is accessible relative to the device lock state.
-
-Docs: [FileProtectionType](https://sosumi.ai/documentation/foundation/fileprotectiontype),
-[Encrypting Your App's Files](https://sosumi.ai/documentation/uikit/encrypting-your-app-s-files)
+Data Protection encrypts files at rest, and the protection level decides
+whether a file can be read while the device is locked. See the
+[protection type reference](https://developer.apple.com/documentation/foundation/fileprotectiontype)
+and the [file encryption article](https://developer.apple.com/documentation/uikit/encrypting-your-app-s-files).
 
-| Level | Constant | When Accessible | Use For |
-|---|---|---|---|
-| Complete | `.complete` | Only when device is unlocked | Sensitive user data (health records, financial data) |
-| Complete Unless Open | `.completeUnlessOpen` | Can finish if opened before lock | Active downloads, recordings in progress |
-| Until First Auth | `.completeUntilFirstUserAuthentication` | After first unlock (default) | Most app data; background-accessible content |
-| None | `.none` | Always, even before first unlock | Non-sensitive system-required data |
-
-### Setting File Protection
+| Level | Readable | Good for |
+|---|---|---|
+| `.complete` | Only while unlocked | Health, finance and other sensitive records |
+| `.completeUnlessOpen` | A file opened before locking stays usable | Recordings or downloads in progress at lock time |
+| `.completeUntilFirstUserAuthentication` | Any time after the first unlock since boot (the default) | Most app data, including data used in the background |
+| `.none` | Always, even before the first unlock | Non-sensitive data needed at boot |
 
 ```swift
-import Foundation
-
-// Option 1: Set protection when writing data
-try sensitiveData.write(to: fileURL, options: .completeFileProtection)
-
-// Option 2: Set protection via FileManager attributes
-try FileManager.default.setAttributes(
-    [.protectionKey: FileProtectionType.complete],
-    ofItemAtPath: fileURL.path
-)
-
-// Option 3: Set protection on a directory (applies to new files within)
-try FileManager.default.setAttributes(
-    [.protectionKey: FileProtectionType.complete],
-    ofItemAtPath: secureDirectoryURL.path
-)
-```
+try statement.write(to: fileURL, options: .completeFileProtection)
 
-### Checking Current Protection Level
+let files = FileManager.default
+let lockedDown: [FileAttributeKey: Any] = [.protectionKey: FileProtectionType.complete]
+try files.setAttributes(lockedDown, ofItemAtPath: vaultFolder.path())
 
-```swift
-let attributes = try FileManager.default.attributesOfItem(atPath: fileURL.path)
-if let protection = attributes[.protectionKey] as? FileProtectionType {
-    switch protection {
-    case .complete:
-        print("File is fully protected")
-    case .completeUnlessOpen:
-        print("Protected unless already open")
-    case .completeUntilFirstUserAuthentication:
-        print("Protected until first unlock (default)")
-    case .none:
-        print("No encryption")
-    default:
-        break
-    }
-}
+let attributes = try files.attributesOfItem(atPath: fileURL.path())
+let level = attributes[.protectionKey] as? FileProtectionType
 ```
 
-### Handling Protected Data Availability
+Protection set on a directory applies to files created in it afterwards.
 
-Files with `.complete` protection are inaccessible when the device is locked.
-Check availability before accessing:
+A `.complete` file cannot be opened while the device is locked. Check
+`UIApplication.shared.isProtectedDataAvailable` before touching one, and
+watch the transitions:
 
 ```swift
-import UIKit
-
-// Check if protected data is currently available
-if UIApplication.shared.isProtectedDataAvailable {
-    // Safe to read .complete files
-    let data = try Data(contentsOf: protectedFileURL)
-} else {
-    // Wait for device unlock
-}
-
-// Observe availability changes
-NotificationCenter.default.addObserver(
-    forName: UIApplication.protectedDataDidBecomeAvailableNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Protected files are now accessible
-}
-
-NotificationCenter.default.addObserver(
-    forName: UIApplication.protectedDataWillBecomeUnavailableNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Close file handles to .complete files
-}
+let center = NotificationCenter.default
+let lockSoon = center.notifications(named: UIApplication.protectedDataWillBecomeUnavailableNotification)
+let unlocked = center.notifications(named: UIApplication.protectedDataDidBecomeAvailableNotification)
 ```
 
-## Backup Exclusion (isExcludedFromBackup)
-
-Exclude large re-downloadable content from iCloud/iTunes backup to avoid
-bloating the user's backup. Apple may reject apps that back up excessive
-re-creatable data.
+Close handles to `.complete` files when the will-become-unavailable
+notification arrives; reopen them after the did-become-available one.
 
-Docs: [URLResourceValues](https://sosumi.ai/documentation/foundation/urlresourcevalues)
+## Backup Exclusion (isExcludedFromBackup)
 
-### Setting the Exclusion Flag
+Large content that can be fetched again should not go into iCloud or
+computer backups. App Review can reject an app that backs up a lot of
+re-creatable data. See the
+[resource values reference](https://developer.apple.com/documentation/foundation/urlresourcevalues).
 
 ```swift
-import Foundation
-
-// Exclude a file or directory from backup
-func excludeFromBackup(_ url: URL) throws {
-    var resourceValues = URLResourceValues()
-    resourceValues.isExcludedFromBackup = true
-    var mutableURL = url
-    try mutableURL.setResourceValues(resourceValues)
+func keepOutOfBackup(_ item: URL) throws {
+    var target = item
+    var values = URLResourceValues()
+    values.isExcludedFromBackup = true
+    try target.setResourceValues(values)
 }
 
-// Usage
-let largeCache = cachesURL.appendingPathComponent("video-cache")
-try excludeFromBackup(largeCache)
-```
-
-### Checking the Exclusion Flag
-
-```swift
-func isExcludedFromBackup(_ url: URL) throws -> Bool {
-    let values = try url.resourceValues(forKeys: [.isExcludedFromBackupKey])
+func skipsBackup(_ item: URL) throws -> Bool {
+    let values = try item.resourceValues(forKeys: [.isExcludedFromBackupKey])
     return values.isExcludedFromBackup ?? false
 }
 ```
 
-### When to Exclude from Backup
-
-| Exclude | Keep in Backup |
+| Exclude | Keep in backup |
 |---|---|
-| Downloaded media (images, videos, audio) | User-created documents |
-| API response caches | User preferences and settings |
-| Generated thumbnails or previews | App databases with user data |
-| Offline map tiles | In-app purchase receipts |
-| Pre-computed search indexes | User-generated content |
+| Downloaded media | The user's documents |
+| API response caches | Preferences and settings |
+| Generated thumbnails and previews | Databases holding user data |
+| Map tiles cached for offline use | In-app purchase receipts |
+| Precomputed search indexes | Anything the user created |
 
-### Common Pattern: Application Support with Exclusion
-
-Store re-downloadable data in Application Support but exclude from backup:
-
-```swift
-let offlineDataURL = appSupportURL.appendingPathComponent("OfflineData")
-try FileManager.default.createDirectory(
-    at: offlineDataURL, withIntermediateDirectories: true
-)
-try excludeFromBackup(offlineDataURL)
-
-// Files in this directory persist across app updates but don't bloat backup
-try downloadedData.write(to: offlineDataURL.appendingPathComponent("map-tiles.db"))
-```
+A useful middle ground: put re-downloadable data in a subfolder of
+Application Support and exclude that folder from backup. It survives app
+updates and system purges without inflating the backup.
 
 ## Storage Pressure Handling
 
-When the device runs low on storage, iOS may purge files in `Library/Caches/`
-and `tmp/`. Apps should proactively manage storage and respond to low-space
-conditions.
+Once free space gets tight, iOS may empty `Library/Caches/` and
+`tmp/` without asking. Do not rely on that alone; keep your own footprint in
+check.
 
-### Checking Available Storage
+### Measuring free space
 
 ```swift
-import Foundation
-
-func availableDiskSpace() throws -> Int64 {
-    let values = try URL(fileURLWithPath: NSHomeDirectory())
-        .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
-    return values.volumeAvailableCapacityForImportantUsage ?? 0
+func freeBytes(forImportantWork important: Bool) throws -> Int64 {
+    let key: URLResourceKey = important ? .volumeAvailableCapacityForImportantUsageKey
+                                        : .volumeAvailableCapacityForOpportunisticUsageKey
+    let values = try URL.homeDirectory.resourceValues(forKeys: [key])
+    return (important ? values.volumeAvailableCapacityForImportantUsage
+                      : values.volumeAvailableCapacityForOpportunisticUsage) ?? 0
 }
 
-// Use .volumeAvailableCapacityForImportantUsageKey for important operations
-// Use .volumeAvailableCapacityForOpportunisticUsageKey for optional operations
-// The opportunistic value is always <= the important value
-
-func hasSpaceForDownload(bytes: Int64) throws -> Bool {
-    let available = try availableDiskSpace()
-    return available > bytes
+func hasRoom(for byteCount: Int64) -> Bool {
+    ((try? freeBytes(forImportantWork: true)) ?? 0) >= byteCount
 }
 ```
 
-### Responding to Low Storage Notifications
+Use the important-usage figure for work the user asked for and the
+opportunistic figure for optional work such as prefetching. The
+opportunistic value is never larger than the important one.
 
-```swift
-import UIKit
-
-// iOS posts this when storage is critically low (UIKit apps)
-NotificationCenter.default.addObserver(
-    forName: UIApplication.didReceiveMemoryWarningNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Clear in-memory caches; consider trimming disk caches too
-    clearImageCache()
-}
+### Where low-disk signals actually come from
+
+There is no general system notification that says storage is low. The
+signals an app can use are:
 
-// Check storage proactively at app launch or before large operations
-func checkStorageAndCleanup() throws {
-    let availableBytes = try availableDiskSpace()
-    let threshold: Int64 = 100 * 1024 * 1024  // 100 MB
+- The capacity keys above, read at launch and before any large download,
+  export or cache fill. Below a threshold you choose (for example 100 MB),
+  run cleanup and skip optional work.
+- Write failures. A write that runs out of space throws
+  `CocoaError(.fileWriteOutOfSpace)` (POSIX `ENOSPC` underneath). Catch it,
+  free cache space, and retry once or tell the user.
+- `NSBundleResourceRequestLowDiskSpace`, posted only to apps that use
+  On-Demand Resources, when the system needs space back from them.
 
-    if availableBytes < threshold {
-        try performCleanup()
+`UIApplication.didReceiveMemoryWarningNotification` is about RAM, not disk.
+Respond to it by dropping in-memory caches (an `NSCache` does this on its
+own); it says nothing about free storage and is not a reason to delete files.
+
+```swift
+func writeCache(_ blob: Data, into file: URL, cleaner: CacheJanitor) throws {
+    do {
+        try blob.write(to: file, options: .atomic)
+    } catch let failure as CocoaError where failure.code == .fileWriteOutOfSpace {
+        try cleaner.sweep()
+        try blob.write(to: file, options: .atomic)
     }
 }
 ```
 
-### Implementing Cleanup Strategies
+### Cleaning a cache directory
 
 ```swift
-import Foundation
-
-struct StorageCleaner {
-    let cachesURL: URL
-    let maxCacheAge: TimeInterval  // e.g., 7 days
-    let maxCacheSize: Int64        // e.g., 500 MB
-
-    /// Remove files older than maxCacheAge
-    func removeExpiredFiles() throws {
-        let contents = try FileManager.default.contentsOfDirectory(
-            at: cachesURL,
-            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
-            options: .skipsHiddenFiles
-        )
-
-        let cutoff = Date.now.addingTimeInterval(-maxCacheAge)
-
-        for fileURL in contents {
-            let values = try fileURL.resourceValues(
-                forKeys: [.contentModificationDateKey]
-            )
-            if let modified = values.contentModificationDate, modified < cutoff {
-                try FileManager.default.removeItem(at: fileURL)
-            }
-        }
-    }
+struct CacheJanitor {
+    let folder: URL
+    var maxAge: Duration = .seconds(7 * 24 * 60 * 60)
+    var maxBytes = 500 * 1024 * 1024
 
-    /// Trim cache to maxCacheSize using LRU eviction
-    func trimToSize() throws {
-        let contents = try FileManager.default.contentsOfDirectory(
-            at: cachesURL,
-            includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
-            options: .skipsHiddenFiles
-        )
-
-        // Sort oldest first
-        let sorted = try contents.sorted { a, b in
-            let aDate = try a.resourceValues(forKeys: [.contentModificationDateKey])
-                .contentModificationDate ?? .distantPast
-            let bDate = try b.resourceValues(forKeys: [.contentModificationDateKey])
-                .contentModificationDate ?? .distantPast
-            return aDate < bDate
-        }
+    private struct Entry { let url: URL; let modified: Date; let size: Int }
 
-        // Calculate total size
-        var totalSize: Int64 = 0
-        for fileURL in sorted {
-            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
-            totalSize += Int64(values.fileSize ?? 0)
+    func sweep() throws {
+        try removeExpired()
+        try trimToBudget()
+    }
+
+    func removeExpired() throws {
+        let cutoff = Date.now.addingTimeInterval(-Double(maxAge.components.seconds))
+        for entry in try entries() where entry.modified < cutoff {
+            try FileManager.default.removeItem(at: entry.url)
         }
+    }
 
-        // Delete oldest files until under budget
-        for fileURL in sorted {
-            guard totalSize > maxCacheSize else { break }
-            let values = try fileURL.resourceValues(forKeys: [.fileSizeKey])
-            let fileSize = Int64(values.fileSize ?? 0)
-            try FileManager.default.removeItem(at: fileURL)
-            totalSize -= fileSize
+    func trimToBudget() throws {
+        let oldestFirst = try entries().sorted { $0.modified < $1.modified }
+        var total = oldestFirst.reduce(0) { $0 + $1.size }
+        for entry in oldestFirst where total > maxBytes {
+            try FileManager.default.removeItem(at: entry.url)
+            total -= entry.size
         }
     }
 
-    /// Full cleanup: expired files first, then trim to size
-    func performCleanup() throws {
-        try removeExpiredFiles()
-        try trimToSize()
+    private func entries() throws -> [Entry] {
+        let keys: [URLResourceKey] = [.contentModificationDateKey, .fileSizeKey]
+        return try FileManager.default
+            .contentsOfDirectory(at: folder, includingPropertiesForKeys: keys, options: .skipsHiddenFiles)
+            .compactMap { item in
+                let info = try item.resourceValues(forKeys: Set(keys))
+                guard let modified = info.contentModificationDate else { return nil }
+                return Entry(url: item, modified: modified, size: info.fileSize ?? 0)
+            }
     }
 }
-
-// Usage
-let cleaner = StorageCleaner(
-    cachesURL: FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!,
-    maxCacheAge: 7 * 24 * 60 * 60,   // 7 days
-    maxCacheSize: 500 * 1024 * 1024    // 500 MB
-)
-try cleaner.performCleanup()
 ```
+
+`sweep()` deletes files past their age first, then removes the least
+recently modified files until the folder fits its size budget.