Crossmate/Services/AppServices.swift (133903B)
1import CloudKit
2import CoreData
3import Foundation
4import UIKit
5import UserNotifications
6
7
8
9
10
11
12
13
14enum DemoSeed {
15
16
17
18
19 enum Profile {
20 case development
21 case marketing
22 }
23
24
25
26
27 static let localAuthorID = "_demo-you"
28
29 private static let alice = "_demo-alice"
30 private static let bob = "_demo-bob"
31 private static let carol = "_demo-carol"
32
33 private static let friends: [(id: String, name: String)] = [
34 (alice, "Alice"),
35 (bob, "Bob"),
36 (carol, "Carol"),
37 ]
38
39
40
41
42
43 private struct GameSpec {
44 let title: String
45 let resourceID: String
46 let participants: [String]
47 let fillAuthors: [String]
48 let completed: Bool
49 }
50
51
52
53
54
55 private static func games(for profile: Profile) -> [GameSpec] {
56
57
58 let showcase: GameSpec = switch profile {
59 case .development:
60 GameSpec(
61 title: "Tuesday Crossword",
62 resourceID: "cm-starter-0001",
63 participants: [alice, bob, carol],
64 fillAuthors: [localAuthorID, alice, bob, carol],
65 completed: false
66 )
67 case .marketing:
68 GameSpec(
69 title: "Tuesday Crossword",
70 resourceID: "cm-starter-0001",
71 participants: [alice, bob],
72 fillAuthors: [localAuthorID, alice, bob],
73 completed: false
74 )
75 }
76 return [
77 showcase,
78 GameSpec(
79 title: "Sunday Special",
80 resourceID: "cm-starter-0002",
81 participants: [alice, bob],
82 fillAuthors: [localAuthorID, alice, bob],
83 completed: false
84 ),
85 GameSpec(
86 title: "Coffee Break",
87 resourceID: "cm-starter-0003",
88 participants: [],
89 fillAuthors: [],
90 completed: true
91 ),
92 GameSpec(
93 title: "Weekend Challenge",
94 resourceID: "cm-starter-0004",
95 participants: [alice, carol],
96 fillAuthors: [],
97 completed: true
98 ),
99 ]
100 }
101
102 @MainActor
103 static func populate(
104 persistence: PersistenceController,
105 preferences: PlayerPreferences,
106 profile: Profile
107 ) {
108 let ctx = persistence.viewContext
109
110
111 if !preferences.hasName {
112 preferences.name = "You"
113 }
114
115 for friend in friends {
116 seedFriend(friend, in: ctx)
117 }
118
119
120
121 for spec in games(for: profile) {
122 guard let entry = PuzzleCatalog.source(matchingResourceID: spec.resourceID, title: nil),
123 let source = try? entry.loadSource(),
124 let xd = try? XD.parse(source) else { continue }
125 let puzzle = Puzzle(xd: xd)
126 let game = seedGame(
127 title: spec.title,
128 resourceID: spec.resourceID,
129 participants: spec.participants,
130 puzzle: puzzle,
131 source: source,
132 completed: spec.completed,
133 in: ctx
134 )
135 if !spec.fillAuthors.isEmpty {
136 seedFilledLetters(in: game, puzzle: puzzle, authors: spec.fillAuthors, in: ctx)
137 }
138 }
139
140 try? ctx.save()
141 }
142
143 private static func seedFriend(
144 _ seed: (id: String, name: String),
145 in ctx: NSManagedObjectContext
146 ) {
147 let friend = FriendEntity(context: ctx)
148 friend.authorID = seed.id
149 friend.createdAt = Date()
150 friend.displayName = seed.name
151 friend.displayNameVersion = 0
152 friend.isBlocked = false
153 friend.nickname = ""
154 friend.nicknameVersion = 0
155 friend.pairKey = "demo-pair-\(seed.id)"
156 }
157
158 @discardableResult
159 private static func seedGame(
160 title: String,
161 resourceID: String,
162 participants: [String],
163 puzzle: Puzzle,
164 source: String,
165 completed: Bool,
166 in ctx: NSManagedObjectContext
167 ) -> GameEntity {
168 let now = Date()
169 let game = GameEntity(context: ctx)
170 game.id = UUID()
171 game.title = title
172 game.puzzleSource = source
173 game.puzzleParserVersion = Int64(XD.currentParserVersion)
174 game.puzzleResourceID = resourceID
175 game.createdAt = now
176 game.updatedAt = now
177 game.syncVersion = GameSyncVersion.current
178
179
180
181 if !participants.isEmpty {
182 game.ckShareRecordName = "demo-share-\(title)"
183 }
184
185
186 if completed {
187 game.completedAt = now
188 game.completedBy = participants.first ?? localAuthorID
189 }
190 game.populateCachedSummaryFields(from: puzzle)
191
192 for authorID in participants {
193 let player = PlayerEntity(context: ctx)
194 player.game = game
195 player.authorID = authorID
196 player.name = friends.first { $0.id == authorID }?.name
197 player.ckRecordName = "demo-player-\(title)-\(authorID)"
198 player.updatedAt = now
199 }
200 return game
201 }
202
203
204
205
206
207
208
209
210 private static func seedFilledLetters(
211 in game: GameEntity,
212 puzzle: Puzzle,
213 authors: [String],
214 in ctx: NSManagedObjectContext
215 ) {
216 guard !authors.isEmpty else { return }
217 let now = Date()
218 var cellsByAuthor: [String: [GridPosition: TimestampedCell]] = [:]
219
220 for r in 0..<puzzle.height {
221 for c in 0..<puzzle.width {
222 let cell = puzzle.cells[r][c]
223 guard !cell.isBlock,
224 let solution = cell.solution,
225 !solution.isEmpty,
226 !solution.allSatisfy(\.isWhitespace)
227 else { continue }
228
229 if (r * 5 + c) % 7 == 0 { continue }
230 let author = authors[((r / 2) + (c / 2)) % authors.count]
231 cellsByAuthor[author, default: [:]][GridPosition(row: r, col: c)] =
232 TimestampedCell(
233 letter: solution.uppercased(),
234 mark: .none,
235 updatedAt: now,
236 authorID: author
237 )
238 }
239 }
240
241 for (author, cells) in cellsByAuthor {
242 let entity = MovesEntity(context: ctx)
243 entity.game = game
244 entity.authorID = author
245 entity.deviceID = "demo-device-\(author)"
246 entity.ckRecordName = "demo-moves-\(game.id?.uuidString ?? "")-\(author)"
247 entity.cells = (try? MovesCodec.encode(cells)) ?? Data()
248 entity.updatedAt = now
249 }
250 }
251}
252
253@MainActor
254final class AppServices {
255
256
257
258
259
260
261 static weak var current: AppServices?
262
263 enum ReadCursorPublishMode {
264 case activeLease
265 case currentTime
266 }
267
268 private static let readLeaseDuration: TimeInterval = 10 * 60
269 private static let readLeaseRefreshFloor: TimeInterval = 5 * 60
270
271 enum FreshenReason {
272 case appeared
273 case foreground
274 case manual
275 case remote
276
277 var diagnosticLabel: String {
278 switch self {
279 case .appeared: return "appeared"
280 case .foreground: return "foreground"
281 case .manual: return "manual"
282 case .remote: return "remote"
283 }
284 }
285 }
286
287 let persistence: PersistenceController
288 let store: GameStore
289 let syncEngine: SyncEngine
290 let eventLog: EventLog
291 let syncMonitor: SyncMonitor
292 let nytAuth: NYTAuthService
293 let driveMonitor: DriveMonitor
294 let nytFetcher: NYTPuzzleFetcher
295 let inputMonitor: InputMonitor
296 let movesUpdater: MovesUpdater
297 let sessionMonitor: SessionMonitor
298 let announcements: AnnouncementCenter
299 let playerSelectionPublisher: PlayerSelectionPublisher
300 let identity: AuthorIdentity
301 let pushClient: PushClient?
302
303
304 let sessions: SessionCoordinator
305
306
307
308 let accountPush: AccountPushCoordinator
309
310
311 let replays: ReplayLoader
312 let shareController: ShareController
313 let friendController: FriendController
314 let gameArchiver: GameArchiver
315 let cursorStore: GameCursorStore
316
317 let friendInviteRecency: FriendInviteRecencyStore
318
319
320 let gameViewedStore: GameViewedStore
321
322
323
324 let tips: TipStore
325 let engagementStore: EngagementStore
326 let cloudService: CloudService
327 let importService: ImportService
328 let engagementHost: EngagementHost
329 let engagementStatus = EngagementStatus()
330 let inviteDeliveries = InviteDeliveryStore()
331 private(set) lazy var appActions = AppActions(services: self)
332
333
334
335
336 private(set) lazy var engagement = EngagementLifecycle(
337 preferences: preferences,
338 persistence: persistence,
339 store: store,
340 identity: identity,
341 syncMonitor: syncMonitor,
342 engagementHost: engagementHost,
343 engagementStatus: engagementStatus,
344 engagementStore: engagementStore,
345 isAppForeground: { [weak self] in self?.isAppForeground ?? false },
346 renewReadLease: { [weak self] gameID in
347 await self?.publishReadCursor(for: gameID, mode: .activeLease)
348 },
349 ensureICloudSyncStarted: { [weak self] in
350 await self?.ensureICloudSyncStarted() ?? false
351 }
352 )
353
354
355 private(set) lazy var badge = BadgeCoordinator(
356 store: store,
357 syncMonitor: syncMonitor,
358 readLeaseDuration: Self.readLeaseDuration,
359 publishAccountSeenPush: { [weak self] gameID, presenceUntil in
360 await self?.accountPush.publishAccountSeenPush(gameID: gameID, presenceUntil: presenceUntil)
361 }
362 )
363
364
365
366 private(set) lazy var invites = InviteCoordinator(
367 persistence: persistence,
368 identity: identity,
369 preferences: preferences,
370 syncMonitor: syncMonitor,
371 eventLog: eventLog,
372 store: store,
373 syncEngine: syncEngine,
374 announcements: announcements,
375 shareController: shareController,
376 friendController: friendController,
377 cloudService: cloudService,
378 refreshAppBadge: { [weak self] reason in
379 await self?.badge.refreshAppBadge(reason: reason)
380 },
381 publishInvitePush: { [weak self] friendAuthorID, gameID, title, inviterName in
382 await self?.accountPush.publishInvitePush(
383 to: friendAuthorID,
384 gameID: gameID,
385 puzzleTitle: title,
386 inviterName: inviterName
387 )
388 }
389 )
390
391 let preferences: PlayerPreferences
392
393 private let ckContainer = CloudContainer.container
394
395
396
397
398 private var startupTask: Task<Void, Never>?
399 private var syncStarted = false
400
401
402
403
404 private var syncStartTask: Task<Bool, Never>?
405 private(set) var playerNamePublisher: PlayerNamePublisher?
406 private var isReadyForShareAcceptance = false
407 private var isProcessingShareAcceptanceQueue = false
408
409
410
411
412 private var isAcceptingSharedGame = false
413 private var pendingShareMetadatas: [CKShare.Metadata] = []
414
415
416
417 private var lastRemoteNotificationAt: Date?
418 private var privatePushCatchUpTask: Task<Void, Never>?
419 private var sharedPushCatchUpTask: Task<Void, Never>?
420 private var privateSessionScanTask: Task<Void, Never>?
421 private var sharedSessionScanTask: Task<Void, Never>?
422 private var isHandlingPrivateRemoteNotification = false
423 private var isHandlingSharedRemoteNotification = false
424 private var gameListFreshenTask: Task<Void, Never>?
425
426
427
428 private var completedPageTask: Task<GameArchiver.CompletedPage, Never>?
429 private var completedPageTaskID: UUID?
430 private var hasStartedRemoteCompletedMigration = false
431 private var isFresheningPrivateGameList = false
432 private var isFresheningSharedGameList = false
433
434
435
436 private var shouldRunColdLaunchArchiveReconcile = true
437
438
439
440
441
442 private var lastPrivateGameListFreshenAt: Date?
443 private var lastSharedGameListFreshenAt: Date?
444
445
446
447 private let gameListFreshenCooldown: TimeInterval = 300
448 private var fresheningPuzzleGridKeys: Set<String> = []
449 private var lastRemotePuzzleGridFreshenAt: [String: Date] = [:]
450
451
452
453
454
455 private let remotePuzzleGridFreshenDebounce: TimeInterval = 5
456 private var isGameListVisible = false
457
458
459
460
461 private var mountedPuzzleCounts: [UUID: Int] = [:]
462
463
464
465
466
467
468 private(set) var isAppForeground = true
469
470
471
472
473
474
475
476 static func accountSwitchRequiresPurge(previousID: String?, newID: String?) -> Bool {
477 guard let previousID, let newID else { return false }
478 return previousID != newID
479 }
480
481 init() {
482 let eventLog = EventLog()
483 self.eventLog = eventLog
484
485
486
487
488
489
490
491 let arguments = ProcessInfo.processInfo.arguments
492 let seedProfile: DemoSeed.Profile? =
493 if arguments.contains("--crossmate-seed-marketing") {
494 .marketing
495 } else if arguments.contains("--crossmate-seed-demo") {
496 .development
497 } else {
498 nil
499 }
500 let isDemoSeed = seedProfile != nil
501
502
503
504 let preferences = isDemoSeed ? PlayerPreferences.ephemeral() : PlayerPreferences()
505 self.preferences = preferences
506 let persistence = PersistenceController(inMemory: isDemoSeed, eventLog: eventLog)
507 self.persistence = persistence
508 if let seedProfile {
509 DemoSeed.populate(persistence: persistence, preferences: preferences, profile: seedProfile)
510
511
512
513 UserDefaults.standard.set(
514 ProcessInfo.processInfo.arguments.contains("--crossmate-show-v4-notice"),
515 forKey: Self.showV4NoticeDefaultsKey
516 )
517 }
518 let syncEngine = SyncEngine(container: self.ckContainer, persistence: persistence)
519 self.syncEngine = syncEngine
520 self.syncMonitor = SyncMonitor(log: eventLog)
521 self.driveMonitor = DriveMonitor()
522 self.nytAuth = NYTAuthService(log: { message in
523 eventLog.note(message)
524 })
525 self.nytFetcher = NYTPuzzleFetcher { NYTAuthService.currentCookieResult() }
526 self.inputMonitor = InputMonitor()
527
528
529
530
531 let identity = isDemoSeed ? AuthorIdentity(testing: DemoSeed.localAuthorID) : AuthorIdentity()
532 self.identity = identity
533 let pushSyncMonitor = self.syncMonitor
534 self.pushClient = PushClient(log: { message in
535 Task { @MainActor in pushSyncMonitor.note(message) }
536 })
537 self.pushClient?.updateAuthorID(identity.currentID)
538
539 let movesUpdater = MovesUpdater(
540 debounceInterval: .milliseconds(500),
541 persistence: persistence,
542 writerAuthorIDProvider: { await MainActor.run { identity.currentID } },
543 sink: { [persistence] gameIDs, drain in
544
545
546
547
548
549
550
551
552
553
554
555
556 await MainActor.run {
557 let viewContext = persistence.viewContext
558 for gameID in gameIDs {
559 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
560 req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
561 req.fetchLimit = 1
562 guard let entity = try? viewContext.fetch(req).first else { continue }
563 viewContext.refresh(entity, mergeChanges: true)
564 }
565 }
566 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
567 guard isEnabled else { return }
568 await syncEngine.enqueueMoves(gameIDs: gameIDs, drain: drain)
569 }
570 )
571 self.movesUpdater = movesUpdater
572
573 self.announcements = AnnouncementCenter()
574
575 let cursorStore = GameCursorStore()
576 self.cursorStore = cursorStore
577 self.friendInviteRecency = FriendInviteRecencyStore()
578 let gameViewedStore = GameViewedStore()
579 self.gameViewedStore = gameViewedStore
580 self.tips = TipStore()
581 let engagementStore = EngagementStore()
582 self.engagementStore = engagementStore
583 let onGameDeletedHandler = Self.makeOnGameDeleted(
584 syncEngine: syncEngine,
585 cursorStore: cursorStore,
586 viewedStore: gameViewedStore
587 )
588
589 let store = GameStore(
590 persistence: persistence,
591 movesUpdater: movesUpdater,
592 authorIDProvider: { identity.currentID },
593 onGameCreated: { [preferences, syncEngine] ckRecordName in
594 Task {
595 guard await MainActor.run(body: { preferences.isICloudSyncEnabled }) else { return }
596 await syncEngine.enqueueGame(ckRecordName: ckRecordName)
597 }
598 },
599 onGameUpdated: { [preferences, syncEngine] ckRecordName in
600 Task {
601 guard await MainActor.run(body: { preferences.isICloudSyncEnabled }) else { return }
602 await syncEngine.enqueueGame(ckRecordName: ckRecordName)
603 }
604 },
605 onGameDeleted: { [preferences] deletion in
606
607
608
609
610
611 BadgeState.forget(gameID: deletion.gameID)
612 guard preferences.isICloudSyncEnabled else { return }
613 onGameDeletedHandler(deletion)
614 },
615 eventLog: eventLog
616 )
617 self.store = store
618
619
620
621 identity.onIdentityResolved = { [weak store] fallbackID, realID in
622 store?.remapAuthorID(from: fallbackID, to: realID)
623 }
624
625
626 self.pushClient?.gameCredentialResolver = { [weak store] gameID in
627 store?.ensurePushCredentials(for: gameID)
628 }
629
630
631
632
633 self.pushClient?.contentKeyResolver = { [weak store] gameID in
634 guard let keyString = store?.ensurePushCredentials(for: gameID)?.contentKey
635 else { return nil }
636 return PushPayloadCipher.key(fromBase64: keyString)
637 }
638
639 let sessionMonitor = SessionMonitor(
640 store: store,
641 localAuthorIDProvider: { identity.currentID }
642 )
643 self.sessionMonitor = sessionMonitor
644
645 self.sessions = SessionCoordinator(
646 persistence: persistence,
647 store: store,
648 syncEngine: syncEngine,
649 syncMonitor: self.syncMonitor,
650 sessionMonitor: sessionMonitor,
651 gameViewedStore: gameViewedStore,
652 announcements: self.announcements,
653 identity: identity,
654 preferences: preferences,
655 pushClient: self.pushClient
656 )
657
658 let accountPush = AccountPushCoordinator(
659 identity: identity,
660 preferences: preferences,
661 persistence: persistence,
662 store: store,
663 syncEngine: syncEngine,
664 syncMonitor: self.syncMonitor,
665 pushClient: self.pushClient
666 )
667 self.accountPush = accountPush
668 store.onPushRegistrationMayNeedRefresh = { [weak accountPush] in
669 guard let accountPush else { return }
670 Task { @MainActor in
671 await accountPush.reconcilePushRegistration()
672 }
673 }
674
675 self.replays = ReplayLoader(
676 store: store,
677 syncEngine: syncEngine,
678 syncMonitor: self.syncMonitor
679 )
680
681 self.shareController = ShareController(
682 container: self.ckContainer,
683 persistence: persistence,
684 syncEngine: syncEngine,
685 syncMonitor: self.syncMonitor
686 )
687 self.playerSelectionPublisher = PlayerSelectionPublisher(
688
689
690
691 debounceInterval: { [engagementStatus] gameID in
692 engagementStatus.isLive(gameID: gameID) ? .milliseconds(2500) : .milliseconds(500)
693 },
694 persistence: persistence,
695 sink: { gameID, authorID, drain in
696 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
697 guard isEnabled else { return }
698 await syncEngine.enqueuePlayer(
699 gameID: gameID,
700 authorID: authorID,
701 reason: "selection",
702 drain: drain
703 )
704 },
705 peerPresent: { [persistence, identity] gameID in
706 let localAuthorID = await MainActor.run { identity.currentID }
707 return await Self.hasPresentPeer(
708 persistence: persistence,
709 gameID: gameID,
710 localAuthorID: localAuthorID
711 )
712 }
713 )
714 self.friendController = FriendController(
715 container: self.ckContainer,
716 persistence: persistence,
717 syncEngine: syncEngine,
718 syncMonitor: self.syncMonitor,
719 eventLog: eventLog,
720 publishFriendInvitationKey: { [accountPush] pairKey, zoneID, scope in
721 await accountPush.ensureFriendInvitationKeyPublished(
722 pairKey: pairKey,
723 friendZoneID: zoneID,
724 friendZoneScope: scope
725 )
726 }
727 )
728 self.gameArchiver = GameArchiver(
729 container: self.ckContainer,
730 persistence: persistence,
731 syncEngine: syncEngine,
732 syncMonitor: self.syncMonitor,
733 eventLog: eventLog,
734 localIdentity: { [identity, preferences] in
735 guard let authorID = identity.currentID, !authorID.isEmpty else { return nil }
736 return (authorID, preferences.name)
737 }
738 )
739 self.cloudService = CloudService(
740 container: self.ckContainer,
741 syncEngine: syncEngine,
742 syncMonitor: self.syncMonitor,
743 store: store,
744 shareController: shareController
745 )
746 self.importService = ImportService(store: store, driveMonitor: self.driveMonitor)
747 self.engagementHost = EngagementHost()
748 self.engagementHost.onEvent = { [weak self] event in
749 self?.engagement.handleEngagementEvent(event)
750 }
751 self.store.onLocalCellEdit = { [weak self] edit in
752 self?.engagement.sendLocalCellEdit(edit)
753 }
754 self.store.onLocalCellEditBatch = { [weak self] edits in
755 self?.engagement.sendLocalCellEdits(edits)
756 }
757 self.store.onJournalComplete = { [weak self] gameID, authorID, resigned, notifyPeers in
758 if notifyPeers {
759 self?.sessions.stageCompletionDelivery(gameID: gameID, resigned: resigned)
760 }
761 self?.beginCompletionJournalUpload(gameID: gameID, authorID: authorID)
762 }
763 }
764
765 private static let cloudGenerationKey = "cloudGeneration"
766 private static let currentCloudGeneration = 4
767
768
769 static let showV4NoticeDefaultsKey = "showV4Notice"
770
771
772
773
774
775
776
777 private func migrateOffLegacyContainerIfNeeded() async {
778
779
780
781 guard !ProcessInfo.processInfo.arguments.contains("--crossmate-seed-demo")
782 else { return }
783 let defaults = UserDefaults.standard
784 guard defaults.integer(forKey: Self.cloudGenerationKey) < Self.currentCloudGeneration
785 else { return }
786
787 if await deviceHasLegacyData() {
788 do {
789 try await cloudService.purgeLocalData()
790 } catch {
791 syncMonitor.note("v4 transition purge failed — \(error)")
792 }
793 defaults.set(true, forKey: Self.showV4NoticeDefaultsKey)
794 syncMonitor.note("Migrated device off legacy CloudKit container — local cache cleared for v4")
795 }
796 defaults.set(Self.currentCloudGeneration, forKey: Self.cloudGenerationKey)
797 }
798
799
800
801
802 private static let legacyCloudReclaimedKey = "legacyCloudDataReclaimed"
803
804
805
806
807
808 private func reclaimLegacyCloudStorageIfNeeded() {
809
810
811 guard !ProcessInfo.processInfo.arguments.contains("--crossmate-seed-demo")
812 else { return }
813 let defaults = UserDefaults.standard
814 guard !defaults.bool(forKey: Self.legacyCloudReclaimedKey) else { return }
815
816 Task { [syncEngine, syncMonitor] in
817 let swept = await syncEngine.deleteLegacyCloudData { message in
818 syncMonitor.note(message)
819 }
820 guard swept else { return }
821 UserDefaults.standard.set(true, forKey: Self.legacyCloudReclaimedKey)
822 }
823 }
824
825
826
827
828
829
830 private func deviceHasLegacyData() async -> Bool {
831 if store.hasAnyGames() { return true }
832 do {
833 let zones = try await CloudContainer.v3Container
834 .privateCloudDatabase.allRecordZones()
835 let defaultZoneName = CKRecordZone.default().zoneID.zoneName
836 return zones.contains { $0.zoneID.zoneName != defaultZoneName }
837 } catch {
838 return false
839 }
840 }
841
842 func start(appDelegate: AppDelegate) async {
843 if let startupTask {
844 await startupTask.value
845 return
846 }
847
848 let task = Task { @MainActor in
849 await self.performStartup(appDelegate: appDelegate)
850 }
851 startupTask = task
852 await task.value
853 }
854
855 private func performStartup(appDelegate: AppDelegate) async {
856
857
858
859
860
861 await migrateOffLegacyContainerIfNeeded()
862
863
864
865
866
867
868
869 reclaimLegacyCloudStorageIfNeeded()
870
871
872
873
874
875
876
877
878
879 tips.noteColdLaunch()
880
881
882
883 #if DEBUG
884 let suppressTips = MarketingLaunch.isScreenshot
885 #else
886 let suppressTips = false
887 #endif
888 if !suppressTips, let tip = tips.currentTip() {
889 announcements.post(tip.liveAnnouncement())
890 }
891
892
893
894
895
896 await eventLog.loadPersisted()
897
898 nytAuth.loadStoredSession()
899 driveMonitor.start()
900
901 store.onUnreadOtherMovesChanged = { [weak self] in
902 guard let self else { return }
903 Task { await self.badge.refreshAppBadge(reason: "unread changed") }
904 }
905 importVisibleNotificationReceipts()
906 await badge.refreshAppBadge(reason: "startup")
907 await badge.logNotificationStartupSnapshot()
908
909
910
911
912
913 let nicknameCtx = persistence.container.newBackgroundContext()
914 await nicknameCtx.perform {
915 FriendEntity.rebuildNicknameDirectory(in: nicknameCtx)
916
917
918
919 GameEntity.rebuildContentKeyDirectory(in: nicknameCtx)
920 }
921
922 appDelegate.onVisibleNotificationReceiptsAvailable = { [weak self] in
923 Task { @MainActor in
924 self?.importVisibleNotificationReceipts()
925 }
926 }
927 appDelegate.onAPNsRegistrationResult = { [syncMonitor] message in
928 syncMonitor.note(message)
929 }
930 appDelegate.onAPNsToken = { [weak self] data in
931 Task { @MainActor in self?.pushClient?.updateAPNsToken(data) }
932 }
933 CloudShareAcceptanceBroker.shared.onAcceptShare = { metadata in
934 await self.enqueueShareAcceptance(metadata)
935 }
936
937 await syncEngine.setTracer { [syncMonitor] message in
938 syncMonitor.note(message)
939 }
940
941 await syncEngine.setSuccessCheckpoint { [syncMonitor] in
942 syncMonitor.noteSuccess()
943 }
944
945 await syncEngine.setLocalAuthorIDProvider { [identity] in
946 identity.currentID
947 }
948
949 await syncEngine.setOnRemoteMovesUpdated { [weak self, store, identity] gameIDs in
950 store.noteIncomingMovesUpdate(
951 gameIDs: gameIDs,
952 currentAuthorID: identity.currentID
953 )
954 if let currentID = store.currentEntity?.id,
955 gameIDs.contains(currentID) {
956 store.refreshCurrentGame()
957
958
959
960
961
962
963
964 if NotificationState.isSuppressed(gameID: currentID) {
965 await self?.publishReadCursor(for: currentID, mode: .activeLease)
966 }
967 }
968
969
970
971
972
973 store.enqueuePeerChangeLedgerUpdate(for: gameIDs)
974 }
975
976
977
978
979 await syncEngine.setOnRemotePlayersUpdated { [weak self] gameIDs in
980 await self?.invites.reconcileFriendships(forGameIDs: gameIDs)
981
982
983
984 await self?.accountPush.reconcilePushRegistration()
985 }
986
987
988
989
990
991
992 await syncEngine.setOnRemotePlayerPresenceChanged { [weak self] gameIDs in
993 await self?.playerSelectionPublisher.peerPresenceMayHaveChanged(gameIDs: gameIDs)
994 guard let self else { return }
995 for gameID in gameIDs {
996 await self.engagement.reconcileEngagement(gameID: gameID)
997 }
998 }
999
1000
1001
1002
1003 await syncEngine.setOnRemoteEngagementChanged { [weak self] gameIDs in
1004 guard let self else { return }
1005 for gameID in gameIDs {
1006 await self.engagement.reconcileEngagement(gameID: gameID)
1007 }
1008 }
1009
1010
1011
1012
1013
1014 await syncEngine.setOnPushCredentialRotationNeeded { [weak self] gameIDs in
1015 guard let self else { return }
1016 var rotated = false
1017 for gameID in gameIDs where self.store.rotatePushCredentials(for: gameID) != nil {
1018 self.syncMonitor.note("push credentials rotated for \(gameID.uuidString) after roster shrink")
1019 rotated = true
1020 }
1021 if rotated {
1022 await self.accountPush.reconcilePushRegistration()
1023 }
1024 }
1025
1026
1027
1028
1029
1030
1031 await syncEngine.setOnRemoteCredentialsChanged { [weak self] _ in
1032 await self?.accountPush.reconcilePushRegistration()
1033 }
1034
1035 await syncEngine.setOnBlockedFriendsChanged { [weak self] authorIDs in
1036 let hiddenChanges = await self?.store.reconcileBlockedFriendHiddenGames(
1037 forAuthorIDs: authorIDs
1038 ) ?? 0
1039 if hiddenChanges > 0 {
1040 self?.syncMonitor.note("block visibility reconcile: updated \(hiddenChanges) game(s)")
1041 }
1042 await self?.refreshSnapshot()
1043 }
1044
1045 await syncEngine.setOnGameVisibilityCandidates { [weak self] gameIDs in
1046 if let currentID = self?.store.currentEntity?.id,
1047 gameIDs.contains(currentID) {
1048 self?.store.refreshCurrentSyncState()
1049 }
1050 let hiddenChanges = await self?.store.reconcileBlockedFriendHiddenGames(
1051 forGameIDs: gameIDs
1052 ) ?? 0
1053 if hiddenChanges > 0 {
1054 self?.syncMonitor.note("block visibility reconcile: updated \(hiddenChanges) game(s)")
1055 await self?.refreshSnapshot()
1056 }
1057 }
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067 await syncEngine.setOnIncomingReadCursor { [weak self, store, gameViewedStore] pairs in
1068 let now = Date()
1069 for (gameID, presenceUntil, viewedAt) in pairs {
1070 let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, presenceUntil: presenceUntil)
1071 self?.syncMonitor.note(
1072 "lease ADOPT[\(gameID.uuidString.prefix(8))] src=sync " +
1073 "presenceUntil=\(presenceUntil.ISO8601Format()) " +
1074 "was=\(previous?.ISO8601Format() ?? "—")" +
1075 (adopted ? "" : " (no-op)")
1076 )
1077
1078
1079
1080
1081 if let viewedAt {
1082 gameViewedStore.advance(viewedAt, forGame: gameID)
1083 }
1084 if presenceUntil > now {
1085 await self?.badge.dismissDeliveredNotifications(
1086 for: gameID,
1087 seenAt: presenceUntil,
1088 publishAccountSeen: false,
1089 preserveUnread: true
1090 )
1091 } else if NotificationState.activePuzzleID() == gameID {
1092 self?.syncMonitor.note(
1093 "lease ADOPT[\(gameID.uuidString.prefix(8))] past while active; reasserting"
1094 )
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106 await self?.publishReadCursor(
1107 for: gameID,
1108 mode: .activeLease,
1109 requireActivePuzzle: true
1110 )
1111 } else {
1112
1113
1114
1115
1116
1117
1118
1119 BadgeState.markSeen(gameID: gameID, at: presenceUntil)
1120 BadgeState.collapseSuppression(gameID: gameID, to: presenceUntil)
1121 }
1122 }
1123 }
1124
1125 await syncEngine.setOnAccountPushAddress { [weak self] address in
1126 await self?.accountPush.adoptInboundPushAddress(address)
1127 }
1128
1129 await syncEngine.setOnAccountPushSecret { [weak self] secret, version in
1130 await self?.accountPush.adoptInboundPushSecret(secret, version: version)
1131 }
1132
1133 shareController.onParticipantRemoved = { [weak self] gameID in
1134 guard let self else { return }
1135 guard self.store.rotatePushCredentials(for: gameID) != nil else { return }
1136 self.syncMonitor.note(
1137 "push credentials rotated for \(gameID.uuidString) after participant removal"
1138 )
1139 Task { @MainActor [weak self] in
1140 await self?.accountPush.reconcilePushRegistration()
1141 }
1142 }
1143
1144 shareController.onShareSaved = { [weak self] gameID in
1145 guard let self else { return }
1146 self.store.markShared(gameID: gameID)
1147
1148
1149
1150
1151
1152
1153
1154
1155 self.store.ensurePushCredentials(for: gameID)
1156
1157
1158 Task { @MainActor [weak self] in
1159 await self?.accountPush.reconcilePushRegistration()
1160 }
1161
1162
1163
1164
1165 Task { await AppDelegate.requestNotificationAuthorizationIfNeeded() }
1166 }
1167
1168 await syncEngine.setOnPings { [weak self] pings in
1169 guard let self else { return }
1170 await self.invites.presentPings(pings)
1171 }
1172
1173 await syncEngine.setOnPingDeliveryUpdate { [weak self] update in
1174 guard let self else { return }
1175 switch update.state {
1176 case .queued:
1177 self.inviteDeliveries.markQueued(
1178 recordName: update.recordName,
1179 gameID: update.gameID,
1180 friendAuthorID: update.addressee
1181 )
1182 self.dismissInviteFailureAnnouncement(
1183 gameID: update.gameID,
1184 friendAuthorID: update.addressee
1185 )
1186 case .sent:
1187 self.inviteDeliveries.markSent(
1188 recordName: update.recordName,
1189 gameID: update.gameID,
1190 friendAuthorID: update.addressee
1191 )
1192 self.dismissInviteFailureAnnouncement(
1193 gameID: update.gameID,
1194 friendAuthorID: update.addressee
1195 )
1196 case .failed:
1197 let failure = update.failure ?? .other
1198 self.inviteDeliveries.markFailed(
1199 recordName: update.recordName,
1200 gameID: update.gameID,
1201 friendAuthorID: update.addressee,
1202 failure: failure
1203 )
1204
1205
1206
1207
1208
1209
1210
1211
1212 self.announcements.post(Announcement(
1213 id: InviteDeliveryStore.failureAnnouncementID(
1214 gameID: update.gameID,
1215 friendAuthorID: update.addressee
1216 ),
1217 scope: .global,
1218 severity: .error,
1219 title: String(localized: failure.title),
1220 body: String(localized: failure.body),
1221 dismissal: .manual
1222 ))
1223 if update.rollbackParticipantOnFailure {
1224 Task { @MainActor [weak self] in
1225 await self?.invites.rollbackUndeliveredInvite(
1226 gameID: update.gameID,
1227 friendAuthorID: update.addressee
1228 )
1229 }
1230 }
1231 }
1232 }
1233
1234 await syncEngine.setOnAccountChange { [weak self] in
1235 guard let self else { return }
1236 let previousID = self.identity.currentID
1237 await self.identity.refresh(using: self.ckContainer)
1238 let newID = self.identity.currentID
1239
1240
1241
1242
1243
1244
1245
1246
1247 if Self.accountSwitchRequiresPurge(previousID: previousID, newID: newID) {
1248 do {
1249 try await self.cloudService.purgeLocalData()
1250 } catch {
1251 self.syncMonitor.note("account-switch purge failed — \(error)")
1252 }
1253 }
1254 self.pushClient?.updateAuthorID(newID)
1255
1256
1257 await self.accountPush.reconcilePushRegistration()
1258 }
1259
1260 await syncEngine.setOnGameAccessRevoked { [weak self, store, gameViewedStore, announcements, gameArchiver] gameID in
1261 store.markAccessRevoked(gameID: gameID)
1262
1263
1264 gameViewedStore.advance(Date(), forGame: gameID)
1265
1266
1267
1268
1269
1270
1271
1272
1273 let chronicleID = await gameArchiver.promoteRevoked(gameID: gameID)
1274 if let chronicleID {
1275 if self?.isPuzzleOnScreen(gameID: gameID) == true {
1276 NotificationNavigationBroker.shared.replaceOpenGame(
1277 gameID,
1278 with: chronicleID
1279 )
1280 } else {
1281 await gameArchiver.retireSupersededLiveRow(gameID: gameID)
1282 }
1283 }
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294 if chronicleID == nil {
1295 announcements.post(.accessRevoked(gameID: gameID))
1296 }
1297 await self?.accountPush.reconcilePushRegistration()
1298 }
1299
1300 await syncEngine.setOnGameRemoved { [weak self, store, gameViewedStore, announcements, gameArchiver] gameID in
1301 let wasOpen = store.handleRemoteRemoval(gameID: gameID)
1302
1303
1304
1305
1306 let chronicleID = await gameArchiver.restoreRetired(gameID: gameID)
1307 gameViewedStore.advance(Date(), forGame: gameID)
1308
1309
1310 BadgeState.forget(gameID: gameID)
1311 await self?.badge.refreshAppBadge(reason: "game removed")
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323 if let chronicleID {
1324 if self?.isPuzzleOnScreen(gameID: gameID) == true {
1325 NotificationNavigationBroker.shared.replaceOpenGame(
1326 gameID,
1327 with: chronicleID
1328 )
1329 }
1330 } else if wasOpen {
1331 announcements.post(.gameRemoved(gameID: gameID))
1332 }
1333 await self?.accountPush.reconcilePushRegistration()
1334 }
1335
1336 await syncEngine.setOnGameCompleted { [weak self, gameArchiver] gameID in
1337 await self?.shareController.closeTicketForCompletedGame(gameID: gameID)
1338
1339
1340
1341 self?.store.enqueuePeerChangeLedgerUpdate(for: [gameID])
1342 await gameArchiver.archiveIfNeeded(gameID: gameID)
1343 }
1344
1345 await syncEngine.setOnReplayJournalsSynced { [gameArchiver] gameIDs in
1346 for gameID in gameIDs {
1347 await gameArchiver.archiveIfNeeded(gameID: gameID)
1348 }
1349 }
1350
1351 await syncEngine.setOnCompletionRecordsSaved { [weak self] records in
1352 await self?.sessions.noteCompletionRecordsSaved(records)
1353 }
1354 await sessions.resumePendingCompletionDeliveries()
1355
1356 await syncEngine.setOnGameJoined { [weak self] gameID in
1357 guard let self else { return }
1358
1359
1360
1361
1362
1363 do {
1364 try self.invites.removePendingInvite(forGameID: gameID)
1365
1366 await self.badge.refreshAppBadge(reason: "game joined")
1367 } catch {
1368 self.announcements.post(Announcement(
1369 id: "remove-pending-invite-error-\(gameID.uuidString)",
1370 scope: .global,
1371 severity: .error,
1372 title: "Clearing Failed",
1373 body: error.localizedDescription,
1374 dismissal: .manual
1375 ))
1376 }
1377
1378
1379 Task { @MainActor [weak self] in
1380 await self?.accountPush.reconcilePushRegistration()
1381 }
1382 }
1383
1384
1385
1386
1387 await syncEngine.setOnPingDeleted { [weak self] pings in
1388 guard let self else { return }
1389 try? self.invites.removePendingInvites(forPingRecordNames: Set(pings.map { $0.recordName }))
1390 await self.badge.refreshAppBadge(reason: "ping deleted")
1391 for gameID in Set(pings.map { $0.gameID }) {
1392 await self.badge.dismissDeliveredNotifications(
1393 for: gameID,
1394 publishAccountSeen: false
1395 )
1396 }
1397 }
1398
1399 cloudService.onShareJoined = { [weak self] gameID in
1400 guard let self else { return }
1401
1402
1403
1404 await AppDelegate.requestNotificationAuthorizationIfNeeded()
1405 await self.accountPush.reconcilePushRegistration()
1406
1407
1408
1409 let ownAddress = self.identity.currentID.flatMap {
1410 self.accountPush.setDerivedPushAddress(gameID: gameID, authorID: $0)
1411 }
1412
1413
1414
1415
1416 await self.playerNamePublisher?.publishName(for: gameID)
1417 await self.accountPush.publishAccountJoinedPush(gameID: gameID)
1418
1419 await self.sessions.publishJoinPush(gameID: gameID, excludeAddress: ownAddress)
1420 }
1421
1422
1423
1424
1425
1426 playerNamePublisher = PlayerNamePublisher(
1427 preferences: preferences,
1428 persistence: persistence,
1429 authorIdentity: identity,
1430 enqueuePlayer: { [preferences, syncEngine] gameID, authorID, reason in
1431 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
1432 guard isEnabled else { return }
1433 await syncEngine.enqueuePlayer(
1434 gameID: gameID,
1435 authorID: authorID,
1436 reason: reason
1437 )
1438 },
1439 enqueueNameDecision: { [preferences, syncEngine] authorID, name, version, zoneID, scope in
1440 let isEnabled = await MainActor.run { preferences.isICloudSyncEnabled }
1441 guard isEnabled else { return }
1442 await syncEngine.enqueueNameDecision(
1443 authorID: authorID,
1444 name: name,
1445 version: version,
1446 zoneID: zoneID,
1447 scope: scope
1448 )
1449 }
1450 )
1451
1452
1453
1454
1455
1456
1457
1458 appDelegate.onRemoteNotification = {
1459 summary, scope, event, gameID, kind, senderDeviceID, presenceUntil, isBackground in
1460 await self.handleRemoteNotification(
1461 summary: summary,
1462 scope: scope,
1463 event: event,
1464 gameID: gameID,
1465 kind: kind,
1466 senderDeviceID: senderDeviceID,
1467 presenceUntil: presenceUntil,
1468 isBackground: isBackground
1469 )
1470 }
1471
1472 guard await ensureICloudSyncStarted() else {
1473 syncMonitor.note("iCloud sync disabled — engine startup skipped")
1474 return
1475 }
1476
1477
1478
1479
1480
1481
1482 if let localAuthorID = identity.currentID, !localAuthorID.isEmpty {
1483 Task { [friendController, preferences] in
1484 await friendController.healPendingBootstraps(
1485 localAuthorID: localAuthorID,
1486 localDisplayName: preferences.name
1487 )
1488 }
1489 }
1490
1491
1492
1493 }
1494
1495 func enqueueShareAcceptance(_ metadata: CKShare.Metadata) async {
1496 guard preferences.isICloudSyncEnabled else {
1497 syncMonitor.note("share acceptance ignored while iCloud sync is disabled")
1498 return
1499 }
1500 pendingShareMetadatas.append(metadata)
1501 syncMonitor.note(
1502 "share acceptance queued: container=\(metadata.containerIdentifier)"
1503 )
1504 await processPendingShareAcceptances()
1505 }
1506
1507 func syncOnForeground() async {
1508 importVisibleNotificationReceipts()
1509 await movesUpdater.flush()
1510 guard await ensureICloudSyncStarted() else { return }
1511 let recoveredMoveCount = await syncEngine.enqueueUnconfirmedMoves()
1512 if recoveredMoveCount > 0 {
1513 syncMonitor.note("recovered \(recoveredMoveCount) unconfirmed move(s) for CloudKit enqueue")
1514 }
1515 await syncMonitor.run("foreground push") {
1516 try await syncEngine.pushChanges()
1517 }
1518 if isGameListVisible {
1519 syncMonitor.note("foreground fetch skipped: game list will refresh")
1520 await freshenGameList(reason: .foreground)
1521 return
1522 }
1523 if let (gameID, scope) = activePuzzleGridTarget() {
1524 syncMonitor.note("foreground fetch skipped: active puzzle will refresh")
1525 await freshenPuzzleGrid(gameID: gameID, scope: scope, reason: .foreground)
1526 return
1527 }
1528 await syncMonitor.run("foreground fetch") {
1529 try await syncEngine.fetchChanges(source: "foreground")
1530 }
1531 await refreshSnapshot()
1532 }
1533
1534 private func importVisibleNotificationReceipts() {
1535 for entry in VisibleNotificationReceiptLog.drain() {
1536 eventLog.note(VisibleNotificationReceiptLog.message(for: entry))
1537 }
1538 }
1539
1540
1541
1542
1543 private func isPuzzleOnScreen(gameID: UUID) -> Bool {
1544 mountedPuzzleCounts[gameID, default: 0] > 0
1545 }
1546
1547 func gameListAppeared() async {
1548 isGameListVisible = true
1549
1550
1551
1552
1553 let retirable = await gameArchiver.sweepSupersededLiveGames()
1554 for gameID in retirable where !isPuzzleOnScreen(gameID: gameID) {
1555 await gameArchiver.retireSupersededLiveRow(gameID: gameID)
1556 }
1557 await freshenGameList(reason: .appeared)
1558 }
1559
1560 func gameListDisappeared() {
1561 isGameListVisible = false
1562 }
1563
1564 func puzzleAppeared(gameID: UUID) {
1565 mountedPuzzleCounts[gameID, default: 0] += 1
1566 }
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578 func puzzleDisappeared(gameID: UUID) {
1579 let remaining = max(0, mountedPuzzleCounts[gameID, default: 0] - 1)
1580 if remaining == 0 {
1581 mountedPuzzleCounts[gameID] = nil
1582 } else {
1583 mountedPuzzleCounts[gameID] = remaining
1584 }
1585 guard remaining == 0 else { return }
1586 Task { await gameArchiver.retireSupersededLiveRow(gameID: gameID) }
1587 }
1588
1589 func loadRecentCompleted(since cutoff: Date) async -> GameArchiver.CompletedPage {
1590 guard await ensureICloudSyncStarted() else {
1591 return .init(oldestCompletedAt: nil, hasMore: false)
1592 }
1593 let predecessor = completedPageTask
1594 let task = Task { @MainActor in
1595 if let predecessor { _ = await predecessor.value }
1596 return await gameArchiver.loadRecentCompleted(since: cutoff)
1597 }
1598 let taskID = UUID()
1599 completedPageTask = task
1600 completedPageTaskID = taskID
1601 let page = await task.value
1602 if completedPageTaskID == taskID {
1603 completedPageTask = nil
1604 completedPageTaskID = nil
1605 }
1606 beginRemoteCompletedMigrationIfNeeded()
1607 return page
1608 }
1609
1610 func loadMoreCompleted() async -> GameArchiver.CompletedPage {
1611 guard await ensureICloudSyncStarted() else {
1612 return .init(oldestCompletedAt: nil, hasMore: false)
1613 }
1614 let predecessor = completedPageTask
1615 let task = Task { @MainActor in
1616 if let predecessor { _ = await predecessor.value }
1617 return await gameArchiver.loadMoreCompleted()
1618 }
1619 let taskID = UUID()
1620 completedPageTask = task
1621 completedPageTaskID = taskID
1622 let page = await task.value
1623 if completedPageTaskID == taskID {
1624 completedPageTask = nil
1625 completedPageTaskID = nil
1626 }
1627 return page
1628 }
1629
1630 private func beginRemoteCompletedMigrationIfNeeded() {
1631 guard !hasStartedRemoteCompletedMigration else { return }
1632 hasStartedRemoteCompletedMigration = true
1633 Task { @MainActor [weak self] in
1634 await self?.gameArchiver.migrateMissingCompletedGames()
1635
1636
1637 await self?.gameArchiver.reconcileChronicleLedger()
1638 }
1639 }
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656 func ensureInBackground(_ name: String, _ work: @escaping () async -> Void) {
1657 var token = UIBackgroundTaskIdentifier.invalid
1658 var released = false
1659 func release() {
1660 guard !released, token != .invalid else { return }
1661 released = true
1662 UIApplication.shared.endBackgroundTask(token)
1663 }
1664 token = UIApplication.shared.beginBackgroundTask(withName: name, expirationHandler: release)
1665 Task {
1666 await work()
1667 release()
1668 }
1669 }
1670
1671
1672
1673
1674
1675 func syncOnBackground() {
1676 ensureInBackground("moves-flush") { [weak self] in
1677 await self?.movesUpdater.flush()
1678 }
1679 ensureInBackground("event-log-flush") { [weak self] in
1680 await self?.eventLog.flush()
1681 }
1682 }
1683
1684
1685
1686
1687
1688
1689 func refreshLibrary() async {
1690 await freshenGameList(reason: .manual)
1691 guard await ensureICloudSyncStarted() else { return }
1692 await syncMonitor.run("library refresh: engine fetch") {
1693 try await syncEngine.fetchChanges(source: "library refresh")
1694 }
1695 await refreshSnapshot()
1696 }
1697
1698 func freshenGameList(reason: FreshenReason) async {
1699 guard await ensureICloudSyncStarted() else { return }
1700 if let task = gameListFreshenTask {
1701 syncMonitor.note(
1702 "freshen game list \(reason.diagnosticLabel): coalesced into in-flight freshen"
1703 )
1704 await task.value
1705 return
1706 }
1707
1708 let task = Task { @MainActor in
1709 await self.runFreshenGameList(reason: reason)
1710 }
1711 gameListFreshenTask = task
1712 await task.value
1713 gameListFreshenTask = nil
1714 }
1715
1716 private func runFreshenGameList(reason: FreshenReason) async {
1717
1718
1719
1720 await freshenGameListScope(
1721 .private,
1722 label: "private",
1723 reason: reason
1724 )
1725 await freshenGameListScope(
1726 .shared,
1727 label: "shared",
1728 reason: reason
1729 )
1730 await refreshSnapshot()
1731
1732
1733
1734
1735
1736
1737 await badge.reconcileBadgeLedgerWithDeliveredNotifications()
1738 await badge.refreshAppBadge(reason: "game list freshen")
1739 await reconcilePendingJournalUploads()
1740 if shouldRunColdLaunchArchiveReconcile {
1741 shouldRunColdLaunchArchiveReconcile = false
1742
1743
1744
1745 await gameArchiver.reconcileUnarchived()
1746 }
1747 }
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760 private func reconcilePendingJournalUploads() async {
1761 guard let authorID = identity.currentID, !authorID.isEmpty else { return }
1762 let ctx = persistence.container.newBackgroundContext()
1763 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
1764 let candidates: [UUID] = await ctx.perform {
1765 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
1766 req.predicate = NSPredicate(format: "completedAt != nil AND journalUploaded == NO")
1767 return ((try? ctx.fetch(req)) ?? []).compactMap(\.id)
1768 }
1769 guard !candidates.isEmpty else { return }
1770
1771 var nothingToUpload: [UUID] = []
1772 for gameID in candidates {
1773 if store.localJournalEntries(for: gameID).isEmpty {
1774 nothingToUpload.append(gameID)
1775 } else {
1776 await syncEngine.enqueueJournalUpload(gameID: gameID, authorID: authorID)
1777 }
1778 }
1779 guard !nothingToUpload.isEmpty else { return }
1780
1781
1782
1783 let toMark = nothingToUpload
1784 await ctx.perform {
1785 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
1786 req.predicate = NSPredicate(format: "id IN %@", toMark)
1787 for game in (try? ctx.fetch(req)) ?? [] {
1788 game.journalUploaded = true
1789 }
1790 if ctx.hasChanges { try? ctx.save() }
1791 }
1792 }
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803 func beginCompletionJournalUpload(gameID: UUID, authorID: String) {
1804 ensureInBackground("journal-upload-\(gameID.uuidString)") { [weak self] in
1805 guard let self else { return }
1806
1807
1808
1809
1810
1811 await self.store.flushCompletionWrites()
1812 guard self.preferences.isICloudSyncEnabled else { return }
1813 await self.shareController.closeTicketForCompletedGame(gameID: gameID)
1814 await self.syncEngine.enqueueJournalUpload(gameID: gameID, authorID: authorID)
1815
1816
1817
1818
1819 await self.gameArchiver.archiveIfNeeded(gameID: gameID)
1820 }
1821 }
1822
1823 private func freshenGameList(
1824 scope: CKDatabase.Scope,
1825 reason: FreshenReason
1826 ) async {
1827 let label: String
1828 switch scope {
1829 case .private:
1830 label = "private"
1831 case .shared:
1832 label = "shared"
1833 case .public:
1834 return
1835 @unknown default:
1836 return
1837 }
1838 guard await ensureICloudSyncStarted() else { return }
1839 if let task = gameListFreshenTask {
1840 syncMonitor.note(
1841 "freshen game list \(reason.diagnosticLabel): \(label) coalesced into in-flight freshen"
1842 )
1843 await task.value
1844 return
1845 }
1846 await freshenGameListScope(scope, label: label, reason: reason)
1847 await refreshSnapshot()
1848 }
1849
1850 private func freshenGameListScope(
1851 _ scope: CKDatabase.Scope,
1852 label: String,
1853 reason: FreshenReason
1854 ) async {
1855 let reasonLabel = reason.diagnosticLabel
1856 if !shouldRunGameListFreshen(scope: scope, reason: reason, label: label) {
1857 return
1858 }
1859 guard beginGameListFreshen(scope: scope, label: label, reason: reasonLabel) else {
1860 return
1861 }
1862 defer { endGameListFreshen(scope: scope) }
1863
1864 await syncMonitor.run("freshen game list \(reasonLabel): \(label) discovery") {
1865 _ = try await self.syncEngine.discoverNewZonesDirect(scope: scope)
1866 }
1867 let catchUpResult: Int? = await syncMonitor.run("freshen game list \(reasonLabel): \(label) game/moves") {
1868 try await self.syncEngine.fetchKnownGameMovesDirect(scope: scope)
1869 }
1870 let inviteResult: Int? = await syncMonitor.run("freshen game list \(reasonLabel): \(label) invites") {
1871 try await self.syncEngine.fetchFriendInvitesDirect(scope: scope)
1872 }
1873 if inviteResult != nil {
1874 await badge.refreshAppBadge(reason: "invite freshen")
1875 }
1876 if catchUpResult != nil {
1877 noteGameListFreshenCompleted(scope: scope)
1878 }
1879 }
1880
1881
1882
1883
1884
1885
1886
1887
1888 private func shouldRunGameListFreshen(
1889 scope: CKDatabase.Scope,
1890 reason: FreshenReason,
1891 label: String
1892 ) -> Bool {
1893 if reason == .manual {
1894 return true
1895 }
1896 guard let last = lastGameListFreshenAt(scope: scope) else {
1897 return true
1898 }
1899 if let pushAt = lastRemoteNotificationAt, pushAt > last {
1900 return true
1901 }
1902 let elapsed = Date().timeIntervalSince(last)
1903 if elapsed >= gameListFreshenCooldown {
1904 return true
1905 }
1906 let elapsedSeconds = Int(elapsed.rounded())
1907 syncMonitor.note(
1908 "freshen game list \(reason.diagnosticLabel): \(label) skipped (cooldown, last \(elapsedSeconds)s ago)"
1909 )
1910 return false
1911 }
1912
1913 private func lastGameListFreshenAt(scope: CKDatabase.Scope) -> Date? {
1914 switch scope {
1915 case .private:
1916 return lastPrivateGameListFreshenAt
1917 case .shared:
1918 return lastSharedGameListFreshenAt
1919 case .public:
1920 return nil
1921 @unknown default:
1922 return nil
1923 }
1924 }
1925
1926 private func noteGameListFreshenCompleted(scope: CKDatabase.Scope) {
1927 let now = Date()
1928 switch scope {
1929 case .private:
1930 lastPrivateGameListFreshenAt = now
1931 case .shared:
1932 lastSharedGameListFreshenAt = now
1933 case .public:
1934 return
1935 @unknown default:
1936 return
1937 }
1938 }
1939
1940 private func beginGameListFreshen(
1941 scope: CKDatabase.Scope,
1942 label: String,
1943 reason: String
1944 ) -> Bool {
1945 switch scope {
1946 case .private:
1947 guard !isFresheningPrivateGameList else {
1948 syncMonitor.note("freshen game list \(reason): \(label) coalesced into in-flight freshen")
1949 return false
1950 }
1951 isFresheningPrivateGameList = true
1952 return true
1953 case .shared:
1954 guard !isFresheningSharedGameList else {
1955 syncMonitor.note("freshen game list \(reason): \(label) coalesced into in-flight freshen")
1956 return false
1957 }
1958 isFresheningSharedGameList = true
1959 return true
1960 case .public:
1961 return false
1962 @unknown default:
1963 return false
1964 }
1965 }
1966
1967 private func endGameListFreshen(scope: CKDatabase.Scope) {
1968 switch scope {
1969 case .private:
1970 isFresheningPrivateGameList = false
1971 case .shared:
1972 isFresheningSharedGameList = false
1973 case .public:
1974 return
1975 @unknown default:
1976 return
1977 }
1978 }
1979
1980 func freshenPuzzleGrid(
1981 gameID: UUID,
1982 scope: CKDatabase.Scope,
1983 reason: FreshenReason
1984 ) async {
1985 await movesUpdater.flush()
1986 guard await ensureICloudSyncStarted() else { return }
1987 let label = reason.diagnosticLabel
1988 if reason == .remote,
1989 shouldSkipRecentRemotePuzzleGridFreshen(
1990 gameID: gameID,
1991 scope: scope,
1992 label: label
1993 ) {
1994 return
1995 }
1996 guard beginPuzzleGridFreshen(gameID: gameID, scope: scope, reason: label) else {
1997 return
1998 }
1999 defer {
2000 endPuzzleGridFreshen(gameID: gameID, scope: scope)
2001 if reason == .remote {
2002 noteRemotePuzzleGridFreshenCompleted(gameID: gameID, scope: scope)
2003 }
2004 }
2005
2006 await syncMonitor.run("freshen puzzle grid \(label)") {
2007 let handled = try await syncEngine.fetchGameDirect(
2008 scope: scope,
2009 gameID: gameID
2010 )
2011 if !handled {
2012 try await syncEngine.fetchChanges(source: "puzzle grid \(label)")
2013 }
2014 }
2015 await refreshSnapshot()
2016 }
2017
2018 private func beginPuzzleGridFreshen(
2019 gameID: UUID,
2020 scope: CKDatabase.Scope,
2021 reason: String
2022 ) -> Bool {
2023 let key = puzzleGridFreshenKey(gameID: gameID, scope: scope)
2024 guard !fresheningPuzzleGridKeys.contains(key) else {
2025 syncMonitor.note(
2026 "freshen puzzle grid \(reason): \(scopeLabel(scope)) \(gameID.uuidString.prefix(8)) coalesced into in-flight freshen"
2027 )
2028 return false
2029 }
2030 fresheningPuzzleGridKeys.insert(key)
2031 return true
2032 }
2033
2034 private func endPuzzleGridFreshen(gameID: UUID, scope: CKDatabase.Scope) {
2035 fresheningPuzzleGridKeys.remove(puzzleGridFreshenKey(gameID: gameID, scope: scope))
2036 }
2037
2038 private func shouldSkipRecentRemotePuzzleGridFreshen(
2039 gameID: UUID,
2040 scope: CKDatabase.Scope,
2041 label: String
2042 ) -> Bool {
2043
2044
2045
2046
2047
2048
2049 guard engagementStatus.isLive(gameID: gameID) else { return false }
2050 let key = puzzleGridFreshenKey(gameID: gameID, scope: scope)
2051 guard let last = lastRemotePuzzleGridFreshenAt[key] else { return false }
2052 let elapsed = Date().timeIntervalSince(last)
2053 guard elapsed < remotePuzzleGridFreshenDebounce else { return false }
2054 syncMonitor.note(
2055 "freshen puzzle grid \(label): \(scopeLabel(scope)) \(gameID.uuidString.prefix(8)) skipped (recent remote refresh \(Int(elapsed.rounded()))s ago)"
2056 )
2057 return true
2058 }
2059
2060 private func noteRemotePuzzleGridFreshenCompleted(gameID: UUID, scope: CKDatabase.Scope) {
2061 lastRemotePuzzleGridFreshenAt[puzzleGridFreshenKey(gameID: gameID, scope: scope)] = Date()
2062 }
2063
2064 private func puzzleGridFreshenKey(gameID: UUID, scope: CKDatabase.Scope) -> String {
2065 "\(scopeLabel(scope)):\(gameID.uuidString)"
2066 }
2067
2068 private func scopeLabel(_ scope: CKDatabase.Scope) -> String {
2069 switch scope {
2070 case .private:
2071 return "private"
2072 case .shared:
2073 return "shared"
2074 case .public:
2075 return "public"
2076 @unknown default:
2077 return "unknown"
2078 }
2079 }
2080
2081 func makePlayerRoster(for gameID: UUID, preferences: PlayerPreferences) -> PlayerRoster {
2082 PlayerRoster(
2083 gameID: gameID,
2084 authorIdentity: identity,
2085 preferences: preferences,
2086 persistence: persistence,
2087 container: ckContainer,
2088 engagementStore: engagementStore,
2089 tracer: { [syncMonitor] message in syncMonitor.note(message) }
2090 )
2091 }
2092
2093 private func handleRemoteNotification(
2094 summary: String,
2095 scope: CKDatabase.Scope?,
2096 event: PushPayload.Event?,
2097 gameID: UUID?,
2098 kind: String?,
2099 senderDeviceID: String?,
2100 presenceUntil: Date?,
2101 isBackground: Bool
2102 ) async {
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114 if isBackground {
2115 noteAppForeground(false)
2116 }
2117 guard preferences.isICloudSyncEnabled else {
2118 syncMonitor.note("remote notification ignored while iCloud sync is disabled")
2119 return
2120 }
2121 guard await ensureICloudSyncStarted() else { return }
2122 lastRemoteNotificationAt = Date()
2123 syncMonitor.note("remote notification: \(summary)")
2124
2125 if await handleAccountControlPush(
2126 kind: kind,
2127 gameID: gameID,
2128 senderDeviceID: senderDeviceID,
2129 presenceUntil: presenceUntil
2130 ) {
2131 return
2132 }
2133
2134 if event == .replay {
2135 let label = gameID.map { String($0.uuidString.prefix(8)) } ?? "unknown"
2136 syncMonitor.note("push(replay): syncing game \(label)")
2137 await syncMonitor.run("replay push fetch") {
2138 try await syncEngine.fetchChanges(source: "replay push")
2139 }
2140 await refreshSnapshot()
2141 await reconcilePendingJournalUploads()
2142 return
2143 }
2144
2145 guard let scope, scope != .public else {
2146 await syncMonitor.run("remote-notification fetch") {
2147 try await syncEngine.fetchChanges(source: "push")
2148 }
2149 await refreshSnapshot()
2150 return
2151 }
2152
2153 guard beginRemoteNotificationHandling(scope: scope) else { return }
2154 defer { endRemoteNotificationHandling(scope: scope) }
2155
2156 cancelBackgroundPushCatchUp(scope: scope)
2157
2158
2159
2160
2161
2162 if scope == .shared, isAcceptingSharedGame {
2163 syncMonitor.note("shared remote notification deferred during share acceptance")
2164 scheduleBackgroundPushCatchUp(scope: scope)
2165 await refreshSnapshot()
2166 return
2167 }
2168
2169 if isBackground {
2170 scheduleBackgroundSessionScan(scope: scope)
2171 scheduleBackgroundPushCatchUp(scope: scope)
2172 await refreshSnapshot()
2173 return
2174 }
2175
2176 if isGameListVisible {
2177 syncMonitor.note("remote notification: game list visible, refreshing list only")
2178 await freshenGameList(scope: scope, reason: .remote)
2179 scheduleBackgroundPushCatchUp(scope: scope)
2180 await refreshSnapshot()
2181 return
2182 }
2183
2184 if let activeGameID = activeGameID(in: scope) {
2185
2186
2187
2188
2189 syncMonitor.note("remote notification: active puzzle visible, refreshing game only")
2190 await freshenPuzzleGrid(
2191 gameID: activeGameID,
2192 scope: scope,
2193 reason: .remote
2194 )
2195 } else {
2196
2197
2198
2199
2200
2201 await syncMonitor.run("remote-notification zone discovery") {
2202 _ = try await self.syncEngine.discoverNewZonesDirect(scope: scope)
2203 }
2204 scheduleBackgroundPushCatchUp(scope: scope)
2205 }
2206
2207 await refreshSnapshot()
2208 }
2209
2210 private func handleAccountControlPush(
2211 kind: String?,
2212 gameID: UUID?,
2213 senderDeviceID: String?,
2214 presenceUntil: Date?
2215 ) async -> Bool {
2216 guard let kind,
2217 kind == AccountPushCoordinator.accountJoinedPushKind || kind == AccountPushCoordinator.accountSeenPushKind
2218 else { return false }
2219 if senderDeviceID == RecordSerializer.localDeviceID {
2220 syncMonitor.note("push(\(kind)): ignored self-send")
2221 return true
2222 }
2223 guard let gameID else {
2224 syncMonitor.note("push(\(kind)): ignored (no gameID)")
2225 return true
2226 }
2227
2228 switch kind {
2229 case AccountPushCoordinator.accountJoinedPushKind:
2230 syncMonitor.note("push(accountJoined): sibling joined \(gameID.uuidString.prefix(8))")
2231 await syncMonitor.run("account-joined shared discovery") {
2232 try await syncEngine.fetchChanges(source: "account joined")
2233 }
2234 await freshenGameList(scope: .shared, reason: .remote)
2235 await accountPush.reconcilePushRegistration()
2236 await refreshSnapshot()
2237 case AccountPushCoordinator.accountSeenPushKind:
2238 guard let presenceUntil else {
2239 syncMonitor.note("push(accountSeen): ignored (no presenceUntil)")
2240 return true
2241 }
2242 let (previous, adopted) = store.noteIncomingReadCursor(gameID: gameID, presenceUntil: presenceUntil)
2243 if store.isCompletedGameFamily(gameID: gameID) {
2244
2245
2246
2247
2248
2249 store.advanceReadThrough(
2250 gameID: gameID,
2251 through: min(presenceUntil, Date())
2252 )
2253 }
2254 syncMonitor.note(
2255 "push(accountSeen): sibling saw \(gameID.uuidString.prefix(8)) " +
2256 "presenceUntil=\(presenceUntil.ISO8601Format()) " +
2257 "was=\(previous?.ISO8601Format() ?? "—")" +
2258 (adopted ? "" : " (no-op)")
2259 )
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270 let siblingPresent = presenceUntil > Date()
2271 await badge.dismissDeliveredNotifications(
2272 for: gameID,
2273 seenAt: presenceUntil,
2274 publishAccountSeen: false,
2275 preserveUnread: !siblingPresent
2276 )
2277 default:
2278 break
2279 }
2280 return true
2281 }
2282
2283
2284
2285 private func dismissInviteFailureAnnouncement(gameID: UUID, friendAuthorID: String) {
2286 announcements.dismiss(
2287 id: InviteDeliveryStore.failureAnnouncementID(
2288 gameID: gameID,
2289 friendAuthorID: friendAuthorID
2290 )
2291 )
2292 }
2293
2294 private func activePuzzleGridTarget() -> (UUID, CKDatabase.Scope)? {
2295 guard let entity = store.currentEntity,
2296 let gameID = entity.id,
2297 !store.isGameArchived(entity)
2298 else { return nil }
2299 switch entity.databaseScope {
2300 case 0:
2301 return (gameID, .private)
2302 case 1:
2303 return (gameID, .shared)
2304 default:
2305 return nil
2306 }
2307 }
2308
2309 private func beginRemoteNotificationHandling(scope: CKDatabase.Scope) -> Bool {
2310 switch scope {
2311 case .private:
2312 guard !isHandlingPrivateRemoteNotification else {
2313 syncMonitor.note("private remote notification coalesced into in-flight handler")
2314 return false
2315 }
2316 isHandlingPrivateRemoteNotification = true
2317 return true
2318 case .shared:
2319 guard !isHandlingSharedRemoteNotification else {
2320 syncMonitor.note("shared remote notification coalesced into in-flight handler")
2321 return false
2322 }
2323 isHandlingSharedRemoteNotification = true
2324 return true
2325 case .public:
2326 return false
2327 @unknown default:
2328 return false
2329 }
2330 }
2331
2332 private func endRemoteNotificationHandling(scope: CKDatabase.Scope) {
2333 switch scope {
2334 case .private:
2335 isHandlingPrivateRemoteNotification = false
2336 case .shared:
2337 isHandlingSharedRemoteNotification = false
2338 case .public:
2339 return
2340 @unknown default:
2341 return
2342 }
2343 }
2344
2345 private func cancelBackgroundPushCatchUp(scope: CKDatabase.Scope) {
2346 switch scope {
2347 case .private:
2348 privatePushCatchUpTask?.cancel()
2349 privatePushCatchUpTask = nil
2350 case .shared:
2351 sharedPushCatchUpTask?.cancel()
2352 sharedPushCatchUpTask = nil
2353 case .public:
2354 return
2355 @unknown default:
2356 return
2357 }
2358 }
2359
2360 private func scheduleBackgroundPushCatchUp(scope: CKDatabase.Scope) {
2361 switch scope {
2362 case .private:
2363 privatePushCatchUpTask?.cancel()
2364 privatePushCatchUpTask = makeBackgroundPushCatchUpTask(scope: scope, label: "private")
2365 case .shared:
2366 sharedPushCatchUpTask?.cancel()
2367 sharedPushCatchUpTask = makeBackgroundPushCatchUpTask(scope: scope, label: "shared")
2368 case .public:
2369 return
2370 @unknown default:
2371 return
2372 }
2373 }
2374
2375
2376
2377
2378
2379 private static let backgroundSessionScanDebounce: UInt64 = 5_000_000_000
2380
2381
2382
2383
2384
2385
2386 private func scheduleBackgroundSessionScan(scope: CKDatabase.Scope) {
2387 switch scope {
2388 case .private:
2389 guard privateSessionScanTask == nil else { return }
2390 privateSessionScanTask = makeBackgroundSessionScanTask(scope: scope)
2391 case .shared:
2392 guard sharedSessionScanTask == nil else { return }
2393 sharedSessionScanTask = makeBackgroundSessionScanTask(scope: scope)
2394 case .public:
2395 return
2396 @unknown default:
2397 return
2398 }
2399 }
2400
2401 private func clearBackgroundSessionScanTask(scope: CKDatabase.Scope) {
2402 switch scope {
2403 case .private:
2404 privateSessionScanTask = nil
2405 case .shared:
2406 sharedSessionScanTask = nil
2407 case .public:
2408 return
2409 @unknown default:
2410 return
2411 }
2412 }
2413
2414 private func makeBackgroundSessionScanTask(scope: CKDatabase.Scope) -> Task<Void, Never> {
2415 Task { @MainActor in
2416 defer { clearBackgroundSessionScanTask(scope: scope) }
2417 do {
2418 try await Task.sleep(nanoseconds: Self.backgroundSessionScanDebounce)
2419 } catch {
2420 return
2421 }
2422 guard !Task.isCancelled else { return }
2423 guard await ensureICloudSyncStarted() else { return }
2424 let result = await syncMonitor.run("remote-notification background session scan") {
2425 try await syncEngine.fetchBackgroundSessionsDirect(scope: scope)
2426 }
2427 if let result {
2428
2429
2430
2431
2432 if result.isEmpty {
2433 syncMonitor.note("remote-notification background session scan: no active sessions")
2434 }
2435 }
2436 await refreshSnapshot()
2437 }
2438 }
2439
2440 private func makeBackgroundPushCatchUpTask(
2441 scope: CKDatabase.Scope,
2442 label: String
2443 ) -> Task<Void, Never> {
2444 syncMonitor.note("\(label) game/moves catch-up scheduled")
2445 return Task { @MainActor in
2446 let shortMoveCount = await runBackgroundPushCatchUp(
2447 scope: scope,
2448 label: label,
2449 delayNanoseconds: 5_000_000_000,
2450 phaseSuffix: "short"
2451 )
2452 guard !Task.isCancelled else { return }
2453 guard shortMoveCount == 0 else {
2454 syncMonitor.note(
2455 "\(label) game/moves catch-up long skipped after short fetched \(shortMoveCount) move record(s)"
2456 )
2457 return
2458 }
2459 _ = await runBackgroundPushCatchUp(
2460 scope: scope,
2461 label: label,
2462 delayNanoseconds: 15_000_000_000,
2463 phaseSuffix: "long"
2464 )
2465 }
2466 }
2467
2468 private func runBackgroundPushCatchUp(
2469 scope: CKDatabase.Scope,
2470 label: String,
2471 delayNanoseconds: UInt64,
2472 phaseSuffix: String
2473 ) async -> Int {
2474 do {
2475 try await Task.sleep(nanoseconds: delayNanoseconds)
2476 } catch {
2477 return 0
2478 }
2479 guard !Task.isCancelled else { return 0 }
2480 guard await ensureICloudSyncStarted() else { return 0 }
2481 guard beginGameListFreshen(
2482 scope: scope,
2483 label: label,
2484 reason: "remote \(phaseSuffix) catch-up"
2485 ) else {
2486 return 0
2487 }
2488 defer { endGameListFreshen(scope: scope) }
2489
2490 let moveCount = await syncMonitor.run("remote-notification \(label) game/moves catch-up \(phaseSuffix)") {
2491 try await syncEngine.fetchKnownGameMovesDirect(scope: scope)
2492 }
2493 await refreshSnapshot()
2494 return moveCount ?? 0
2495 }
2496
2497 private func activeGameID(in scope: CKDatabase.Scope) -> UUID? {
2498 guard let target = activePuzzleGridTarget() else { return nil }
2499 return target.1 == scope ? target.0 : nil
2500 }
2501
2502 private func ensureICloudSyncStarted() async -> Bool {
2503 guard preferences.isICloudSyncEnabled else { return false }
2504 guard !syncStarted else { return true }
2505 if let inFlight = syncStartTask { return await inFlight.value }
2506
2507 let task = Task { @MainActor in
2508 await identity.refresh(using: ckContainer)
2509 pushClient?.updateAuthorID(identity.currentID)
2510 await syncEngine.start()
2511 syncStarted = true
2512
2513 let recoveredMoveCount = await syncEngine.enqueueUnconfirmedMoves()
2514 if recoveredMoveCount > 0 {
2515 syncMonitor.note("recovered \(recoveredMoveCount) unconfirmed move(s) for CloudKit enqueue")
2516 }
2517 isReadyForShareAcceptance = true
2518 await processPendingShareAcceptances()
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530 if let authorID = identity.currentID, !authorID.isEmpty,
2531 !accountPush.hasCachedAccountPushCredentials(authorID: authorID) {
2532 await syncMonitor.run("startup account sync") {
2533 try await syncEngine.fetchChanges(source: "startup")
2534 }
2535 }
2536 await accountPush.reconcilePushRegistration()
2537 return true
2538 }
2539 syncStartTask = task
2540 let result = await task.value
2541 syncStartTask = nil
2542 return result
2543 }
2544
2545
2546
2547
2548
2549 static func describePush(userInfo: [AnyHashable: Any]) -> String {
2550 guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo) else {
2551 let kind = (userInfo["kind"] as? String) ?? "<nil>"
2552 let gameID = (userInfo["gameID"] as? String) ?? "<nil>"
2553 return "custom kind=\(kind) gameID=\(gameID)"
2554 }
2555 let kind: String
2556 let scope: CKDatabase.Scope?
2557 switch note {
2558 case let n as CKDatabaseNotification:
2559 kind = "database"
2560 scope = n.databaseScope
2561 case let n as CKRecordZoneNotification:
2562 kind = "recordZone"
2563 scope = n.databaseScope
2564 case let n as CKQueryNotification:
2565 kind = "query(\(n.queryNotificationReason.rawValue))"
2566 scope = n.databaseScope
2567 default:
2568 kind = "type(\(note.notificationType.rawValue))"
2569 scope = nil
2570 }
2571 let scopeLabel: String
2572 switch scope {
2573 case .private: scopeLabel = "private"
2574 case .shared: scopeLabel = "shared"
2575 case .public: scopeLabel = "public"
2576 case .none: scopeLabel = "n/a"
2577 case .some(let other): scopeLabel = "scope(\(other.rawValue))"
2578 }
2579 let sub = note.subscriptionID ?? "<nil>"
2580 return "scope=\(scopeLabel) kind=\(kind) sub=\(sub) pruned=\(note.isPruned)"
2581 }
2582
2583 static func databaseScope(fromPush userInfo: [AnyHashable: Any]) -> CKDatabase.Scope? {
2584 guard let note = CKNotification(fromRemoteNotificationDictionary: userInfo) else {
2585 return nil
2586 }
2587 switch note {
2588 case let n as CKDatabaseNotification:
2589 return n.databaseScope
2590 case let n as CKRecordZoneNotification:
2591 return n.databaseScope
2592 case let n as CKQueryNotification:
2593 return n.databaseScope
2594 default:
2595 return nil
2596 }
2597 }
2598
2599 private func processPendingShareAcceptances() async {
2600 guard isReadyForShareAcceptance, !isProcessingShareAcceptanceQueue else { return }
2601 isProcessingShareAcceptanceQueue = true
2602 isAcceptingSharedGame = true
2603 defer {
2604 isProcessingShareAcceptanceQueue = false
2605 isAcceptingSharedGame = false
2606 }
2607
2608 while !pendingShareMetadatas.isEmpty {
2609 let metadata = pendingShareMetadatas.removeFirst()
2610 do {
2611 let outcome = try await cloudService.acceptShare(metadata: metadata)
2612
2613
2614 if case .pendingSync = outcome {
2615 announcements.post(.puzzleStillSyncing())
2616 }
2617 } catch {
2618
2619
2620
2621
2622 if error is AcceptedShareError {
2623 let copy = CloudFailureCopy.joinFailure(for: error)
2624 announcements.post(Announcement(
2625 id: "os-share-joined-unavailable",
2626 scope: .global,
2627 severity: .error,
2628 title: copy.title,
2629 body: copy.body,
2630 dismissal: .manual
2631 ))
2632 }
2633 }
2634 }
2635 }
2636
2637 private func refreshSnapshot() async {
2638 let snapshot = await syncEngine.diagnosticSnapshot()
2639 syncMonitor.updateSnapshot(snapshot)
2640 }
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650 func noteAppForeground(_ foreground: Bool) {
2651 isAppForeground = foreground
2652 }
2653
2654 func publishReadCursor(
2655 for gameID: UUID,
2656 mode: ReadCursorPublishMode = .activeLease,
2657 requireActivePuzzle: Bool = false
2658 ) async {
2659 guard let authorID = identity.currentID, !authorID.isEmpty else { return }
2660
2661
2662
2663
2664
2665
2666 if case .activeLease = mode, !isAppForeground {
2667 syncMonitor.note("lease(activeLease) skipped for \(gameID.uuidString): backgrounded")
2668 return
2669 }
2670
2671
2672
2673
2674
2675
2676
2677 if case .activeLease = mode,
2678 requireActivePuzzle,
2679 NotificationState.activePuzzleID() != gameID {
2680 syncMonitor.note("lease(activeLease) skipped for \(gameID.uuidString): not active puzzle")
2681 return
2682 }
2683 let now = Date()
2684 let didUpdate: Bool
2685 switch mode {
2686 case .activeLease:
2687 let presenceUntil = now.addingTimeInterval(Self.readLeaseDuration)
2688 didUpdate = store.setReadCursor(
2689 gameID: gameID,
2690 presenceUntil: presenceUntil,
2691 minimumExistingPresenceUntil: now.addingTimeInterval(Self.readLeaseRefreshFloor)
2692 )
2693 if didUpdate {
2694
2695
2696
2697
2698
2699 syncMonitor.note(
2700 "lease MINT[\(gameID.uuidString.prefix(8))] " +
2701 "presenceUntil=\(presenceUntil.ISO8601Format()) foreground=\(isAppForeground) " +
2702 "suppressed=\(NotificationState.isSuppressed(gameID: gameID))"
2703 )
2704
2705
2706
2707
2708 BadgeState.adoptReadHorizon(gameID: gameID, horizon: presenceUntil)
2709 await accountPush.publishAccountSeenPush(gameID: gameID, presenceUntil: presenceUntil)
2710 }
2711 case .currentTime:
2712
2713
2714
2715
2716
2717 let collapsed = store.setReadCursor(gameID: gameID, presenceUntil: now)
2718 let advanced = store.advanceReadThrough(gameID: gameID, through: now)
2719
2720
2721
2722
2723
2724 BadgeState.markSeen(gameID: gameID, at: now)
2725 BadgeState.collapseSuppression(gameID: gameID, to: now)
2726 didUpdate = collapsed || advanced
2727 }
2728 guard didUpdate else { return }
2729 let reason: String
2730 let drain: Bool
2731 switch mode {
2732 case .activeLease:
2733 reason = "lease(activeLease)"
2734 drain = true
2735 case .currentTime:
2736
2737
2738
2739 reason = "lease(currentTime)"
2740 drain = false
2741 }
2742 await syncEngine.enqueuePlayer(
2743 gameID: gameID,
2744 authorID: authorID,
2745 reason: reason,
2746 drain: drain
2747 )
2748 }
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758 func logPlayerLeaseSnapshot(gameID: UUID) async {
2759 let localAuthorID = identity.currentID
2760 let context = persistence.container.newBackgroundContext()
2761 let lines: [String] = await withCheckedContinuation { continuation in
2762 context.perform {
2763 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
2764 req.predicate = NSPredicate(format: "game.id == %@", gameID as CVarArg)
2765 let now = Date()
2766 let players = (try? context.fetch(req)) ?? []
2767 let lines = players.map { player -> String in
2768 let author = player.authorID ?? "?"
2769 let isLocal = author == CKCurrentUserDefaultName
2770 || (localAuthorID.map { author == $0 } ?? false)
2771 let tag = isLocal ? "self" : "peer"
2772 let name = (player.name?.isEmpty == false) ? player.name! : "—"
2773 let presenceUntil = isLocal
2774 ? player.game?.lastReadOtherMoveAt
2775 : player.presenceUntil
2776 guard let presenceUntil else {
2777 return "\(tag) \(author.prefix(8)) [\(name)] presenceUntil=nil"
2778 }
2779 let delta = Int(presenceUntil.timeIntervalSince(now))
2780 let state = delta > 0 ? "present, +\(delta)s" : "absent, \(-delta)s ago"
2781 return "\(tag) \(author.prefix(8)) [\(name)] presenceUntil=\(presenceUntil.ISO8601Format()) (\(state))"
2782 }
2783 continuation.resume(returning: lines)
2784 }
2785 }
2786 syncMonitor.note("open lease snapshot \(gameID.uuidString.prefix(8)): \(lines.count) player(s)")
2787 for line in lines {
2788 syncMonitor.note(" \(line)")
2789 }
2790 }
2791
2792
2793
2794
2795
2796 static func makeOnGameDeleted(
2797 syncEngine: SyncEngine,
2798 cursorStore: GameCursorStore? = nil,
2799 viewedStore: GameViewedStore? = nil
2800 ) -> (GameCloudDeletion) -> Void {
2801 { deletion in
2802 cursorStore?.clearCursor(forGame: deletion.gameID)
2803 viewedStore?.clearLastViewed(forGame: deletion.gameID)
2804 Task { await syncEngine.enqueueDeleteGame(deletion) }
2805 }
2806 }
2807
2808
2809
2810
2811
2812
2813
2814
2815 static func hasPresentPeer(
2816 persistence: PersistenceController,
2817 gameID: UUID,
2818 localAuthorID: String?
2819 ) async -> Bool {
2820 let context = persistence.container.newBackgroundContext()
2821 return await withCheckedContinuation { continuation in
2822 context.perform {
2823 let now = Date()
2824 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
2825 req.predicate = NSPredicate(
2826 format: "game.id == %@ AND presenceUntil > %@",
2827 gameID as CVarArg,
2828 PeerPresence.presenceCutoff(asOf: now) as NSDate
2829 )
2830 let players = (try? context.fetch(req)) ?? []
2831 let hasPeer = players.contains { player in
2832 guard let authorID = player.authorID, !authorID.isEmpty else { return false }
2833 if authorID == CKCurrentUserDefaultName { return false }
2834 if let localAuthorID, !localAuthorID.isEmpty, authorID == localAuthorID { return false }
2835 return PeerPresence.isPresent(presenceUntil: player.presenceUntil, asOf: now)
2836 }
2837 continuation.resume(returning: hasPeer)
2838 }
2839 }
2840 }
2841
2842
2843
2844
2845
2846
2847 static func soonestPeerLease(
2848 persistence: PersistenceController,
2849 gameID: UUID,
2850 localAuthorID: String?
2851 ) async -> Date? {
2852 let context = persistence.container.newBackgroundContext()
2853 return await withCheckedContinuation { continuation in
2854 context.perform {
2855 let now = Date()
2856 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
2857 req.predicate = NSPredicate(
2858 format: "game.id == %@ AND presenceUntil > %@",
2859 gameID as CVarArg,
2860 PeerPresence.presenceCutoff(asOf: now) as NSDate
2861 )
2862 var soonest: Date?
2863 for player in (try? context.fetch(req)) ?? [] {
2864 guard let authorID = player.authorID, !authorID.isEmpty else { continue }
2865 if authorID == CKCurrentUserDefaultName { continue }
2866 if let localAuthorID, !localAuthorID.isEmpty, authorID == localAuthorID { continue }
2867 guard let presenceUntil = player.presenceUntil,
2868 PeerPresence.isPresent(presenceUntil: presenceUntil, asOf: now) else { continue }
2869 if soonest == nil || presenceUntil < soonest! { soonest = presenceUntil }
2870 }
2871 continuation.resume(returning: soonest)
2872 }
2873 }
2874 }
2875
2876 static func presentPeers(
2877 persistence: PersistenceController,
2878 gameIDs: Set<UUID>?,
2879 localAuthorID: String?
2880 ) async -> [UUID: [String]] {
2881 let context = persistence.container.newBackgroundContext()
2882 return await withCheckedContinuation { continuation in
2883 context.perform {
2884 let now = Date()
2885 let req = NSFetchRequest<PlayerEntity>(entityName: "PlayerEntity")
2886 var predicates = [
2887 NSPredicate(format: "presenceUntil > %@", PeerPresence.presenceCutoff(asOf: now) as NSDate)
2888 ]
2889 if let gameIDs, !gameIDs.isEmpty {
2890 predicates.append(NSPredicate(format: "game.id IN %@", Array(gameIDs)))
2891 }
2892 if let localAuthorID, !localAuthorID.isEmpty {
2893 predicates.append(NSPredicate(format: "authorID != %@", localAuthorID))
2894 }
2895 req.predicate = NSCompoundPredicate(andPredicateWithSubpredicates: predicates)
2896
2897 var result: [UUID: Set<String>] = [:]
2898 for player in (try? context.fetch(req)) ?? [] {
2899 guard let gameID = player.game?.id,
2900 let authorID = player.authorID,
2901 !authorID.isEmpty,
2902 authorID != CKCurrentUserDefaultName,
2903 PeerPresence.isPresent(presenceUntil: player.presenceUntil, asOf: now) else { continue }
2904 result[gameID, default: []].insert(authorID)
2905 }
2906 continuation.resume(returning: result.mapValues { Array($0) })
2907 }
2908 }
2909 }
2910
2911}