← All repositories

crossmate

A collaborative crossword app for iPhone and iPad

git clone https://code.inqk.net/crossmate.git


Crossmate/Persistence/PersistenceController.swift (18144B)

1import CloudKit
2import CoreData
3import Foundation
4
5/// Wraps the app's `NSPersistentContainer`. Plain Core Data with no
6/// CloudKit mirroring — sync (single-user iPhone↔iPad and CKShare
7/// collaboration alike) is the job of a separate sync engine that will
8/// drive CloudKit directly on top of this same store. See PLAN.md for the
9/// layered design.
10@MainActor
11final class PersistenceController {
12    let container: NSPersistentContainer
13
14    var viewContext: NSManagedObjectContext { container.viewContext }
15
16    let eventLog: EventLog?
17
18    init(inMemory: Bool = false, storeURL: URL? = nil, eventLog: EventLog? = nil) {
19        self.eventLog = eventLog
20        container = NSPersistentContainer(
21            name: "CrossmateModel",
22            managedObjectModel: Self.sharedModel
23        )
24
25        if inMemory {
26            // NSInMemoryStoreType keeps each store fully isolated in process
27            // memory with no file involvement, which prevents concurrent test
28            // runs from colliding through shared SQLite WAL files at /dev/null.
29            let description = NSPersistentStoreDescription()
30            description.type = NSInMemoryStoreType
31            container.persistentStoreDescriptions = [description]
32        } else {
33            // The app always uses the container's default location; tests
34            // point the store at a throwaway URL to exercise the on-disk
35            // load/recovery path without touching real data.
36            if let storeURL {
37                container.persistentStoreDescriptions = [
38                    NSPersistentStoreDescription(url: storeURL)
39                ]
40            }
41            // Enable lightweight migration so additive schema changes — and
42            // attribute renames carrying a `renamingIdentifier` in the model
43            // — apply on launch without a hand-written mapping. A non-additive
44            // change made in place (no prior model version kept as a migration
45            // source) can't be inferred; `recreateStore(after:)` handles that
46            // by discarding and rebuilding the store.
47            for description in container.persistentStoreDescriptions {
48                description.shouldMigrateStoreAutomatically = true
49                description.shouldInferMappingModelAutomatically = true
50            }
51        }
52
53        container.loadPersistentStores { [self] _, error in
54            guard let error else { return }
55            if inMemory {
56                fatalError("Failed to load in-memory Core Data store: \(error)")
57            }
58            recreateStore(after: error)
59        }
60
61        container.viewContext.automaticallyMergesChangesFromParent = true
62        container.viewContext.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
63
64        if !inMemory {
65            // Synchronous, unlike the backfill below: a stranded row shadows
66            // the real game in every `id`-keyed lookup, so leaving a window
67            // where the library is live but the heal hasn't landed means the
68            // user can still open the broken row on this launch.
69            healStrandedSharedGameRows_v1()
70            backfillZoneIdentityFields()
71            backfillCachedSummaryFields()
72        }
73    }
74
75    /// Rebuilds the store empty when an existing one can't be opened against
76    /// the current model — e.g. after an in-place schema change with no
77    /// migration source. The store is *usually* a rebuildable cache of CloudKit
78    /// (the sync engine refetches every record on the next sync), but not
79    /// always: iCloud sync is user-toggleable, making the local store the only
80    /// copy of that user's games, and even with sync on, offline edits may not
81    /// have uploaded yet. The failing files are therefore moved aside under a
82    /// `.broken-<timestamp>` suffix rather than destroyed, so the data stays
83    /// inspectable and recoverable, and the recovery is surfaced through
84    /// diagnostics.
85    private func recreateStore(after originalError: Error) {
86        let coordinator = container.persistentStoreCoordinator
87        var preserved: [String] = []
88        for description in container.persistentStoreDescriptions {
89            guard let url = description.url else { continue }
90            preserved.append(contentsOf: preserveBrokenStore(at: url))
91            do {
92                try coordinator.destroyPersistentStore(
93                    at: url,
94                    ofType: description.type,
95                    options: description.options
96                )
97            } catch {
98                // Best effort — fall through and let the reload attempt report
99                // the real failure if the store truly can't be replaced.
100            }
101        }
102        container.loadPersistentStores { _, retryError in
103            if let retryError {
104                fatalError(
105                    "Failed to load Core Data store after reset: \(retryError) "
106                    + "(original open error: \(originalError))"
107                )
108            }
109        }
110        eventLog?.note(
111            "PersistenceController: store load failed; rebuilt empty"
112            + (preserved.isEmpty
113                ? " (no files to preserve)"
114                : " (broken store preserved as \(preserved.joined(separator: ", ")))")
115            + " — \(originalError)",
116            level: "error"
117        )
118    }
119
120    /// Moves the failing store's files (including the `-wal`/`-shm` sidecars)
121    /// aside before destructive recovery, returning the names of the files it
122    /// preserved. Best effort: a file that can't be moved is left in place for
123    /// `destroyPersistentStore` to clear, so recovery always proceeds.
124    private func preserveBrokenStore(at url: URL) -> [String] {
125        let fileManager = FileManager.default
126        let formatter = DateFormatter()
127        formatter.dateFormat = "yyyyMMdd-HHmmss"
128        formatter.timeZone = TimeZone(secondsFromGMT: 0)
129        let timestamp = formatter.string(from: Date())
130        var preserved: [String] = []
131        for suffix in ["", "-wal", "-shm"] {
132            let source = URL(fileURLWithPath: url.path + suffix)
133            guard fileManager.fileExists(atPath: source.path) else { continue }
134            let destination = URL(fileURLWithPath: source.path + ".broken-\(timestamp)")
135            do {
136                try fileManager.moveItem(at: source, to: destination)
137                preserved.append(destination.lastPathComponent)
138            } catch {
139                // Leave the file for destroyPersistentStore.
140            }
141        }
142        return preserved
143    }
144
145    // MARK: - TEMPORARY v1.1 MIGRATION
146
147    /// Repairs `GameEntity` rows stranded by the sync-engine scope bug: while
148    /// `SyncEngine.handleEvent` resolved an engine's database by instance
149    /// identity, a fetch still in flight from an engine that `resetSyncState`
150    /// had just replaced (the account-switch and v4-container purges both
151    /// replace both engines) resolved to *shared*. The private database's zone
152    /// changes then ran the shared branch, which seats a "Joining…" placeholder
153    /// for every newly-visible zone — so every game the user owned got a
154    /// `databaseScope == 1` row carrying the owner placeholder.
155    ///
156    /// Neither scope's `gameIdentityPredicate` can match that row again
157    /// (private wants `ckZoneOwnerName == NIL`, shared wants a concrete owner),
158    /// so the arriving Game record forked a second row instead of filling this
159    /// one in. Two rows then answered to one `id`, and the `fetchLimit = 1`
160    /// lookups in `GameStore.loadGame(id:)` and `movesDiagnostics(for:by:)`
161    /// picked between them unpredictably — an empty row reads as
162    /// `.missingGrid`, surfacing as "Couldn't load puzzle".
163    ///
164    /// Only empty placeholders are touched: a stranded row that carries a
165    /// puzzle is not this bug's work and is left alone. A row with a sibling is
166    /// merged into it and deleted; a row without one is repaired to private
167    /// scope, which is always right here — the branch that produced these rows
168    /// only ever ran over zones the user owns — so the ordinary private sync
169    /// path adopts and fills it.
170    ///
171    /// Gated on a stored flag rather than left to its predicate: unlike the
172    /// non-destructive backfills below this one deletes rows, and a standing
173    /// destructive sweep would be a hazard if some later change ever made this
174    /// row shape legitimate. Remove as one block with
175    /// `strandedSharedRowHealKey`, its call site, and
176    /// `PersistenceControllerHealTests`.
177    private static let strandedSharedRowHealKey = "healStrandedSharedGameRows_v1"
178
179    func healStrandedSharedGameRows_v1(force: Bool = false) {
180        let defaults = UserDefaults.standard
181        if !force, defaults.bool(forKey: Self.strandedSharedRowHealKey) { return }
182
183        let ctx = container.newBackgroundContext()
184        ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
185        let summary: String? = ctx.performAndWait {
186            let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
187            // `CKCurrentUserDefaultName` is the spelling the placeholder branch
188            // copied off the private zone; nil covers the same shape from
189            // `constructJoinedGame`'s former owner-normalising ternary.
190            req.predicate = NSPredicate(
191                format: "databaseScope == 1"
192                    + " AND (ckZoneOwnerName == nil OR ckZoneOwnerName == %@)"
193                    + " AND (puzzleSource == nil OR puzzleSource == %@)",
194                CKCurrentUserDefaultName,
195                ""
196            )
197            guard let stranded = try? ctx.fetch(req), !stranded.isEmpty else { return nil }
198
199            var merged = 0
200            var repaired = 0
201            for row in stranded {
202                guard let id = row.id else {
203                    // No domain identity, no puzzle, unmatchable by sync: inert.
204                    ctx.delete(row)
205                    merged += 1
206                    continue
207                }
208                let siblings = NSFetchRequest<GameEntity>(entityName: "GameEntity")
209                siblings.predicate = NSPredicate(
210                    format: "id == %@ AND SELF != %@", id as CVarArg, row
211                )
212                siblings.fetchLimit = 1
213                if let survivor = try? ctx.fetch(siblings).first {
214                    Self.adoptChildren(of: row, into: survivor, in: ctx)
215                    ctx.delete(row)
216                    merged += 1
217                } else {
218                    row.databaseScope = 0
219                    row.ckZoneOwnerName = nil
220                    repaired += 1
221                }
222            }
223
224            guard ctx.hasChanges else { return nil }
225            do {
226                try ctx.save()
227                return "PersistenceController: healed \(stranded.count) stranded shared "
228                    + "game row(s) — \(merged) merged, \(repaired) repaired to private"
229            } catch {
230                return "PersistenceController: stranded-row heal save failed — \(error)"
231            }
232        }
233
234        // `force` is the test affordance for driving the pass repeatedly; it
235        // deliberately leaves the shared flag untouched so tests stay hermetic.
236        if !force { defaults.set(true, forKey: Self.strandedSharedRowHealKey) }
237        if let summary { eventLog?.note(summary) }
238    }
239
240    /// Moves a stranded row's irreplaceable children onto the surviving row.
241    ///
242    /// `moves` and `journal` are the synced/durable payload and `players`
243    /// carries local read state, so they are reparented — skipping any whose
244    /// counterpart the survivor already holds, since both rows may have been
245    /// written from the same records. `cells` and `peerChanges` are derived
246    /// caches (replay rebuilds one, the next ledger build the other), so they
247    /// are left to cascade with the deleted row.
248    private nonisolated static func adoptChildren(
249        of row: GameEntity,
250        into survivor: GameEntity,
251        in ctx: NSManagedObjectContext
252    ) {
253        let existingMoves = Set(
254            ((survivor.moves as? Set<MovesEntity>) ?? []).compactMap(\.ckRecordName)
255        )
256        for child in (row.moves as? Set<MovesEntity>) ?? [] {
257            guard let name = child.ckRecordName, !existingMoves.contains(name) else {
258                ctx.delete(child)
259                continue
260            }
261            child.game = survivor
262        }
263
264        let existingPlayers = Set(
265            ((survivor.players as? Set<PlayerEntity>) ?? []).compactMap(\.ckRecordName)
266        )
267        for child in (row.players as? Set<PlayerEntity>) ?? [] {
268            guard let name = child.ckRecordName, !existingPlayers.contains(name) else {
269                ctx.delete(child)
270                continue
271            }
272            child.game = survivor
273        }
274
275        // Journal rows have no record name; a device's log is keyed by its
276        // source device and sequence number.
277        let existingJournal = Set(
278            ((survivor.journal as? Set<JournalEntity>) ?? []).map {
279                "\($0.sourceDeviceID ?? "")|\($0.seq)"
280            }
281        )
282        for child in (row.journal as? Set<JournalEntity>) ?? [] {
283            let key = "\(child.sourceDeviceID ?? "")|\(child.seq)"
284            guard !existingJournal.contains(key) else {
285                ctx.delete(child)
286                continue
287            }
288            child.game = survivor
289        }
290    }
291
292    // MARK: - Backfill
293
294    /// Populates the derived summary columns on rows that never got them.
295    ///
296    /// Chronicles materialized before `Archive.materialize` populated these
297    /// are the population that matters: `GameSummary` papers over the gap by
298    /// reparsing `puzzleSource`, but anything that queries the columns
299    /// directly — the browser's "already in your library" lookup — simply
300    /// can't see those rows.
301    ///
302    /// Self-limiting rather than flag-gated: a populated row no longer matches
303    /// `gridWidth == 0`. A row whose source won't parse stays unmatched and is
304    /// retried on later launches, which is the right outcome for the handful
305    /// of rows that could be in that state.
306    private func backfillCachedSummaryFields() {
307        let bg = container.newBackgroundContext()
308        let eventLog = eventLog
309        bg.perform {
310            let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
311            req.predicate = NSPredicate(
312                format: "gridWidth == 0 AND puzzleSource != nil AND puzzleSource != %@",
313                ""
314            )
315            guard let rows = try? bg.fetch(req), !rows.isEmpty else { return }
316            for entity in rows {
317                guard let source = entity.puzzleSource,
318                      let xd = try? XD.parse(source) else { continue }
319                entity.populateCachedSummaryFields(from: Puzzle(xd: xd))
320            }
321            guard bg.hasChanges else { return }
322            do {
323                try bg.save()
324            } catch {
325                Task { @MainActor in
326                    eventLog?.note(
327                        "PersistenceController: backfillCachedSummaryFields save failed — \(error)",
328                        level: "error"
329                    )
330                }
331            }
332        }
333    }
334
335    /// One-shot pass for `GameEntity` rows written before inbound lookups
336    /// matched on full zone identity (`RecordSerializer.gameIdentityPredicate`).
337    /// Without it, a legacy row is invisible to the new predicate and the next
338    /// fetched record silently spawns a duplicate. Two normalizations:
339    /// a missing `ckZoneName` is derived from `ckRecordName` (game zone and
340    /// record share the `game-<UUID>` spelling), and `ckZoneOwnerName` is
341    /// cleared on private-scope rows — private zones always belong to the
342    /// current user and are matched as `ckZoneOwnerName == NIL`, but rows
343    /// written before that invariant could hold a concrete user-record ID
344    /// when CloudKit round-tripped one instead of the owner placeholder.
345    /// No-ops on every subsequent launch.
346    private func backfillZoneIdentityFields() {
347        let bg = container.newBackgroundContext()
348        let eventLog = eventLog
349        bg.perform {
350            let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
351            req.predicate = NSPredicate(
352                format: "(ckRecordName != nil AND ckZoneName == nil) "
353                    + "OR (databaseScope == 0 AND ckZoneOwnerName != nil)"
354            )
355            guard let rows = try? bg.fetch(req), !rows.isEmpty else { return }
356            for entity in rows {
357                if entity.ckZoneName == nil {
358                    entity.ckZoneName = entity.ckRecordName
359                }
360                if entity.databaseScope == 0 {
361                    entity.ckZoneOwnerName = nil
362                }
363            }
364            if bg.hasChanges {
365                do {
366                    try bg.save()
367                } catch {
368                    Task { @MainActor in
369                        eventLog?.note(
370                            "PersistenceController: backfillZoneIdentityFields save failed — \(error)",
371                            level: "error"
372                        )
373                    }
374                }
375            }
376        }
377    }
378
379    // Loaded once and shared across all container instances so that entity
380    // descriptions are identical objects, which is required for CoreData
381    // relationship type-checking to pass when tests create multiple containers
382    // concurrently.
383    private static let sharedModel: NSManagedObjectModel = {
384        for bundle in Bundle.allBundles + Bundle.allFrameworks {
385            if let url = bundle.url(forResource: "CrossmateModel", withExtension: "momd"),
386               let model = NSManagedObjectModel(contentsOf: url) {
387                return model
388            }
389        }
390        fatalError("CrossmateModel.momd not found in any loaded bundle")
391    }()
392}