crossmate

GameArchiver.swift (12306B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Writes the private-zone archive of a finished shared game, and promotes it to
 /// a normal completed game when the original is revoked.
 ///
 /// See `Archive` for the why. This type owns the side effects: it
 /// creates the `archive-<gameID>` zone in the participant's *private* database
 /// and saves the snapshot record there with a raw `CKModifyRecordsOperation`
 /// (mirroring `FriendController`'s raw private-DB writes), rather than routing
 /// through `CKSyncEngine`'s entity-driven push path — the archive is not backed
 /// by a normal sync entity. Every device (including the author) then receives
 /// the record back through the private engine's `fetchedRecordZoneChanges` and
 /// applies it (`SyncEngine` `Archive` case): inert where the live original
 /// still exists, hydrated into a completed owned game where it doesn't.
 @MainActor
 final class GameArchiver {
     nonisolated static let archiveRetryWindow: TimeInterval = 14 * 24 * 60 * 60
 
     private let container: CKContainer
     private let persistence: PersistenceController
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor?
     private let eventLog: EventLog?
 
     init(
         container: CKContainer,
         persistence: PersistenceController,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor? = nil,
         eventLog: EventLog? = nil
     ) {
         self.container = container
         self.persistence = persistence
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.eventLog = eventLog
     }
 
     // MARK: - Write
 
     /// Archives a just-finished participant game, refreshing the snapshot until
     /// every contributing device's journal is captured. A no-op for owned games
     /// (already durable in the owner's own private DB) and for games already
     /// marked complete (`archivedAt != nil`).
     ///
     /// Convergence: at completion the peers' journals almost never exist yet —
     /// they upload at *their* own completion — so the first pass usually captures
     /// only this device's log. Each later call (driven by the reconcile sweep)
     /// re-fetches the shared zone, folds in whatever has since uploaded, and
     /// force-overwrites the archive. `archivedAt` is set once the log is
     /// complete (one journal per device that wrote grid state), or once the
     /// 14-day retry window has elapsed and we deliberately settle for the best
     /// available snapshot.
     func archiveIfNeeded(gameID: UUID) async {
         let ctx = persistence.container.newBackgroundContext()
         let local: Archive.Snapshot? = ctx.performAndWait {
             guard shouldArchive(gameID: gameID, in: ctx) else { return nil }
             return Archive.snapshot(forGameID: gameID, in: ctx)
         }
         guard let local else { return }
 
         // Gather every available copy of each device's log, newest-wins:
         // this device's own local log (authoritative) over a freshly-fetched
         // peer log over whatever a sibling device already folded into the cloud
         // archive.
         let fetch = try? await syncEngine.fetchReplay(forGameID: local.originalGameID)
         let existing = await fetchArchivePayload(originalGameID: local.originalGameID)
         var snapshot = local
         if let existing { snapshot = Archive.merging(snapshot, peerJournals: existing.journal) }
         if let fetch { snapshot = Archive.merging(snapshot, peerJournals: fetch.journals) }
 
         // Complete = a journal for every device that wrote grid state. Unknown
         // when the shared zone is unreachable (no fetch), so treat as incomplete
         // and let a later sweep settle it.
         let present = Set(snapshot.journal.map(\.key))
         let isComplete = fetch.map { $0.expectedDevices.subtracting(present).isEmpty } ?? false
         let retryExpired = Self.hasArchiveRetryExpired(completedAt: local.completedAt)
         let shouldFinalize = isComplete || retryExpired
         if retryExpired && !isComplete {
             syncMonitor?.note(
                 "archive \(local.originalGameID.uuidString.prefix(8)): " +
                 "retry window expired; finalizing incomplete archive"
             )
         }
 
         // Skip a redundant overwrite (and the push churn it causes) when the
         // cloud archive already holds every device we'd write — only the
         // completeness marker might still need flipping.
         if let existing, present.isSubset(of: Set(existing.journal.map(\.key))) {
             if shouldFinalize { markArchived(originalGameID: local.originalGameID) }
             return
         }
         await write(snapshot, markComplete: shouldFinalize)
     }
 
     /// Re-attempts (and converges) the archive for any completed participant game
     /// not yet marked complete — covering a completion that happened while
     /// offline, one whose peers hadn't uploaded their journals yet, or a game
     /// completed before this feature shipped. Driven by the cold-launch freshen
     /// sweep; after 14 days from completion, `archiveIfNeeded` finalizes the
     /// best available archive so legacy/incomplete games stop retrying forever.
     func reconcileUnarchived() async {
         let ctx = persistence.container.newBackgroundContext()
         let ids: [UUID] = ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(
                 format: "databaseScope == 1 AND completedAt != nil AND archivedAt == nil AND isAccessRevoked == NO"
             )
             return ((try? ctx.fetch(req)) ?? []).compactMap(\.id)
         }
         for id in ids {
             await archiveIfNeeded(gameID: id)
         }
     }
 
     nonisolated static func hasArchiveRetryExpired(
         completedAt: Date,
         now: Date = Date()
     ) -> Bool {
         now.timeIntervalSince(completedAt) >= archiveRetryWindow
     }
 
     private nonisolated func shouldArchive(gameID: UUID, in ctx: NSManagedObjectContext) -> Bool {
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         req.fetchLimit = 1
         guard let entity = try? ctx.fetch(req).first else { return false }
         return entity.databaseScope == 1
             && entity.completedAt != nil
             && entity.archivedAt == nil
             && !entity.isAccessRevoked
     }
 
     /// Force-overwrites the archive record with `snapshot`. `markComplete` flips
     /// the `archivedAt` marker that stops the reconcile sweep — set only when the
     /// caller knows every contributing device is captured.
     private func write(_ snapshot: Archive.Snapshot, markComplete: Bool) async {
         let zoneID = Archive.zoneID(forOriginalGameID: snapshot.originalGameID)
         do {
             try await ensureZone(zoneID)
             let record = try Archive.record(from: snapshot)
             try await save(record)
             if markComplete { markArchived(originalGameID: snapshot.originalGameID) }
         } catch {
             syncMonitor?.recordError("archive game", error)
             eventLog?.note(
                 "GameArchiver: write failed for \(snapshot.originalGameID.uuidString) — \(error)",
                 level: "error"
             )
         }
     }
 
     /// Reads back the archive record from this user's private database — the
     /// accumulated, possibly cross-device-converged copy. `nil` when it doesn't
     /// exist yet or the database is unreachable.
     private func fetchArchivePayload(
         originalGameID: UUID
     ) async -> Archive.Payload? {
         let recordID = CKRecord.ID(
             recordName: Archive.recordName(forOriginalGameID: originalGameID),
             zoneID: Archive.zoneID(forOriginalGameID: originalGameID)
         )
         guard let record = try? await container.privateCloudDatabase.record(for: recordID) else {
             return nil
         }
         return Archive.payload(from: record)
     }
 
     private func markArchived(originalGameID: UUID) {
         let ctx = persistence.container.newBackgroundContext()
         ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", originalGameID as CVarArg)
             req.fetchLimit = 1
             guard let entity = try? ctx.fetch(req).first else { return }
             entity.archivedAt = Date()
             entity.archiveGameID = Archive.archiveGameID(for: originalGameID)
             try? ctx.save()
         }
     }
 
     // MARK: - Promote on revocation
 
     /// Turns a revoked shared game into a durable, owned completed game, then
     /// deletes the revoked original so the library shows a single completed game
     /// rather than a dead tombstone.
     ///
     /// Prefers the cloud archive as the source: by the time an owner deletes,
     /// the reconcile sweep has usually converged it to the *full* multi-author
     /// log, whereas this device's local `JournalEntity` rows only hold its own
     /// moves plus any peers it happened to cache for replay. Falls back to the
     /// local data (and seeds a cloud copy from it) when the archive can't be
     /// reached — e.g. a game that completed and was revoked entirely offline.
     func promoteRevoked(gameID: UUID) async {
         let ctx = persistence.container.newBackgroundContext()
         let local: Archive.Snapshot? = ctx.performAndWait {
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             // Only finished games are archivable; an owner deleting an
             // in-progress shared game leaves the revoked tombstone as-is.
             guard (try? ctx.fetch(req).first)?.completedAt != nil else { return nil }
             return Archive.snapshot(forGameID: gameID, in: ctx)
         }
         guard let local else { return }
 
         let payload: Archive.Payload
         if let cloud = await fetchArchivePayload(originalGameID: gameID) {
             payload = cloud
         } else {
             // No reachable cloud copy — back up the local data now (the private
             // DB is still writable) and promote from it.
             await write(local, markComplete: true)
             payload = Archive.payload(from: local)
         }
 
         let promoteCtx = persistence.container.newBackgroundContext()
         promoteCtx.performAndWait {
             _ = Archive.materialize(payload, in: promoteCtx)
             let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
             req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
             req.fetchLimit = 1
             if let original = try? promoteCtx.fetch(req).first {
                 promoteCtx.delete(original)
             }
             if promoteCtx.hasChanges { try? promoteCtx.save() }
         }
     }
 
     // MARK: - CloudKit helpers
 
     private func ensureZone(_ zoneID: CKRecordZone.ID) async throws {
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             let op = CKModifyRecordZonesOperation(
                 recordZonesToSave: [CKRecordZone(zoneID: zoneID)],
                 recordZoneIDsToDelete: nil
             )
             op.qualityOfService = .utility
             op.modifyRecordZonesResultBlock = { result in cont.resume(with: result) }
             container.privateCloudDatabase.add(op)
         }
     }
 
     private func save(_ record: CKRecord) async throws {
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             let op = CKModifyRecordsOperation(recordsToSave: [record], recordIDsToDelete: nil)
             // Force-overwrite: each convergence pass writes a fresh record (no
             // change tag), and the archive is a frozen game, so last-writer-wins
             // across this user's own devices is exactly right.
             op.savePolicy = .allKeys
             op.qualityOfService = .utility
             op.modifyRecordsResultBlock = { result in cont.resume(with: result) }
             container.privateCloudDatabase.add(op)
         }
     }
 }