crossmate

ShareController.swift (14604B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Manages the lifecycle of `CKShare` objects for per-game zones. Responsible
 /// for creating zone-scoped shares and saving them to CloudKit, refreshing
 /// existing shares on re-present, and letting participants leave a shared game.
 @MainActor
 final class ShareController {
     private static let zoneWideShareRecordName = "cloudkit.zoneshare"
 
     let container: CKContainer
     private let persistence: PersistenceController
     private let syncEngine: SyncEngine
     private let syncMonitor: SyncMonitor?
 
     /// Fired after `persistShareName` has saved the local entity's
     /// `ckShareRecordName`, so dependent state (e.g. the open game's mutator
     /// `isShared` flag) can flip without waiting for the user to re-open.
     var onShareSaved: (@MainActor (UUID) -> Void)?
 
     enum ShareError: Error {
         case gameNotFound
         case invalidShareRecord
         case notAnOwner
         case invalidGameRecord
         case missingShareURL
     }
 
     init(
         container: CKContainer,
         persistence: PersistenceController,
         syncEngine: SyncEngine,
         syncMonitor: SyncMonitor? = nil
     ) {
         self.container = container
         self.persistence = persistence
         self.syncEngine = syncEngine
         self.syncMonitor = syncMonitor
     }
 
     /// Returns the `CKShare` and container for `UICloudSharingController`'s
     /// preparation handler. For a first-time share, the returned share is
     /// *unsaved* — `UICloudSharingController` saves it when the user submits
     /// participants. Call `persistShareName(_:for:)` from the controller's
     /// `didSaveShare` delegate callback to record the saved share's name.
     /// For an existing share, the saved share is fetched and returned.
     func prepareShare(for gameID: UUID) async throws -> (CKShare, CKContainer) {
         let share = try await prepareShareRecord(for: gameID, publicPermission: .none)
         return (share, container)
     }
 
     /// Creates or updates the game's CloudKit share as a public collaboration
     /// link and returns the generated URL. This avoids the participant
     /// management UI and lets Crossmate capture the CloudKit save error
     /// directly when link creation fails.
     func createShareLink(for gameID: UUID) async throws -> URL {
         syncMonitor?.recordStart("create share link")
         do {
             let share = try await prepareShareRecord(for: gameID, publicPermission: .readWrite)
             let savedShare: CKShare
             do {
                 savedShare = try await saveShareForLink(share, for: gameID)
             } catch let error as CKError where error.code == .serverRecordChanged {
                 savedShare = try await recoverShareLinkAfterSaveConflict(error, for: gameID)
             }
             let url = try shareURL(from: savedShare)
             syncMonitor?.note("share link created for \(gameID.uuidString): \(url.absoluteString)")
             syncMonitor?.recordSuccess("create share link")
             return url
         } catch {
             syncMonitor?.recordError("create share link", error)
             throw error
         }
     }
 
     /// Returns the saved public share URL for a game, if Crossmate already
     /// knows about its `CKShare`. Stale local share references are cleared so
     /// the caller can safely offer to create a fresh link.
     func existingShareLink(for gameID: UUID) async throws -> URL? {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
         guard entity.databaseScope == 0 else {
             throw ShareError.notAnOwner
         }
         guard let existingName = entity.ckShareRecordName else {
             let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
             do {
                 let share = try await fetchExistingShare(
                     recordName: Self.zoneWideShareRecordName,
                     zoneName: zoneName
                 )
                 entity.ckShareRecordName = share.recordID.recordName
                 try ctx.save()
                 return share.url
             } catch let error as CKError where isMissingShare(error) {
                 return nil
             }
         }
 
         do {
             let share = try await fetchExistingShare(
                 recordName: existingName,
                 zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
             )
             return share.url
         } catch let error as CKError where error.code == .unknownItem {
             entity.ckShareRecordName = nil
             try ctx.save()
             return nil
         }
     }
 
     private func prepareShareRecord(
         for gameID: UUID,
         publicPermission: CKShare.ParticipantPermission
     ) async throws -> CKShare {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
         guard entity.databaseScope == 0 else {
             throw ShareError.notAnOwner
         }
 
         if let existingName = entity.ckShareRecordName {
             do {
                 let existing = try await fetchExistingShare(
                     recordName: existingName,
                     zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
                 )
                 return configureShare(existing, title: entity.title, publicPermission: publicPermission)
             } catch let error as CKError where error.code == .unknownItem {
                 entity.ckShareRecordName = nil
                 try ctx.save()
             }
         }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: CKCurrentUserDefaultName)
 
         // Create the zone directly rather than going through CKSyncEngine.sendChanges(),
         // which can block on post-reset state (stale tokens, in-flight operations).
         // Zone creation is idempotent so this is safe even if the engine already created it.
         try await withCheckedThrowingContinuation { (cont: CheckedContinuation<Void, Error>) in
             let op = CKModifyRecordZonesOperation(
                 recordZonesToSave: [CKRecordZone(zoneID: zoneID)],
                 recordZoneIDsToDelete: nil
             )
             op.qualityOfService = .userInitiated
             op.modifyRecordZonesResultBlock = { result in cont.resume(with: result) }
             self.container.privateCloudDatabase.add(op)
         }
 
         if let existing = try await fetchZoneWideShareIfPresent(zoneName: zoneName) {
             entity.ckShareRecordName = existing.recordID.recordName
             try ctx.save()
             return configureShare(existing, title: entity.title, publicPermission: publicPermission)
         }
 
         try await ensureGameRecordExists(for: entity, in: zoneID)
 
         let share = CKShare(recordZoneID: zoneID)
         return configureShare(share, title: entity.title, publicPermission: publicPermission)
     }
 
     /// Records the share's CloudKit record name on the local entity so future
     /// invocations of `prepareShare` fetch the existing share. Also enqueues a
     /// Game record push so other owner-devices receive the share marker via
     /// `RecordSerializer.applyGameRecord` and flip their `isShared` flag.
     /// Idempotent.
     func persistShareName(_ recordName: String, for gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else { return }
         guard entity.ckShareRecordName != recordName else { return }
         entity.ckShareRecordName = recordName
         try ctx.save()
         if let ckRecordName = entity.ckRecordName {
             await syncEngine.enqueueGame(ckRecordName: ckRecordName)
         }
         onShareSaved?(gameID)
     }
 
     /// Removes the current user's participation from a shared game and deletes
     /// the local entity. No-ops if the game is not a shared (participant) game.
     func leaveShare(gameID: UUID) async throws {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first,
               entity.databaseScope == 1 else { return }
 
         let zoneName = entity.ckZoneName ?? "game-\(gameID.uuidString)"
         let ownerName = entity.ckZoneOwnerName ?? CKCurrentUserDefaultName
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: ownerName)
         let shareID = CKRecord.ID(recordName: Self.zoneWideShareRecordName, zoneID: zoneID)
 
         // A participant leaves a zone-wide share by deleting the CKShare record
         // from the shared database; deleting the zone itself is rejected with
         // "Zone delete not allowed".
         do {
             try await container.sharedCloudDatabase.deleteRecord(withID: shareID)
         } catch let error as CKError where error.code == .unknownItem || error.code == .zoneNotFound {
             // Already gone — proceed to clean up local state.
         }
 
         ctx.delete(entity)
         try ctx.save()
     }
 
     // MARK: - Helpers
 
     private func fetchExistingShare(
         recordName: String,
         zoneName: String
     ) async throws -> CKShare {
         let zoneID = CKRecordZone.ID(zoneName: zoneName, ownerName: CKCurrentUserDefaultName)
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
         let record = try await container.privateCloudDatabase.record(for: recordID)
         guard let share = record as? CKShare else {
             throw ShareError.invalidShareRecord
         }
         return share
     }
 
     private func fetchZoneWideShareIfPresent(zoneName: String) async throws -> CKShare? {
         do {
             return try await fetchExistingShare(
                 recordName: Self.zoneWideShareRecordName,
                 zoneName: zoneName
             )
         } catch let error as CKError where isMissingShare(error) {
             return nil
         }
     }
 
     private func isMissingShare(_ error: CKError) -> Bool {
         error.code == .unknownItem || error.code == .zoneNotFound
     }
 
     @discardableResult
     private func configureShare(
         _ share: CKShare,
         title: String?,
         publicPermission: CKShare.ParticipantPermission
     ) -> CKShare {
         share.publicPermission = publicPermission
         share[CKShare.SystemFieldKey.title] = title as CKRecordValue?
         return share
     }
 
     private func saveShareForLink(_ share: CKShare, for gameID: UUID) async throws -> CKShare {
         let savedRecord = try await container.privateCloudDatabase.save(share)
         guard let savedShare = savedRecord as? CKShare else {
             throw ShareError.invalidShareRecord
         }
         try await persistShareName(savedShare.recordID.recordName, for: gameID)
         return savedShare
     }
 
     private func shareURL(from share: CKShare) throws -> URL {
         guard let url = share.url else {
             throw ShareError.missingShareURL
         }
         return url
     }
 
     private func recoverShareLinkAfterSaveConflict(
         _ error: CKError,
         for gameID: UUID
     ) async throws -> CKShare {
         let ctx = persistence.viewContext
         let request = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         request.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
         request.fetchLimit = 1
         guard let entity = try ctx.fetch(request).first else {
             throw ShareError.gameNotFound
         }
 
         let share: CKShare
         if let serverShare = (error as NSError).userInfo[CKRecordChangedErrorServerRecordKey] as? CKShare {
             share = serverShare
         } else {
             share = try await fetchExistingShare(
                 recordName: Self.zoneWideShareRecordName,
                 zoneName: entity.ckZoneName ?? "game-\(gameID.uuidString)"
             )
         }
 
         configureShare(share, title: entity.title, publicPermission: .readWrite)
         return try await saveShareForLink(share, for: gameID)
     }
 
     /// CloudKit requires the initial records covered by a new share to already
     /// exist on the server or be saved with the share. `CKShareTransferRepresentation`
     /// only returns the share, so save the root game record before handing the
     /// zone-wide share to the system UI.
     private func ensureGameRecordExists(
         for entity: GameEntity,
         in zoneID: CKRecordZone.ID
     ) async throws {
         guard let recordName = entity.ckRecordName else {
             throw ShareError.invalidGameRecord
         }
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
         let record: CKRecord
         let includePuzzleSource: Bool
 
         do {
             record = try await container.privateCloudDatabase.record(for: recordID)
             includePuzzleSource = record["puzzleSource"] == nil
         } catch let error as CKError where error.code == .unknownItem {
             guard let newRecord = RecordSerializer.gameRecord(
                 from: entity,
                 recordID: recordID,
                 includePuzzleSource: true
             ) else {
                 throw ShareError.invalidGameRecord
             }
             record = newRecord
             includePuzzleSource = true
         }
 
         RecordSerializer.populateGameRecord(
             record,
             from: entity,
             includePuzzleSource: includePuzzleSource
         )
         let saved = try await container.privateCloudDatabase.save(record)
         entity.ckSystemFields = RecordSerializer.encodeSystemFields(of: saved)
         entity.lastSyncedAt = Date()
         if entity.ckZoneName == nil {
             entity.ckZoneName = zoneID.zoneName
         }
         try persistence.viewContext.save()
     }
 }