crossmate

CloudDiagnostics.swift (26626B)

---

 import CloudKit
 import Foundation
 
 extension SyncEngine {
     private struct StorageAuditAsset {
         let containerLabel: String
         let recordType: String
         let field: String
         let recordName: String
         let zoneName: String
         let bytes: Int64
     }
 
     private struct StorageAuditFieldTotal {
         var count = 0
         var bytes: Int64 = 0
         var unavailableCount = 0
     }
 
     private struct StorageAuditTotals {
         var zoneCount = 0
         var recordCount = 0
         var title: String?
         var recordCounts: [String: Int] = [:]
         var assetFields: [String: StorageAuditFieldTotal] = [:]
         var inlineBytes: Int64 = 0
         var unavailableAssetCount = 0
         var recordErrorCount = 0
         var assets: [StorageAuditAsset] = []
 
         var assetBytes: Int64 {
             assetFields.values.reduce(0) { $0 + $1.bytes }
         }
 
         var assetCount: Int {
             assetFields.values.reduce(0) { $0 + $1.count }
         }
 
         mutating func merge(_ other: StorageAuditTotals) {
             zoneCount += other.zoneCount
             recordCount += other.recordCount
             inlineBytes += other.inlineBytes
             unavailableAssetCount += other.unavailableAssetCount
             recordErrorCount += other.recordErrorCount
             assets.append(contentsOf: other.assets)
             for (type, count) in other.recordCounts {
                 recordCounts[type, default: 0] += count
             }
             for (field, value) in other.assetFields {
                 assetFields[field, default: StorageAuditFieldTotal()].count += value.count
                 assetFields[field, default: StorageAuditFieldTotal()].bytes += value.bytes
                 assetFields[field, default: StorageAuditFieldTotal()].unavailableCount +=
                     value.unavailableCount
             }
         }
     }
 
     private struct DocumentsAuditFile: Sendable {
         let path: String
         let bytes: Int64
     }
 
     private struct DocumentsAuditTotals: Sendable {
         var fileCount = 0
         var bytes: Int64 = 0
         var unavailableCount = 0
         var files: [DocumentsAuditFile] = []
     }
 
     struct DiagnosticSnapshot: Sendable {
         let accountStatus: CKAccountStatus
         let engineRunning: Bool
         let pendingChangesCount: Int
         let privatePendingCount: Int
         let sharedPendingCount: Int
         let pendingInvitationCount: Int
     }
 
     /// Record names of pending `.saveRecord` changes queued on the given
     /// scope's engine. Used by tests to verify that outbound enqueues route
     /// to the correct database.
     func pendingSaveRecordNames(scope: CKDatabase.Scope) -> [String] {
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return [] }
         return engine.state.pendingRecordZoneChanges.compactMap {
             if case .saveRecord(let id) = $0 { return id.recordName }
             return nil
         }
     }
 
     /// Zone names queued for deletion on the given scope's engine. Used by
     /// tests to verify delete routing after the local GameEntity is gone.
     func pendingDeletedZoneNames(scope: CKDatabase.Scope) -> [String] {
         let engine = scope == .shared ? sharedEngine : privateEngine
         guard let engine else { return [] }
         return engine.state.pendingDatabaseChanges.compactMap {
             if case .deleteZone(let id) = $0 { return id.zoneName }
             return nil
         }
     }
 
     func diagnosticSnapshot() async -> DiagnosticSnapshot {
         let status: CKAccountStatus
         do { status = try await container.accountStatus() }
         catch { status = .couldNotDetermine }
         let running = privateEngine != nil
         let privateCount = privateEngine.map { $0.state.pendingRecordZoneChanges.count } ?? 0
         let sharedCount = sharedEngine.map { $0.state.pendingRecordZoneChanges.count } ?? 0
         return DiagnosticSnapshot(
             accountStatus: status,
             engineRunning: running,
             pendingChangesCount: privateCount + sharedCount,
             privatePendingCount: privateCount,
             sharedPendingCount: sharedCount,
             pendingInvitationCount: pendingInvitationPingCount()
         )
     }
 
     /// Runs a series of lightweight CloudKit probes and returns human-readable
     /// (name, result) pairs for display in the diagnostics view.
     func probeContainer() async -> [(name: String, result: String)] {
         var results: [(String, String)] = []
         results.append(("containerIdentifier", container.containerIdentifier ?? "nil"))
         do {
             let s = try await container.accountStatus()
             results.append(("accountStatus", describeStatus(s)))
         } catch {
             results.append(("accountStatus", describe(error)))
         }
         do {
             let id = try await container.userRecordID()
             results.append(("userRecordID", id.recordName))
         } catch {
             results.append(("userRecordID", describe(error)))
         }
         do {
             let zones = try await container.privateCloudDatabase.allRecordZones()
             let names = zones.map(\.zoneID.zoneName).joined(separator: ", ")
             results.append(("privateZones", "\(zones.count) zone(s): [\(names)]"))
         } catch {
             results.append(("privateZones", describe(error)))
         }
         do {
             let zones = try await container.sharedCloudDatabase.allRecordZones()
             let names = zones.map(\.zoneID.zoneName).joined(separator: ", ")
             results.append(("sharedZones", "\(zones.count) zone(s): [\(names)]"))
         } catch {
             results.append(("sharedZones", describe(error)))
         }
         // CKSyncEngine creates a CKDatabaseSubscription per scope on first
         // start. If subscription creation silently failed, no push will ever
         // fire for that scope — surface what's actually present so a missing
         // entry is visible from the diagnostics view rather than diagnosed
         // by elimination.
         results.append(await probeSubscriptions(database: container.privateCloudDatabase, label: "privateSubs"))
         results.append(await probeSubscriptions(database: container.sharedCloudDatabase, label: "sharedSubs"))
         return results
     }
 
     /// Downloads the current records in every custom zone owned by this iCloud
     /// account across every container in the app's current entitlements, then
     /// inventories the separate iCloud Documents container. This is an
     /// account-scoped alternative to CloudKit Console's Act As iCloud workflow
     /// for a TestFlight build.
     ///
     /// Superseded containers are audited alongside the current one because
     /// abandoning a generation does not reclaim its records — they keep
     /// consuming the account's iCloud quota until something deletes their zones.
     ///
     /// The audit reads whichever CloudKit environment the build is signed for,
     /// and the two environments have entirely separate private databases, so the
     /// environment is logged first: an empty result means nothing without it.
     ///
     /// The byte count is diagnostic rather than billing-exact: CKAsset file
     /// lengths and inline String/Data payloads are measurable, but CloudKit does
     /// not expose its record, share, zone, encryption, or retained-server-state
     /// overhead. Nothing is saved, changed, or deleted.
     func auditPrivateCloudStorage(
         progress: @MainActor @Sendable (String) -> Void
     ) async {
         let containers: [(label: String, container: CKContainer)] = [
             ("v4", container),
             ("v3", CloudContainer.v3Container),
             ("v2", CloudContainer.v2Container),
             ("v1", CloudContainer.v1Container),
         ]
         let labels = containers.map(\.label).joined(separator: ", ")
         await progress(
             "storage audit: starting entitled containers [\(labels)] in the " +
             "\(cloudEnvironment()) CloudKit environment"
         )
 
         var grandTotals = StorageAuditTotals()
         var unreadable: [String] = []
         for source in containers {
             if let totals = await auditPrivateCloudStorage(
                 label: source.label,
                 container: source.container,
                 progress: progress
             ) {
                 grandTotals.merge(totals)
             } else {
                 unreadable.append(source.label)
             }
         }
 
         await logStorageTotals(
             grandTotals,
             prefix: "storage audit CloudKit grand totals",
             includeLargest: true,
             progress: progress
         )
         // A container that fails to list its zones contributes nothing to the
         // totals, which otherwise read as a complete account inventory. Say so
         // explicitly rather than letting the omission pass silently.
         if unreadable.isEmpty {
             await progress("storage audit coverage: every entitled container was read")
         } else {
             await progress(
                 "storage audit coverage INCOMPLETE: grand totals omit " +
                 "[\(unreadable.joined(separator: ", "))] — those containers failed to " +
                 "list zones, so any bytes they hold are unmeasured"
             )
         }
         await auditICloudDocuments(progress: progress)
         await progress(
             "storage audit complete: measured bytes exclude CloudKit metadata, shares, " +
             "zone overhead, encryption overhead, and server-retained state"
         )
     }
 
     /// The CloudKit environment this build talks to. `ICLOUD_ENVIRONMENT` feeds
     /// both the icloud-container-environment entitlement and this Info.plist
     /// key, so what the audit reports is what the entitlement selected. The
     /// entitlement itself is not readable at runtime on iOS — `SecTask` is
     /// macOS-only — which is why it travels through Info.plist instead.
     private nonisolated func cloudEnvironment() -> String {
         let value = Bundle.main.object(forInfoDictionaryKey: "CrossmateICloudEnvironment")
         guard let environment = value as? String, !environment.isEmpty else {
             return "unreported"
         }
         return environment
     }
 
     /// Deletes every custom zone this account holds in the abandoned v3
     /// container. The private default zone is left alone: the sync engine only
     /// ever wrote to custom zones, and CloudKit rejects change enumeration
     /// there outright ('AppDefaultZone does not support getChanges call'), so
     /// there is nothing to sweep and no cheap way to look.
     ///
     /// Abandoning a container generation does not reclaim its records — they
     /// consume the account's iCloud quota indefinitely — and v3 was abandoned
     /// rather than migrated, so nothing in the app reads it beyond the pre-v4
     /// data probe. This is irreversible, and the app holds no copy of what it
     /// removes.
     ///
     /// Returns `true` only when the container was swept clean, so a caller
     /// that records the work as done cannot mark a partial or offline run
     /// complete. It touches no container the sync engine uses, so it is safe
     /// to run alongside ordinary syncing.
     @discardableResult
     func deleteLegacyCloudData(
         progress: @MainActor @Sendable (String) -> Void
     ) async -> Bool {
         let container = CloudContainer.v3Container
         let identifier = container.containerIdentifier ?? "unknown"
         let database = container.privateCloudDatabase
         await progress(
             "legacy delete: starting v3 [\(identifier)] in the " +
             "\(cloudEnvironment()) CloudKit environment"
         )
 
         let zones: [CKRecordZone]
         do {
             zones = try await database.allRecordZones()
         } catch {
             await progress("legacy delete: couldn't list zones — \(describe(error)) — nothing deleted")
             return false
         }
 
         let defaultZoneID = CKRecordZone.default().zoneID
         let customZoneIDs = zones
             .map(\.zoneID)
             .filter { $0 != defaultZoneID }
             .sorted { $0.zoneName < $1.zoneName }
         await progress("legacy delete: \(customZoneIDs.count) custom zone(s) to remove")
 
         var deleted = 0
         var failed = 0
         // Batched so a single oversized request cannot fail the whole run, and
         // so a long delete reports progress rather than going quiet.
         for start in stride(from: 0, to: customZoneIDs.count, by: 20) {
             let batch = Array(customZoneIDs[start..<min(start + 20, customZoneIDs.count)])
             do {
                 let results = try await database.modifyRecordZones(
                     saving: [],
                     deleting: batch
                 )
                 for (zoneID, result) in results.deleteResults {
                     switch result {
                     case .success:
                         deleted += 1
                     case .failure(let error):
                         failed += 1
                         await progress(
                             "legacy delete: zone [\(zoneID.zoneName)] FAILED — \(describe(error))"
                         )
                     }
                 }
             } catch {
                 failed += batch.count
                 await progress("legacy delete: batch of \(batch.count) FAILED — \(describe(error))")
             }
             await progress(
                 "legacy delete: \(deleted) deleted, \(failed) failed of \(customZoneIDs.count)"
             )
         }
 
         let swept = failed == 0
         await progress(
             "legacy delete complete: zonesDeleted=\(deleted) zonesFailed=\(failed) " +
             "swept=\(swept)"
         )
         return swept
     }
 
     private func auditPrivateCloudStorage(
         label: String,
         container: CKContainer,
         progress: @MainActor @Sendable (String) -> Void
     ) async -> StorageAuditTotals? {
         let identifier = container.containerIdentifier ?? "unknown"
         let database = container.privateCloudDatabase
         await progress("storage audit container \(label) [\(identifier)]: starting private database")
 
         let zones: [CKRecordZone]
         do {
             zones = try await database.allRecordZones()
         } catch {
             await progress(
                 "storage audit container \(label): couldn't list private zones — \(describe(error))"
             )
             return nil
         }
 
         let defaultZoneID = CKRecordZone.default().zoneID
         let customZones = zones
             .map(\.zoneID)
             .filter { $0 != defaultZoneID }
             .sorted { $0.zoneName < $1.zoneName }
         await progress(
             "storage audit container \(label): found \(customZones.count) custom zone(s); " +
             "asset contents will be downloaded"
         )
 
         var totals = StorageAuditTotals()
         for (index, zoneID) in customZones.enumerated() {
             do {
                 let zone = try await auditStorageZone(zoneID, containerLabel: label, in: database)
                 var completedZone = zone
                 completedZone.zoneCount = 1
                 totals.merge(completedZone)
 
                 let types = formattedCounts(zone.recordCounts)
                 let title = zone.title.map { " title=[\(singleLine($0))]" } ?? ""
                 await progress(
                     "storage audit container \(label) zone \(index + 1)/\(customZones.count) " +
                     "[\(zoneID.zoneName)]:\(title) records=\(zone.recordCount) " +
                     "assets=\(zone.assetCount) assetBytes=\(formatBytes(zone.assetBytes)) " +
                     "inline=\(formatBytes(zone.inlineBytes)) " +
                     "types=[\(types)]"
                 )
             } catch {
                 await progress(
                     "storage audit container \(label) zone \(index + 1)/\(customZones.count) " +
                     "[\(zoneID.zoneName)] FAILED — \(describe(error))"
                 )
             }
         }
 
         await logStorageTotals(
             totals,
             prefix: "storage audit container \(label) totals",
             includeLargest: false,
             progress: progress
         )
         return totals
     }
 
     private func logStorageTotals(
         _ totals: StorageAuditTotals,
         prefix: String,
         includeLargest: Bool,
         progress: @MainActor @Sendable (String) -> Void
     ) async {
         await progress(
             "\(prefix): zones=\(totals.zoneCount) " +
             "records=\(totals.recordCount) " +
             "assets=\(totals.assetCount) assetBytes=\(formatBytes(totals.assetBytes)) " +
             "inline=\(formatBytes(totals.inlineBytes)) " +
             "measured=\(formatBytes(totals.assetBytes + totals.inlineBytes))"
         )
         await progress("\(prefix) record types: [\(formattedCounts(totals.recordCounts))]")
 
         for field in totals.assetFields.keys.sorted() {
             guard let value = totals.assetFields[field] else { continue }
             await progress(
                 "\(prefix) asset field \(field): count=\(value.count) " +
                 "bytes=\(formatBytes(value.bytes)) unavailable=\(value.unavailableCount)"
             )
         }
 
         guard includeLargest else {
             if totals.unavailableAssetCount > 0 || totals.recordErrorCount > 0 {
                 await logStorageWarnings(totals, prefix: prefix, progress: progress)
             }
             return
         }
 
         let largest = totals.assets
             .sorted { $0.bytes > $1.bytes }
             .prefix(20)
         for (index, asset) in largest.enumerated() {
             await progress(
                 "\(prefix) largest #\(index + 1): \(asset.recordType).\(asset.field) " +
                 "bytes=\(formatBytes(asset.bytes)) container=\(asset.containerLabel) " +
                 "zone=\(asset.zoneName) " +
                 "record=\(asset.recordName)"
             )
         }
 
         if totals.unavailableAssetCount > 0 || totals.recordErrorCount > 0 {
             await logStorageWarnings(totals, prefix: prefix, progress: progress)
         }
     }
 
     private func logStorageWarnings(
         _ totals: StorageAuditTotals,
         prefix: String,
         progress: @MainActor @Sendable (String) -> Void
     ) async {
         await progress(
             "\(prefix) warnings: unavailableAssets=\(totals.unavailableAssetCount) " +
             "recordErrors=\(totals.recordErrorCount)"
         )
     }
 
     private func auditICloudDocuments(
         progress: @MainActor @Sendable (String) -> Void
     ) async {
         guard let root = FileManager.default.url(
             forUbiquityContainerIdentifier: CloudContainer.v1Identifier
         ) else {
             await progress("storage audit iCloud Documents: container unavailable")
             return
         }
         let documents = root.appendingPathComponent("Documents", isDirectory: true)
         let totals = Self.scanICloudDocuments(at: documents)
 
         await progress(
             "storage audit iCloud Documents totals: files=\(totals.fileCount) " +
             "bytes=\(formatBytes(totals.bytes)) unavailable=\(totals.unavailableCount)"
         )
         for (index, file) in totals.files.sorted(by: { $0.bytes > $1.bytes }).prefix(20).enumerated() {
             await progress(
                 "storage audit iCloud Documents largest #\(index + 1): " +
                 "bytes=\(formatBytes(file.bytes)) path=[\(singleLine(file.path))]"
             )
         }
     }
 
     private nonisolated static func scanICloudDocuments(
         at documents: URL
     ) -> DocumentsAuditTotals {
         let keys: [URLResourceKey] = [.isRegularFileKey, .fileSizeKey]
         guard let enumerator = FileManager.default.enumerator(
             at: documents,
             includingPropertiesForKeys: keys,
             options: [.skipsHiddenFiles, .skipsPackageDescendants]
         ) else {
             return DocumentsAuditTotals(unavailableCount: 1)
         }
 
         var totals = DocumentsAuditTotals()
         for case let url as URL in enumerator {
             guard let values = try? url.resourceValues(forKeys: Set(keys)),
                   values.isRegularFile == true
             else { continue }
             totals.fileCount += 1
             if let size = values.fileSize {
                 let bytes = Int64(size)
                 totals.bytes += bytes
                 totals.files.append(
                     DocumentsAuditFile(
                         path: url.path.replacingOccurrences(of: documents.path + "/", with: ""),
                         bytes: bytes
                     )
                 )
             } else {
                 totals.unavailableCount += 1
             }
         }
 
         return totals
     }
 
     private func auditStorageZone(
         _ zoneID: CKRecordZone.ID,
         containerLabel: String,
         in database: CKDatabase
     ) async throws -> StorageAuditTotals {
         var totals = StorageAuditTotals()
         var token: CKServerChangeToken?
         var moreComing = true
 
         while moreComing {
             let page = try await database.recordZoneChanges(
                 inZoneWith: zoneID,
                 since: token
             )
             token = page.changeToken
             moreComing = page.moreComing
 
             for result in page.modificationResultsByID.values {
                 do {
                     let record = try result.get().record
                     measure(record, containerLabel: containerLabel, into: &totals)
                 } catch {
                     totals.recordErrorCount += 1
                 }
             }
         }
         return totals
     }
 
     private func measure(
         _ record: CKRecord,
         containerLabel: String,
         into totals: inout StorageAuditTotals
     ) {
         totals.recordCount += 1
         totals.recordCounts[record.recordType, default: 0] += 1
         if totals.title == nil,
            record.recordType == "Game"
             || record.recordType == Archive.recordType
             || record.recordType == Archive.legacyRecordType {
             totals.title = record["title"] as? String
         }
 
         for field in record.allKeys() {
             guard let value = record[field] else { continue }
             if let asset = value as? CKAsset {
                 let key = "\(record.recordType).\(field)"
                 var fieldTotal = totals.assetFields[key, default: StorageAuditFieldTotal()]
                 fieldTotal.count += 1
                 if let bytes = asset.fileURL.flatMap(assetFileSize) {
                     fieldTotal.bytes += bytes
                     totals.assets.append(
                         StorageAuditAsset(
                             containerLabel: containerLabel,
                             recordType: record.recordType,
                             field: field,
                             recordName: record.recordID.recordName,
                             zoneName: record.recordID.zoneID.zoneName,
                             bytes: bytes
                         )
                     )
                 } else {
                     fieldTotal.unavailableCount += 1
                     totals.unavailableAssetCount += 1
                 }
                 totals.assetFields[key] = fieldTotal
             } else {
                 totals.inlineBytes += approximateInlineSize(value)
             }
         }
     }
 
     private func assetFileSize(at url: URL) -> Int64? {
         guard let attributes = try? FileManager.default.attributesOfItem(atPath: url.path),
               let size = attributes[.size] as? NSNumber
         else { return nil }
         return size.int64Value
     }
 
     private func approximateInlineSize(_ value: Any) -> Int64 {
         switch value {
         case let data as Data:
             return Int64(data.count)
         case let string as String:
             return Int64(string.utf8.count)
         case let values as [Any]:
             return values.reduce(0) { $0 + approximateInlineSize($1) }
         case is NSNumber, is Date:
             return 8
         case let reference as CKRecord.Reference:
             return Int64(reference.recordID.recordName.utf8.count)
         default:
             return 0
         }
     }
 
     private func formattedCounts(_ counts: [String: Int]) -> String {
         counts.keys.sorted().compactMap { key in
             counts[key].map { "\(key)=\($0)" }
         }.joined(separator: ", ")
     }
 
     private func formatBytes(_ bytes: Int64) -> String {
         "\(ByteCountFormatter.string(fromByteCount: bytes, countStyle: .file)) (\(bytes) B)"
     }
 
     private func singleLine(_ value: String) -> String {
         String(value.replacing(/\s+/, with: " ").prefix(80))
     }
 
     private func probeSubscriptions(
         database: CKDatabase,
         label: String
     ) async -> (String, String) {
         do {
             let subs = try await database.allSubscriptions()
             if subs.isEmpty {
                 return (label, "0 subscriptions — pushes will not fire")
             }
             let descriptions = subs.map { sub -> String in
                 let kind: String
                 switch sub {
                 case is CKDatabaseSubscription: kind = "database"
                 case is CKQuerySubscription: kind = "query"
                 case is CKRecordZoneSubscription: kind = "zone"
                 default: kind = "other(\(type(of: sub)))"
                 }
                 let silent = sub.notificationInfo?.shouldSendContentAvailable == true ? "silent" : "alert-only"
                 return "\(kind):\(sub.subscriptionID)[\(silent)]"
             }
             return (label, "\(subs.count): [\(descriptions.joined(separator: ", "))]")
         } catch {
             return (label, describe(error))
         }
     }
 
     nonisolated func describe(_ error: Error) -> String {
         let nsError = error as NSError
         return "ERROR domain=\(nsError.domain) code=\(nsError.code) \(nsError.localizedDescription)"
     }
 
     private nonisolated func describeStatus(_ status: CKAccountStatus) -> String {
         switch status {
         case .available: return "available"
         case .noAccount: return "noAccount"
         case .restricted: return "restricted"
         case .couldNotDetermine: return "couldNotDetermine"
         case .temporarilyUnavailable: return "temporarilyUnavailable"
         @unknown default: return "unknown(\(status.rawValue))"
         }
     }
 }