crossmate

RecordSerializer.swift (19521B)

---

 import CloudKit
 import CoreData
 import Foundation
 
 /// Pure-function helpers for converting between the app's Core Data / in-memory
 /// models and CloudKit `CKRecord` objects. Stateless — all context is passed in.
 enum RecordSerializer {
 
     // MARK: - Device identity
 
     /// A stable per-device identifier appended to move and snapshot record
     /// names to prevent two devices owned by the same iCloud user from
     /// producing identical record names when both assign the same Lamport
     /// clock value while offline.
     ///
     /// Stored in UserDefaults so it survives app restarts but resets on
     /// reinstall (which is fine — a reinstalled app has no local moves to
     /// conflict with).
     static let localDeviceID: String = {
         let key = "crossmate.localDeviceID"
         if let stored = UserDefaults.standard.string(forKey: key) {
             return stored
         }
         let new = UUID().uuidString.replacingOccurrences(of: "-", with: "").lowercased()
         UserDefaults.standard.set(new, forKey: key)
         return new
     }()
 
     // MARK: - Record names
 
     static func recordName(forGameID gameID: UUID) -> String {
         "game-\(gameID.uuidString)"
     }
 
     /// One Moves record per `(game, authorID, deviceID)`. Each device only
     /// writes to its own slot, so there are no write-write conflicts on the
     /// `cells` field.
     static func recordName(
         forMovesInGame gameID: UUID,
         authorID: String,
         deviceID: String
     ) -> String {
         "moves-\(gameID.uuidString)-\(authorID)-\(deviceID)"
     }
 
     /// One player record per (game, author). Each participant only ever
     /// writes to their own slot, so there are no write-write conflicts on
     /// the field.
     static func recordName(forPlayerInGame gameID: UUID, authorID: String) -> String {
         "player-\(gameID.uuidString)-\(authorID)"
     }
 
     /// One Ping record per event. The event timestamp (ms since epoch) makes
     /// the name unique across events and devices, so repeated pings from the
     /// same author for the same game don't collide.
     static func recordName(
         forPingInGame gameID: UUID,
         authorID: String,
         eventTimestampMs: Int64
     ) -> String {
         "ping-\(gameID.uuidString)-\(authorID)-\(eventTimestampMs)"
     }
 
     // MARK: - Zone
 
     /// Zone ID for a per-game zone. `ownerName` defaults to the current user
     /// placeholder; pass an explicit value for shared games where the zone is
     /// owned by another iCloud account.
     static func zoneID(
         for gameID: UUID,
         ownerName: String = CKCurrentUserDefaultName
     ) -> CKRecordZone.ID {
         CKRecordZone.ID(zoneName: "game-\(gameID.uuidString)", ownerName: ownerName)
     }
 
     // MARK: - Moves record building
 
     static func movesRecord(
         from view: MovesValue,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) throws -> CKRecord {
         let movesName = recordName(
             forMovesInGame: view.gameID,
             authorID: view.authorID,
             deviceID: view.deviceID
         )
         let record = restoreOrCreate(
             recordType: "Moves",
             recordName: movesName,
             zone: zone,
             systemFields: systemFields
         )
 
         record["authorID"] = view.authorID as CKRecordValue
         record["deviceID"] = view.deviceID as CKRecordValue
         record["updatedAt"] = view.updatedAt as CKRecordValue
         record["cells"] = try MovesCodec.encode(view.cells) as CKRecordValue
 
         return record
     }
 
     static func gameRecord(
         from entity: GameEntity,
         recordID: CKRecord.ID,
         includePuzzleSource: Bool
     ) -> CKRecord? {
         guard entity.ckRecordName != nil else { return nil }
         let record: CKRecord
         if let fields = entity.ckSystemFields,
            let restored = decodeRecord(from: fields) {
             record = restored
         } else {
             record = CKRecord(recordType: "Game", recordID: recordID)
         }
         populateGameRecord(record, from: entity, includePuzzleSource: includePuzzleSource)
         return record
     }
 
     static func populateGameRecord(
         _ record: CKRecord,
         from entity: GameEntity,
         includePuzzleSource: Bool
     ) {
         record["title"] = entity.title as CKRecordValue?
         record["completedAt"] = entity.completedAt as CKRecordValue?
         // Owner-side share marker. Propagated so other owner-devices can flip
         // their `isShared` flag without reading the zone's CKShare directly.
         record["shareRecordName"] = entity.ckShareRecordName as CKRecordValue?
         guard includePuzzleSource, let source = entity.puzzleSource else { return }
         let url = FileManager.default.temporaryDirectory
             .appendingPathComponent(UUID().uuidString)
             .appendingPathExtension("xd")
         try? source.write(to: url, atomically: true, encoding: .utf8)
         record["puzzleSource"] = CKAsset(fileURL: url)
     }
 
     /// Builds a freshly-minted Ping record. Pings are write-once — they have
     /// no Core Data equivalent and no system-fields archive.
     /// - `authorID` lets receivers filter out self-sends.
     /// - `playerName` and `puzzleTitle` let receivers render the alert body.
     /// - `kind` distinguishes session/join/win/check/reveal events.
     /// - `scope` is set only for check/reveal kinds.
     static func pingRecord(
         gameID: UUID,
         authorID: String,
         playerName: String,
         puzzleTitle: String,
         eventTimestampMs: Int64,
         kind: PingKind,
         scope: PingScope?,
         zone: CKRecordZone.ID
     ) -> CKRecord {
         let name = recordName(
             forPingInGame: gameID,
             authorID: authorID,
             eventTimestampMs: eventTimestampMs
         )
         let recordID = CKRecord.ID(recordName: name, zoneID: zone)
         let record = CKRecord(recordType: "Ping", recordID: recordID)
         record["authorID"] = authorID as CKRecordValue
         record["playerName"] = playerName as CKRecordValue
         record["puzzleTitle"] = puzzleTitle as CKRecordValue
         record["kind"] = kind.rawValue as CKRecordValue
         if let scope {
             record["scope"] = scope.rawValue as CKRecordValue
         }
         return record
     }
 
     static func playerRecord(
         gameID: UUID,
         authorID: String,
         name: String,
         updatedAt: Date,
         selection: PlayerSelection?,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) -> CKRecord {
         let recordName = recordName(forPlayerInGame: gameID, authorID: authorID)
         let record = restoreOrCreate(
             recordType: "Player",
             recordName: recordName,
             zone: zone,
             systemFields: systemFields
         )
 
         record["authorID"] = authorID as CKRecordValue
         record["name"] = name as CKRecordValue
         record["updatedAt"] = updatedAt as CKRecordValue
         if let selection {
             record["selRow"] = Int64(selection.row) as CKRecordValue
             record["selCol"] = Int64(selection.col) as CKRecordValue
             record["selDir"] = Int64(selection.direction.rawValue) as CKRecordValue
         } else {
             record["selRow"] = nil
             record["selCol"] = nil
             record["selDir"] = nil
         }
 
         return record
     }
 
     /// Reads `selRow`/`selCol`/`selDir` off an inbound Player record. Returns
     /// `nil` if any field is missing — the peer either hasn't published a
     /// selection yet or has cleared theirs (e.g. left the puzzle view).
     static func parsePlayerSelection(from record: CKRecord) -> PlayerSelection? {
         guard let row = record["selRow"] as? Int64,
               let col = record["selCol"] as? Int64,
               let dirRaw = record["selDir"] as? Int64,
               let direction = PlayerSelection.Direction(rawValue: Int(dirRaw))
         else { return nil }
         return PlayerSelection(row: Int(row), col: Int(col), direction: direction)
     }
 
     /// Parses an incoming `Player` record name back into its `(gameID,
     /// authorID)` components. Returns `nil` if the name doesn't match the
     /// `player-<UUID>-<authorID>` shape.
     static func parsePlayerRecordName(_ name: String) -> (UUID, String)? {
         guard name.hasPrefix("player-") else { return nil }
         let rest = name.dropFirst("player-".count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let authorPart = String(rest.suffix(from: rest.index(rest.startIndex, offsetBy: uuidLength + 1)))
         guard !authorPart.isEmpty else { return nil }
         return (gameID, authorPart)
     }
 
     /// Parses an incoming `Moves` CKRecord into a `MovesValue`. Returns `nil`
     /// if the record name doesn't match the `moves-<gameUUID>-<authorID>-<deviceID>`
     /// shape or the cells payload fails to decode.
     static func parseMovesRecord(_ record: CKRecord) -> MovesValue? {
         guard record.recordType == "Moves" else { return nil }
         guard let (gameID, authorID, deviceID) = parseMovesRecordName(
             record.recordID.recordName
         ) else { return nil }
         guard let data = record["cells"] as? Data,
               let cells = try? MovesCodec.decode(data)
         else { return nil }
         let updatedAt = record["updatedAt"] as? Date
             ?? record.modificationDate
             ?? Date()
         return MovesValue(
             gameID: gameID,
             authorID: authorID,
             deviceID: deviceID,
             cells: cells,
             updatedAt: updatedAt
         )
     }
 
     /// Parses `moves-<gameUUID>-<authorID>-<deviceID>` into its three parts.
     /// `deviceID` is the suffix after the final `-`; `authorID` may itself
     /// contain dashes (e.g. CloudKit user record names with no dashes today,
     /// but we don't want to assume).
     static func parseMovesRecordName(_ name: String) -> (UUID, String, String)? {
         let prefix = "moves-"
         guard name.hasPrefix(prefix) else { return nil }
         let rest = name.dropFirst(prefix.count)
         let uuidLength = 36
         guard rest.count > uuidLength,
               rest[rest.index(rest.startIndex, offsetBy: uuidLength)] == "-"
         else { return nil }
         let uuidPart = String(rest[rest.startIndex..<rest.index(rest.startIndex, offsetBy: uuidLength)])
         guard let gameID = UUID(uuidString: uuidPart) else { return nil }
         let afterUUID = rest.index(rest.startIndex, offsetBy: uuidLength + 1)
         let tail = rest[afterUUID...]
         guard let lastDash = tail.lastIndex(of: "-") else { return nil }
         let authorID = String(tail[tail.startIndex..<lastDash])
         let deviceID = String(tail[tail.index(after: lastDash)...])
         guard !authorID.isEmpty, !deviceID.isEmpty else { return nil }
         return (gameID, authorID, deviceID)
     }
 
     // MARK: - Applying incoming CKRecords to Core Data
 
     /// Returns the `GameEntity` for `gameID`, creating an unpopulated stub if
     /// none exists yet. Moves and Player records can arrive in a different
     /// fetch batch than the Game record that created the zone — on
     /// a fresh device CKSyncEngine paginates the initial pull and there is no
     /// guarantee that Game comes first. Without this stub the parent lookup
     /// fails, the inbound record is dropped, but CKSyncEngine still advances
     /// its change token, so the gap is invisible until the next state reset.
     /// The stub uses empty `title` / `puzzleSource` so `GameSummary.init?`
     /// filters it out of the library until `applyGameRecord` arrives with
     /// the real metadata and updates the same row (matched by `ckRecordName`).
     static func ensureGameEntity(
         forGameID gameID: UUID,
         zoneID: CKRecordZone.ID,
         in ctx: NSManagedObjectContext
     ) -> GameEntity {
         let name = recordName(forGameID: gameID)
         let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", name)
         req.fetchLimit = 1
         if let existing = try? ctx.fetch(req).first { return existing }
         let entity = GameEntity(context: ctx)
         entity.id = gameID
         entity.ckRecordName = name
         entity.ckZoneName = zoneID.zoneName
         let ownerName = zoneID.ownerName
         let isOwner = ownerName == CKCurrentUserDefaultName
         entity.ckZoneOwnerName = isOwner ? nil : ownerName
         entity.databaseScope = isOwner ? 0 : 1
         entity.title = ""
         entity.puzzleSource = ""
         entity.createdAt = Date()
         entity.updatedAt = Date()
         return entity
     }
 
     static func applyGameRecord(
         _ record: CKRecord,
         to context: NSManagedObjectContext,
         databaseScope: Int16 = 0
     ) -> GameEntity {
         let recordName = record.recordID.recordName
         let entity = fetchOrCreate(
             entityName: "GameEntity",
             recordName: recordName,
             in: context
         ) as! GameEntity
 
         // Recover the UUID from the record name ("game-<UUID>") so the
         // library query, which filters on `entity.id`, doesn't silently drop
         // newly-synced games.
         if entity.id == nil {
             let uuidString = String(recordName.dropFirst("game-".count))
             entity.id = UUID(uuidString: uuidString)
         }
 
         // Seed createdAt/updatedAt from the server record so the library
         // can order newly-arrived games. The CKRecord timestamps are the
         // source of truth when we don't have a local creation event.
         if entity.createdAt == nil {
             entity.createdAt = record.creationDate ?? Date()
         }
         entity.updatedAt = record.modificationDate ?? entity.updatedAt ?? Date()
 
         entity.ckRecordName = recordName
         entity.ckSystemFields = encodeSystemFields(of: record)
         entity.title = record["title"] as? String ?? entity.title
         entity.completedAt = record["completedAt"] as? Date
         entity.databaseScope = databaseScope
         // Owner-side share marker — set on the device that created the share
         // and round-tripped via the Game record so other owner-devices learn
         // the game is shared. On participant devices `databaseScope == 1`
         // already implies shared, but keeping the field in sync is harmless.
         if let shareRecordName = record["shareRecordName"] as? String {
             entity.ckShareRecordName = shareRecordName
         }
 
         // Persist the zone identity so outbound moves use the right zone ID.
         entity.ckZoneName = record.recordID.zoneID.zoneName
         let ownerName = record.recordID.zoneID.ownerName
         entity.ckZoneOwnerName = ownerName == CKCurrentUserDefaultName ? nil : ownerName
 
         if let asset = record["puzzleSource"] as? CKAsset,
            let fileURL = asset.fileURL,
            let source = try? String(contentsOf: fileURL, encoding: .utf8) {
             entity.puzzleSource = source
             if let xd = try? XD.parse(source) {
                 entity.puzzleCmVersion = Int64(XD.currentCmVersion)
                 entity.populateCachedSummaryFields(from: Puzzle(xd: xd))
             }
         }
 
         return entity
     }
 
     /// Upserts the `MovesEntity` for `value`. The cells blob is taken straight
     /// off the record so any forward-compat fields the encoder added are
     /// preserved verbatim. Bumps the parent `GameEntity.updatedAt` if the
     /// record is fresher.
     static func applyMovesRecord(
         _ record: CKRecord,
         value: MovesValue,
         to ctx: NSManagedObjectContext,
         localAuthorID: String? = nil
     ) {
         let ckName = record.recordID.recordName
         let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
         req.predicate = NSPredicate(format: "ckRecordName == %@", ckName)
         req.fetchLimit = 1
 
         let entity: MovesEntity
         let foundExisting: Bool
         if let existing = try? ctx.fetch(req).first {
             entity = existing
             foundExisting = true
         } else {
             let game = ensureGameEntity(
                 forGameID: value.gameID,
                 zoneID: record.recordID.zoneID,
                 in: ctx
             )
             entity = MovesEntity(context: ctx)
             entity.game = game
             foundExisting = false
         }
 
         // Always adopt system fields so future saves target the server's
         // current change tag. If this is our own per-device row and it already
         // exists locally, the local value state is authoritative; tokenless
         // push-driven direct fetches can re-deliver an older server copy while
         // newer edits are still queued for upload.
         entity.ckRecordName = ckName
         entity.ckSystemFields = encodeSystemFields(of: record)
         entity.authorID = value.authorID
         entity.deviceID = value.deviceID
         let isLocalDeviceRow = value.authorID == localAuthorID
             && value.deviceID == localDeviceID
         guard !foundExisting || !isLocalDeviceRow else { return }
         entity.updatedAt = value.updatedAt
         entity.cells = (record["cells"] as? Data) ?? Data()
 
         if let game = entity.game,
            game.updatedAt.map({ $0 < value.updatedAt }) ?? true {
             game.updatedAt = value.updatedAt
         }
     }
 
     // MARK: - System fields encode/decode
 
     static func encodeSystemFields(of record: CKRecord) -> Data? {
         let coder = NSKeyedArchiver(requiringSecureCoding: true)
         record.encodeSystemFields(with: coder)
         coder.finishEncoding()
         return coder.encodedData
     }
 
     static func decodeRecord(from data: Data) -> CKRecord? {
         guard let coder = try? NSKeyedUnarchiver(forReadingFrom: data) else { return nil }
         coder.requiresSecureCoding = true
         let record = CKRecord(coder: coder)
         coder.finishDecoding()
         return record
     }
 
     // MARK: - Private helpers
 
     /// Restores a `CKRecord` from archived system fields (preserving the
     /// server change tag) or creates a fresh one if no archive is available.
     private static func restoreOrCreate(
         recordType: String,
         recordName: String,
         zone: CKRecordZone.ID,
         systemFields: Data?
     ) -> CKRecord {
         if let data = systemFields, let restored = decodeRecord(from: data) {
             return restored
         }
         let recordID = CKRecord.ID(recordName: recordName, zoneID: zone)
         return CKRecord(recordType: recordType, recordID: recordID)
     }
 
     private static func fetchOrCreate(
         entityName: String,
         recordName: String,
         in context: NSManagedObjectContext
     ) -> NSManagedObject {
         let request = NSFetchRequest<NSManagedObject>(entityName: entityName)
         request.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
         request.fetchLimit = 1
         if let existing = try? context.fetch(request).first {
             return existing
         }
         return NSEntityDescription.insertNewObject(forEntityName: entityName, into: context)
     }
 
 }