crossmate

CloudService.swift (20855B)

---

 import CloudKit
 
 enum CloudFailureCopy {
     static let quotaJoinTitle = "Puzzle Unavailable"
     static let quotaJoinBody =
         "The puzzle could not be joined properly. This could be because your friend's iCloud storage is full."
 
     /// Banner copy for a failed join, shared by the three surfaces that can
     /// raise one (share link, invite row, OS-delivered acceptance) so they can't
     /// drift apart. An `AcceptedShareError` means the share itself went
     /// through and only its puzzle is unusable — a different thing to tell the
     /// user than failing to accept at all — and a quota failure names the
     /// likely cause instead of echoing CloudKit's wording.
     static func joinFailure(for error: Error) -> (title: String, body: String) {
         guard let accepted = error as? AcceptedShareError else {
             return ("Accepting Failed", error.localizedDescription)
         }
         guard accepted.isQuotaExceeded else {
             return ("Puzzle Unavailable", error.localizedDescription)
         }
         return (quotaJoinTitle, quotaJoinBody)
     }
 }
 
 extension Notification.Name {
     static let cloudShareAcceptanceStarted = Notification.Name("cloudShareAcceptanceStarted")
     static let cloudShareAcceptanceCompleted = Notification.Name("cloudShareAcceptanceCompleted")
 }
 
 /// Errors from `CloudService` that need distinct user-facing handling.
 enum CloudServiceError: Error, LocalizedError, Equatable {
     /// A tapped share belongs to a different CloudKit container generation than
     /// this build uses — the sharer and joiner are on incompatible app versions
     /// (e.g. a not-yet-updated peer taps a link to a v4 game, or vice versa).
     case containerVersionMismatch
 
     var errorDescription: String? {
         switch self {
         case .containerVersionMismatch:
             return "This game is from a different version of Crossmate. "
                 + "Make sure you and the other player are both on the latest version."
         }
     }
 }
 
 /// The share itself was accepted, but Crossmate could not materialize its
 /// playable Game record. Keeping this distinct from an acceptance failure lets
 /// callers tell the truth: retrying does not need to accept the share again.
 struct AcceptedShareError: Error, LocalizedError {
     enum Kind: Equatable {
         case removed
         case temporarilyUnavailable
         case unavailable
     }
 
     let kind: Kind
     let underlyingError: Error
 
     var errorDescription: String? {
         if isQuotaExceeded { return CloudFailureCopy.quotaJoinBody }
         return underlyingError.localizedDescription
     }
 
     var isQuotaExceeded: Bool {
         CloudService.cloudErrorCode(underlyingError) == .quotaExceeded
     }
 }
 
 @MainActor
 final class CloudService {
     private let ckContainer: CKContainer
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor
     private let store: GameStore
     private let shareController: ShareController
 
     /// Fired after a successful share acceptance once the shared zone has been
     /// fetched. Used to enqueue a `.join` ping so other collaborators are
     /// notified that someone has joined the puzzle.
     var onShareJoined: ((UUID) async -> Void)?
 
     init(
         container: CKContainer,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor,
         store: GameStore,
         shareController: ShareController
     ) {
         self.ckContainer = container
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
         self.store = store
         self.shareController = shareController
     }
 
     /// The result of accepting a share, so callers can react to a join that
     /// succeeded at the CloudKit level but hasn't produced a playable puzzle
     /// yet. Navigation is still driven by `.cloudShareAcceptanceCompleted`; this
     /// only lets a caller surface a "still syncing" message where appropriate.
     enum AcceptOutcome {
         /// A playable puzzle was joined; navigation has been posted.
         case opened
         /// The share was accepted but its puzzle hadn't synced before the wait
         /// timed out. The game still surfaces in the Game List once sync
         /// settles, so callers may reassure the user rather than report failure.
         case pendingSync
         /// The user cancelled the join (only the link tap can); no message.
         case cancelled
     }
 
     /// Fetches share metadata for a URL and joins via `acceptShare(metadata:)`.
     /// Used by the "Invited" section and the universal-link tap, where the
     /// share URL arrived in an `.invite` Ping or a tapped link rather than from
     /// the OS share-accept handler.
     @discardableResult
     func acceptShare(
         url: URL,
         prefetchedPuzzleSource: String? = nil,
         prefetchedNotification: String? = nil
     ) async throws -> AcceptOutcome {
         let metadata = try await withCheckedThrowingContinuation {
             (cont: CheckedContinuation<CKShare.Metadata, Error>) in
             var found: CKShare.Metadata?
             let op = CKFetchShareMetadataOperation(shareURLs: [url])
             op.shouldFetchRootRecord = false
             op.perShareMetadataResultBlock = { _, result in
                 if case .success(let m) = result { found = m }
             }
             op.fetchShareMetadataResultBlock = { result in
                 switch result {
                 case .success:
                     if let found {
                         cont.resume(returning: found)
                     } else {
                         cont.resume(throwing: CKError(.unknownItem))
                     }
                 case .failure(let error):
                     cont.resume(throwing: error)
                 }
             }
             ckContainer.add(op)
         }
         return try await acceptShare(
             metadata: metadata,
             prefetchedPuzzleSource: prefetchedPuzzleSource,
             prefetchedNotification: prefetchedNotification
         )
     }
 
     @discardableResult
     func acceptShare(
         metadata: CKShare.Metadata,
         prefetchedPuzzleSource: String? = nil,
         prefetchedNotification: String? = nil
     ) async throws -> AcceptOutcome {
         NotificationCenter.default.post(name: .cloudShareAcceptanceStarted, object: nil)
 
         guard metadata.containerIdentifier == ckContainer.containerIdentifier else {
             syncMonitor.note(
                 "acceptShare: container mismatch — metadata=\(metadata.containerIdentifier) " +
                 "expected=\(ckContainer.containerIdentifier ?? "nil")"
             )
             throw CloudServiceError.containerVersionMismatch
         }
         // The share names the game it covers: Crossmate uses zone-wide shares,
         // so the metadata's zone ("game-<UUID>") identifies the game outright.
         // This replaces a fragile before/after join diff that came up empty
         // whenever the game was already present — a re-tapped link, a sibling
         // device, or a directly-invited friend added by identity before Accept.
         let sharedZoneID = metadata.share.recordID.zoneID
         let sharedGameID = RecordSerializer.gameID(
             fromGameRecordName: sharedZoneID.zoneName
         )
         var shareWasAccepted = false
         do {
             try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
                 let op = CKAcceptSharesOperation(shareMetadatas: [metadata])
                 op.acceptSharesResultBlock = { result in cont.resume(with: result) }
                 ckContainer.add(op)
             }
             shareWasAccepted = true
             if let sharedGameID {
                 // When the invite carried the puzzle source, build the playable
                 // game from it now and pull the canonical Game record, Moves and
                 // Players in the background — they merge into this same row
                 // (matched by record name) as a pure update. The user reaches
                 // the grid after just the accept round-trip rather than waiting
                 // on the shared-zone fetch.
                 var constructed = false
                 if let prefetchedPuzzleSource, !prefetchedPuzzleSource.isEmpty {
                     do {
                         try store.constructJoinedGame(
                             gameID: sharedGameID,
                             zoneID: sharedZoneID,
                             source: prefetchedPuzzleSource,
                             notification: prefetchedNotification
                         )
                         constructed = true
                         syncMonitor.note("Share accepted — built game from invite; fetching remainder in background")
                     } catch {
                         syncMonitor.note("acceptShare: invite-source construct failed — \(error); fetching inline")
                     }
                 }
                 if constructed {
                     Task { @MainActor [weak self] in
                         guard let self else { return }
                         _ = await self.syncMonitor.run("share-accept background remainder fetch") {
                             try await self.syncEngine.fetchAcceptedSharedGameDirect(
                                 gameID: sharedGameID,
                                 zoneID: sharedZoneID
                             )
                         }
                     }
                 } else {
                     syncMonitor.note("Share accepted — fetching shared game")
                     do {
                         _ = try await syncEngine.fetchAcceptedSharedGameDirect(
                             gameID: sharedGameID,
                             zoneID: sharedZoneID
                         )
                     } catch {
                         guard Self.isRetryableJoinError(error) else { throw error }
                         syncMonitor.note(
                             "acceptShare: initial shared-game fetch will retry — " +
                             Self.describeCloudError(error)
                         )
                     }
                 }
             } else {
                 syncMonitor.note("Share accepted — discovering shared zone")
                 await syncMonitor.run("share-accept shared discovery") {
                     _ = try await syncEngine.discoverNewZonesDirect(scope: .shared)
                 }
             }
             // Navigate once the game's puzzle has actually synced and is
             // playable. The caller holds the join placeholder up for the whole
             // of this call, so waiting here keeps the user on the joining screen
             // through a slow sync rather than dropping them back at the Game
             // List with an unopened game.
             let joinedGameID = try await waitForPlayablePuzzle(
                 gameID: sharedGameID,
                 zoneID: sharedZoneID
             )
             // The user tapped Cancel on the joining screen — don't pull them
             // into the game. The joined zone still surfaces in the Game List on
             // its own once sync settles.
             guard !Task.isCancelled else { return .cancelled }
             if let joinedGameID {
                 try await shareController.confirmSeatAfterJoin(gameID: joinedGameID)
             }
             NotificationCenter.default.post(
                 name: .cloudShareAcceptanceCompleted,
                 object: nil,
                 userInfo: joinedGameID.map { ["gameID": $0] }
             )
             if let joinedGameID, let onShareJoined {
                 await onShareJoined(joinedGameID)
             }
             return joinedGameID == nil ? .pendingSync : .opened
         } catch {
             syncMonitor.recordError("acceptShare", error)
             if shareWasAccepted, !(error is AcceptedShareError) {
                 throw AcceptedShareError(
                     kind: Self.joinFailureKind(for: error),
                     underlyingError: error
                 )
             }
             throw error
         }
     }
 
     /// How long `acceptShare` holds the joining screen waiting for the puzzle to
     /// become playable before returning the user to the Game List. Mirrors
     /// `RootView`'s invite-ping join wait.
     private static let joinSyncTimeout: TimeInterval = 30
     private static let joinSyncPollInterval: Duration = .seconds(1)
     /// How often `waitForPlayablePuzzle` re-issues the CloudKit fetch while
     /// waiting. Between backstops it only observes the store, which the initial
     /// accepted-game fetch (and concurrent sync) populate — so a slow asset
     /// commit costs cheap store polls, not repeated three-query CloudKit reads.
     private static let joinSyncRefetchInterval: TimeInterval = 3
 
     /// Polls the just-joined game's own zone until its puzzle is playable, so
     /// the joining screen holds through a slow sync rather than dropping the
     /// user back at the Game List. The accepted-zone fetch downloads the Game
     /// record and its `puzzleSource` asset inline, so this returns on the first
     /// check in the common case. Returns nil on timeout, or when the join
     /// `Task` is cancelled (the user tapped Cancel) — the caller then doesn't
     /// navigate.
     private func waitForPlayablePuzzle(
         gameID: UUID?,
         zoneID: CKRecordZone.ID?
     ) async throws -> UUID? {
         guard let gameID else { return nil }
         if store.joinedSharedGameIDs().contains(gameID) { return gameID }
         let deadline = Date().addingTimeInterval(Self.joinSyncTimeout)
         // The caller already issued one accepted-game fetch, so begin by just
         // observing the store and only re-issue the CloudKit fetch on a backstop
         // interval. In the common case the asset commits within a poll or two
         // and we return without a single redundant three-query read.
         var nextRefetch = Date().addingTimeInterval(Self.joinSyncRefetchInterval)
         var lastRetryableError: Error?
         while Date() < deadline {
             if store.joinedSharedGameIDs().contains(gameID) { return gameID }
 
             if Date() >= nextRefetch {
                 if let zoneID {
                     // The gate only reads `puzzleSource`, so the backstop needs
                     // just the Game record — the initial accept fetch already
                     // pulled Moves/Players, and the grid re-fetches them on open.
                     do {
                         _ = try await syncEngine.fetchAcceptedSharedGameDirect(
                             gameID: gameID,
                             zoneID: zoneID,
                             onlyGame: true
                         )
                         lastRetryableError = nil
                     } catch {
                         guard Self.isRetryableJoinError(error) else { throw error }
                         lastRetryableError = error
                     }
                 } else {
                     do {
                         _ = try await syncEngine.fetchGameDirect(
                             scope: .shared,
                             gameID: gameID
                         )
                         lastRetryableError = nil
                     } catch {
                         guard Self.isRetryableJoinError(error) else { throw error }
                         lastRetryableError = error
                     }
                 }
                 let retryAfter = lastRetryableError.flatMap(Self.retryAfter)
                 nextRefetch = Date().addingTimeInterval(
                     max(Self.joinSyncRefetchInterval, retryAfter ?? 0)
                 )
                 if store.joinedSharedGameIDs().contains(gameID) { return gameID }
             }
 
             do {
                 try await Task.sleep(for: Self.joinSyncPollInterval)
             } catch {
                 return nil // cancelled
             }
         }
         syncMonitor.note(
             "acceptShare: puzzle not playable within \(Int(Self.joinSyncTimeout))s " +
             "for \(gameID.uuidString)"
         )
         if let lastRetryableError { throw lastRetryableError }
         return nil
     }
 
     nonisolated static func joinFailureKind(for error: Error) -> AcceptedShareError.Kind {
         let code = cloudErrorCode(error)
         if code == .unknownItem || code == .zoneNotFound || code == .userDeletedZone {
             return .removed
         }
         return isRetryableJoinError(error) ? .temporarilyUnavailable : .unavailable
     }
 
     nonisolated static func isRetryableJoinError(_ error: Error) -> Bool {
         switch cloudErrorCode(error) {
         case .internalError,
              .networkUnavailable,
              .networkFailure,
              .serviceUnavailable,
              .requestRateLimited,
              .zoneBusy,
              .operationCancelled,
              .serverResponseLost,
              .accountTemporarilyUnavailable:
             return true
         default:
             return false
         }
     }
 
     nonisolated static func retryAfter(_ error: Error) -> TimeInterval? {
         let value = (unwrappedCloudError(error) as NSError)
             .userInfo[CKErrorRetryAfterKey]
         if let number = value as? NSNumber { return max(0, number.doubleValue) }
         if let interval = value as? TimeInterval { return max(0, interval) }
         return nil
     }
 
     nonisolated static func cloudErrorCode(_ error: Error) -> CKError.Code? {
         let nsError = unwrappedCloudError(error) as NSError
         guard nsError.domain == CKErrorDomain else { return nil }
         return CKError.Code(rawValue: nsError.code)
     }
 
     nonisolated private static func unwrappedCloudError(_ error: Error) -> Error {
         if let accepted = error as? AcceptedShareError {
             return unwrappedCloudError(accepted.underlyingError)
         }
         return error
     }
 
     nonisolated private static func describeCloudError(_ error: Error) -> String {
         let nsError = unwrappedCloudError(error) as NSError
         let retry = retryAfter(error).map { " retryAfter=\($0)s" } ?? ""
         return "domain=\(nsError.domain) code=\(nsError.code)\(retry) " +
             nsError.localizedDescription
     }
 
     func resetAllData() async throws {
         await syncEngine.resetSyncState()
 
         async let privateCleanup: Void = deleteAllPrivateZones()
         async let sharedCleanup: Void = leaveAllSharedZones()
         _ = await (privateCleanup, sharedCleanup)
 
         try store.resetAllData()
         UserDefaults.standard.removeObject(forKey: "gamePlayerColors")
         BadgeState.reset()
         syncMonitor.note("Database reset — all games and sync state cleared")
     }
 
     /// Local-only counterpart to `resetAllData`, used on an iCloud account
     /// switch. Drops this device's cached store, badge ledger, colour map, and
     /// sync-engine tokens, then rebuilds the engines so they resync as the new
     /// account. Critically it does **not** delete private zones or leave shared
     /// zones: the previous account's games stay intact in *its* CloudKit (the
     /// user still has them on other devices) — only this device's stale cache
     /// of them is discarded. The store is wiped before `resetSyncState` so the
     /// latter's unconfirmed-move recovery finds nothing to re-enqueue.
     func purgeLocalData() async throws {
         try store.resetAllData()
         UserDefaults.standard.removeObject(forKey: "gamePlayerColors")
         BadgeState.reset()
         await syncEngine.resetSyncState()
         syncMonitor.note("Local store purged for account switch — previous account untouched in CloudKit")
     }
 
     private func deleteAllPrivateZones() async {
         do {
             let zones = try await ckContainer.privateCloudDatabase.allRecordZones()
             guard !zones.isEmpty else { return }
             let ids = zones.map(\.zoneID)
             try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
                 let op = CKModifyRecordZonesOperation(
                     recordZonesToSave: nil,
                     recordZoneIDsToDelete: ids
                 )
                 op.modifyRecordZonesResultBlock = { result in cont.resume(with: result) }
                 ckContainer.privateCloudDatabase.add(op)
             }
         } catch {
             syncMonitor.note("reset: private zone cleanup failed — \(error)")
         }
     }
 
     private func leaveAllSharedZones() async {
         do {
             let zones = try await ckContainer.sharedCloudDatabase.allRecordZones()
             for zone in zones {
                 try await ckContainer.sharedCloudDatabase.deleteRecordZone(withID: zone.zoneID)
             }
         } catch {
             syncMonitor.note("reset: shared zone cleanup failed — \(error)")
         }
     }
 }