Crossmate/Sync/SyncEngine.swift (138532B)
1import CloudKit
2import CoreData
3import Foundation
4import SwiftUI
5
6enum CompletionDurableRecordKind: String, Codable, Hashable, Sendable {
7 case game
8 case moves
9 case journal
10}
11
12enum PingDeliveryState: Sendable {
13 case queued
14 case sent
15 case failed
16}
17
18enum InviteDeliveryFailure: Equatable, Sendable {
19 case quotaExceeded
20 case other
21
22 var title: LocalizedStringResource {
23 "Invitation Not Sent"
24 }
25
26 var body: LocalizedStringResource {
27 switch self {
28 case .quotaExceeded:
29 "The invitation was not received. This could be because your friend's iCloud storage is full."
30 case .other:
31 "The invitation could not be delivered. Try again."
32 }
33 }
34
35 init(error: Error) {
36 if let pingError = error as? SyncEngine.PingOutboxError,
37 pingError.isQuotaExceeded {
38 self = .quotaExceeded
39 } else {
40 self = .other
41 }
42 }
43}
44
45struct PingDeliveryUpdate: Sendable {
46 let recordName: String
47 let gameID: UUID
48 let addressee: String
49 let state: PingDeliveryState
50 let rollbackParticipantOnFailure: Bool
51 let failure: InviteDeliveryFailure?
52}
53
54extension EnvironmentValues {
55 @Entry var syncEngine: SyncEngine? = nil
56}
57
58extension Notification.Name {
59
60
61
62
63
64
65
66 static let playerRosterShouldRefresh = Notification.Name("playerRosterShouldRefresh")
67
68
69
70
71
72 static let replayJournalDidSync = Notification.Name("replayJournalDidSync")
73
74
75
76 static let chronicleZoneDidChange = Notification.Name("chronicleZoneDidChange")
77}
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92actor SyncEngine {
93 enum PingOutboxError: Error, Equatable, LocalizedError {
94 case syncEngineUnavailable
95 case deliveryFailed(code: Int?)
96
97
98
99 case deliveryPending
100
101 var errorDescription: String? {
102 switch self {
103 case .syncEngineUnavailable:
104 return String(localized: "The invitation could not be queued for syncing.")
105 case .deliveryFailed(let code)
106 where code == CKError.quotaExceeded.rawValue:
107 return String(localized: InviteDeliveryFailure.quotaExceeded.body)
108 case .deliveryFailed:
109 return String(localized: InviteDeliveryFailure.other.body)
110 case .deliveryPending:
111 return String(localized: "The invitation is queued and will keep trying.")
112 }
113 }
114
115 var isQuotaExceeded: Bool {
116 if case .deliveryFailed(let code) = self {
117 return code == CKError.quotaExceeded.rawValue
118 }
119 return false
120 }
121 }
122
123 let container: CKContainer
124 let persistence: PersistenceController
125
126 var privateEngine: CKSyncEngine?
127 var sharedEngine: CKSyncEngine?
128
129
130
131
132
133
134
135
136
137 private lazy var syncStateContext: NSManagedObjectContext = {
138 let ctx = persistence.container.newBackgroundContext()
139 ctx.automaticallyMergesChangesFromParent = true
140 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
141 return ctx
142 }()
143
144
145
146
147
148 private var isStarting = false
149
150
151
152
153
154 private var pendingPings: [String: PingPayload] = [:]
155 private var pingDeliveryWaiters: [
156 String: CheckedContinuation<Void, Error>
157 ] = [:]
158 private var pingDeliveryTimeouts: [String: Task<Void, Never>] = [:]
159 private var scheduledPingRetries: Set<String> = []
160
161
162
163
164
165 private var pingConfirmationTimeout: Duration = .seconds(30)
166
167 private lazy var pendingPingContext: NSManagedObjectContext = {
168 let ctx = persistence.container.newBackgroundContext()
169 ctx.automaticallyMergesChangesFromParent = true
170 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
171 return ctx
172 }()
173
174
175
176
177
178
179
180
181
182
183 private var pendingDecisionPayloads: [String: String] = [:]
184
185 private static let pendingDecisionPayloadsDefaultsKey =
186 "SyncEngine.pendingDecisionPayloads"
187
188
189
190
191
192
193
194 private var pendingDecisionVersions: [String: Int64] = [:]
195
196 private static let pendingDecisionVersionsDefaultsKey =
197 "SyncEngine.pendingDecisionVersions"
198
199
200
201
202
203
204
205
206
207
208 private var decisionSystemFields: [String: Data] = [:]
209
210
211
212
213 nonisolated static func decisionStateKey(_ recordID: CKRecord.ID) -> String {
214 "\(recordID.zoneID.zoneName)/\(recordID.recordName)"
215 }
216
217 struct PingPayload: Codable {
218 let gameID: UUID
219 let authorID: String
220 let deviceID: String
221 let playerName: String
222 let puzzleTitle: String
223 let eventTimestampMs: Int64
224 let kind: PingKind
225 let payload: String?
226 let addressee: String?
227 let zoneName: String
228 let zoneOwnerName: String
229 let databaseScope: DatabaseScope
230
231
232
233 let rollbackParticipantOnFailure: Bool?
234
235 var recordZoneID: CKRecordZone.ID {
236 CKRecordZone.ID(zoneName: zoneName, ownerName: zoneOwnerName)
237 }
238 }
239
240
241
242
243 private var currentFetchSource: String?
244
245
246
247 private var privateCompletedFetchExclusions: Set<CKRecordZone.ID>?
248 private var sharedCompletedFetchExclusions: Set<CKRecordZone.ID>?
249
250
251
252 private var loggedFirstSharedPushPayload = false
253
254 var onRemoteMovesUpdated: (@MainActor @Sendable (Set<UUID>) async -> Void)?
255
256
257
258
259
260 var onRemotePlayersUpdated: (@MainActor @Sendable (Set<UUID>) async -> Void)?
261
262
263
264
265 var onRemotePlayerPresenceChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
266
267
268
269 var onRemoteEngagementChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
270
271
272
273 var onPushCredentialRotationNeeded: (@MainActor @Sendable (Set<UUID>) async -> Void)?
274
275
276
277
278
279 var onRemoteCredentialsChanged: (@MainActor @Sendable (Set<UUID>) async -> Void)?
280 var onPings: (@MainActor @Sendable ([Ping]) async -> Void)?
281 private var onPingDeliveryUpdate: (@MainActor @Sendable (PingDeliveryUpdate) -> Void)?
282 private var onAccountChange: (@MainActor @Sendable () async -> Void)?
283 private var onGameAccessRevoked: (@MainActor @Sendable (UUID) async -> Void)?
284 private var onGameRemoved: (@MainActor @Sendable (UUID) async -> Void)?
285
286
287
288 var onGameCompleted: (@MainActor @Sendable (UUID) async -> Void)?
289
290
291 private var onReplayJournalsSynced:
292 (@MainActor @Sendable (Set<UUID>) async -> Void)?
293 private var onCompletionRecordsSaved: (@MainActor @Sendable ([UUID: Set<CompletionDurableRecordKind>]) async -> Void)?
294
295
296
297 private var onGameJoined: (@MainActor @Sendable (UUID) async -> Void)?
298
299
300
301 var onPingDeleted: (@MainActor @Sendable ([(recordName: String, gameID: UUID)]) async -> Void)?
302
303
304
305
306 var onIncomingReadCursor: (@MainActor @Sendable ([(UUID, Date, Date?)]) async -> Void)?
307 var onAccountPushAddress: (@MainActor @Sendable (String) async -> Void)?
308 var onAccountPushSecret: (@MainActor @Sendable (String, Int64) async -> Void)?
309 var onBlockedFriendsChanged: (@MainActor @Sendable (Set<String>) async -> Void)?
310 var onGameVisibilityCandidates: (@MainActor @Sendable (Set<UUID>) async -> Void)?
311 private var localAuthorIDProvider: (@MainActor @Sendable () -> String?)?
312 private var tracer: (@MainActor @Sendable (String) -> Void)?
313
314
315
316
317
318 private var successCheckpoint: (@MainActor @Sendable () -> Void)?
319 var liveQueryCheckpoints: [String: Date] = [:]
320 let liveQueryCheckpointOverlap: TimeInterval = 5
321
322
323
324
325 var pingPushCheckpoints: [DatabaseScope: Date] = [:]
326 let pingPushCheckpointOverlap: TimeInterval = 30
327
328
329
330
331
332
333 var seenPingRecords: [DatabaseScope: [String: Date]] = [:]
334 let backgroundSessionLookback: TimeInterval = 10 * 60
335
336 func setTracer(_ t: @MainActor @Sendable @escaping (String) -> Void) {
337 tracer = t
338 }
339
340 func setSuccessCheckpoint(_ cb: @MainActor @Sendable @escaping () -> Void) {
341 successCheckpoint = cb
342 }
343
344 private func noteRoundTripSuccess() async {
345 guard let successCheckpoint else { return }
346 await successCheckpoint()
347 }
348
349 func setOnRemoteMovesUpdated(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
350 onRemoteMovesUpdated = cb
351 }
352
353 func setOnRemotePlayersUpdated(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
354 onRemotePlayersUpdated = cb
355 }
356
357 func setOnRemotePlayerPresenceChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
358 onRemotePlayerPresenceChanged = cb
359 }
360
361 func setOnRemoteEngagementChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
362 onRemoteEngagementChanged = cb
363 }
364
365 func setOnPushCredentialRotationNeeded(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
366 onPushCredentialRotationNeeded = cb
367 }
368
369 func setOnRemoteCredentialsChanged(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
370 onRemoteCredentialsChanged = cb
371 }
372
373 func setOnPings(_ cb: @MainActor @Sendable @escaping ([Ping]) async -> Void) {
374 onPings = cb
375 }
376
377 func setOnPingDeliveryUpdate(
378 _ cb: @MainActor @Sendable @escaping (PingDeliveryUpdate) -> Void
379 ) {
380 onPingDeliveryUpdate = cb
381 }
382
383 func setOnAccountChange(_ cb: @MainActor @Sendable @escaping () async -> Void) {
384 onAccountChange = cb
385 }
386
387 func setOnGameAccessRevoked(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
388 onGameAccessRevoked = cb
389 }
390
391 func setOnGameRemoved(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
392 onGameRemoved = cb
393 }
394
395 func setOnGameCompleted(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
396 onGameCompleted = cb
397 }
398
399 func setOnReplayJournalsSynced(
400 _ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void
401 ) {
402 onReplayJournalsSynced = cb
403 }
404
405 func setOnCompletionRecordsSaved(
406 _ cb: @MainActor @Sendable @escaping ([UUID: Set<CompletionDurableRecordKind>]) async -> Void
407 ) {
408 onCompletionRecordsSaved = cb
409 }
410
411 func setOnGameJoined(_ cb: @MainActor @Sendable @escaping (UUID) async -> Void) {
412 onGameJoined = cb
413 }
414
415 func setOnPingDeleted(
416 _ cb: @MainActor @Sendable @escaping ([(recordName: String, gameID: UUID)]) async -> Void
417 ) {
418 onPingDeleted = cb
419 }
420
421 func setOnIncomingReadCursor(_ cb: @MainActor @Sendable @escaping ([(UUID, Date, Date?)]) async -> Void) {
422 onIncomingReadCursor = cb
423 }
424
425 func setOnAccountPushAddress(_ cb: @MainActor @Sendable @escaping (String) async -> Void) {
426 onAccountPushAddress = cb
427 }
428
429 func setOnAccountPushSecret(_ cb: @MainActor @Sendable @escaping (String, Int64) async -> Void) {
430 onAccountPushSecret = cb
431 }
432
433 func setOnBlockedFriendsChanged(_ cb: @MainActor @Sendable @escaping (Set<String>) async -> Void) {
434 onBlockedFriendsChanged = cb
435 }
436
437 func setOnGameVisibilityCandidates(_ cb: @MainActor @Sendable @escaping (Set<UUID>) async -> Void) {
438 onGameVisibilityCandidates = cb
439 }
440
441 func setLocalAuthorIDProvider(_ cb: @MainActor @Sendable @escaping () -> String?) {
442 localAuthorIDProvider = cb
443 }
444
445 init(container: CKContainer, persistence: PersistenceController) {
446 self.container = container
447 self.persistence = persistence
448 }
449
450
451
452
453
454
455
456
457 func start() async {
458 guard privateEngine == nil, sharedEngine == nil, !isStarting else { return }
459 isStarting = true
460 defer { isStarting = false }
461
462
463
464
465 await restorePendingPings()
466 restorePendingDecisionPayloads()
467 restorePendingDecisionVersions()
468
469 let ctx = syncStateContext
470 let (privateData, sharedData): (Data?, Data?) = await ctx.perform {
471 let entity = SyncStateEntity.current(in: ctx)
472 return (entity.ckPrivateEngineState, entity.ckSharedEngineState)
473 }
474
475 let privateState = await decodeEngineState(privateData, label: "private")
476 privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
477 database: container.privateCloudDatabase,
478 stateSerialization: privateState,
479 delegate: self
480 ))
481
482 let sharedState = await decodeEngineState(sharedData, label: "shared")
483 sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
484 database: container.sharedCloudDatabase,
485 stateSerialization: sharedState,
486 delegate: self
487 ))
488
489
490
491
492
493 reconcilePendingPingOutbox()
494 }
495
496
497
498
499
500
501
502
503 private func sendChangesDetached(on engine: CKSyncEngine) {
504 let scope = scope(for: engine)
505 if sendChangesInFlight.contains(scope) {
506 sendChangesPending.insert(scope)
507 return
508 }
509 sendChangesInFlight.insert(scope)
510 Task.detached { [engine] in
511 try? await engine.sendChanges()
512 await self.finishDetachedSendChanges(for: scope)
513 }
514 }
515
516
517
518
519
520
521
522
523
524
525
526 private nonisolated func scope(for engine: CKSyncEngine) -> DatabaseScope {
527 DatabaseScope(isPrivate: engine.database.databaseScope == .private)
528 }
529
530 private func finishDetachedSendChanges(for scope: DatabaseScope) {
531 sendChangesInFlight.remove(scope)
532 guard sendChangesPending.remove(scope) != nil else { return }
533 let engine = scope == .shared ? sharedEngine : privateEngine
534 guard let engine else { return }
535 sendChangesDetached(on: engine)
536 }
537
538
539
540
541
542
543
544
545
546
547 private var playerSendBurstDepth: [DatabaseScope: Int] = [:]
548 private var playerSendBurstPending: Set<DatabaseScope> = []
549 private var sendChangesInFlight: Set<DatabaseScope> = []
550 private var sendChangesPending: Set<DatabaseScope> = []
551
552
553
554
555
556
557
558 func beginPlayerSendBurst(gameID: UUID) -> DatabaseScope? {
559 let ctx = persistence.container.newBackgroundContext()
560 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return nil }
561 playerSendBurstDepth[info.scope, default: 0] += 1
562 return info.scope
563 }
564
565
566
567
568 func endPlayerSendBurst(scope: DatabaseScope) {
569 guard let depth = playerSendBurstDepth[scope], depth > 0 else { return }
570 if depth > 1 {
571 playerSendBurstDepth[scope] = depth - 1
572 return
573 }
574 playerSendBurstDepth.removeValue(forKey: scope)
575 guard playerSendBurstPending.remove(scope) != nil else { return }
576 let engine = scope == .shared ? sharedEngine : privateEngine
577 guard let engine else { return }
578 sendChangesDetached(on: engine)
579 }
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600 func enqueueMoves(gameIDs: Set<UUID>, drain: Bool = true) async {
601 guard !gameIDs.isEmpty else { return }
602
603
604
605
606
607
608
609
610 let localAuthorID = await currentLocalAuthorID()
611 let ctx = persistence.container.newBackgroundContext()
612 let (privateRecordIDs, sharedRecordIDs): ([CKRecord.ID], [CKRecord.ID]) = await ctx.perform {
613 var privateIDs: [CKRecord.ID] = []
614 var sharedIDs: [CKRecord.ID] = []
615 for gameID in gameIDs {
616 guard let info = self.zoneInfo(forGameID: gameID, in: ctx) else { continue }
617 let isShared = info.scope == .shared
618 let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
619 if let localAuthorID, !localAuthorID.isEmpty {
620 req.predicate = NSPredicate(
621 format: "game.id == %@ AND deviceID == %@ AND authorID == %@",
622 gameID as CVarArg,
623 RecordSerializer.localDeviceID,
624 localAuthorID
625 )
626 } else {
627 req.predicate = NSPredicate(
628 format: "game.id == %@ AND deviceID == %@",
629 gameID as CVarArg,
630 RecordSerializer.localDeviceID
631 )
632 }
633 req.fetchLimit = 1
634 guard let entity = try? ctx.fetch(req).first,
635 let recordName = entity.ckRecordName
636 else { continue }
637 let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
638 if isShared {
639 sharedIDs.append(recordID)
640 } else {
641 privateIDs.append(recordID)
642 }
643 }
644 return (privateIDs, sharedIDs)
645 }
646 if !privateRecordIDs.isEmpty, let engine = privateEngine {
647 engine.state.add(
648 pendingRecordZoneChanges: privateRecordIDs.map { .saveRecord($0) }
649 )
650 if drain { sendChangesDetached(on: engine) }
651 }
652 if !sharedRecordIDs.isEmpty, let engine = sharedEngine {
653 engine.state.add(
654 pendingRecordZoneChanges: sharedRecordIDs.map { .saveRecord($0) }
655 )
656 if drain { sendChangesDetached(on: engine) }
657 }
658 }
659
660
661
662
663
664
665
666 @discardableResult
667 func enqueueUnconfirmedMoves() async -> Int {
668 let localAuthorID = await currentLocalAuthorID()
669 let ctx = persistence.container.newBackgroundContext()
670 let gameIDs: Set<UUID> = await ctx.perform {
671 let req = NSFetchRequest<MovesEntity>(entityName: "MovesEntity")
672 if let localAuthorID, !localAuthorID.isEmpty {
673 req.predicate = NSPredicate(
674 format: "ckSystemFields == nil AND deviceID == %@ AND authorID == %@",
675 RecordSerializer.localDeviceID,
676 localAuthorID
677 )
678 } else {
679 req.predicate = NSPredicate(
680 format: "ckSystemFields == nil AND deviceID == %@",
681 RecordSerializer.localDeviceID
682 )
683 }
684 let entities = (try? ctx.fetch(req)) ?? []
685 return Set(entities.compactMap { $0.game?.id })
686 }
687 await enqueueMoves(gameIDs: gameIDs)
688 return gameIDs.count
689 }
690
691
692
693
694
695
696 func enqueueDeleteGame(_ deletion: GameCloudDeletion) {
697 if deletion.deletesLiveZone {
698 let zoneID = CKRecordZone.ID(
699 zoneName: deletion.ckZoneName,
700 ownerName: deletion.ckZoneOwnerName
701 )
702 let engine = deletion.databaseScope == .shared ? sharedEngine : privateEngine
703 if let engine {
704 engine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
705 sendChangesDetached(on: engine)
706 }
707 }
708
709 guard let privateEngine else { return }
710 if let archiveRecordName = deletion.archiveRecordName {
711 let recordID = CKRecord.ID(
712 recordName: archiveRecordName,
713 zoneID: Archive.zoneID
714 )
715 privateEngine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
716 }
717 if let legacyZoneName = deletion.legacyArchiveZoneName {
718 let legacyZoneID = CKRecordZone.ID(
719 zoneName: legacyZoneName,
720 ownerName: CKCurrentUserDefaultName
721 )
722 privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(legacyZoneID)])
723 }
724 sendChangesDetached(on: privateEngine)
725 }
726
727
728
729
730 func enqueueRetireOwnedGameZone(_ zoneID: CKRecordZone.ID) {
731 guard let privateEngine else { return }
732 privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
733 sendChangesDetached(on: privateEngine)
734 }
735
736
737
738 func enqueueDeleteLegacyArchiveZone(_ zoneID: CKRecordZone.ID) {
739 guard let privateEngine else { return }
740 privateEngine.state.add(pendingDatabaseChanges: [.deleteZone(zoneID)])
741 sendChangesDetached(on: privateEngine)
742 }
743
744 private func storePendingPing(
745 _ ping: PingPayload,
746 recordName: String
747 ) async throws {
748 let data = try JSONEncoder().encode(ping)
749 let ctx = pendingPingContext
750 try await ctx.perform {
751 let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
752 req.predicate = NSPredicate(format: "recordName == %@", recordName)
753 req.fetchLimit = 1
754 let entity = try ctx.fetch(req).first ?? PendingPingEntity(context: ctx)
755 entity.recordName = recordName
756 entity.zoneName = ping.zoneName
757 entity.zoneOwnerName = ping.zoneOwnerName
758 entity.databaseScope = ping.databaseScope.rawValue
759 entity.payloadData = data
760 try ctx.save()
761 }
762 pendingPings[recordName] = ping
763 await publishPingDeliveryUpdate(.queued, recordName: recordName, ping: ping)
764 }
765
766 private func removePendingPing(recordName: String) async {
767 pendingPings.removeValue(forKey: recordName)
768 let ctx = pendingPingContext
769 await ctx.perform {
770 let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
771 req.predicate = NSPredicate(format: "recordName == %@", recordName)
772 for entity in (try? ctx.fetch(req)) ?? [] {
773 ctx.delete(entity)
774 }
775 if ctx.hasChanges { try? ctx.save() }
776 }
777 }
778
779 private func confirmPendingPing(recordName: String) async {
780 scheduledPingRetries.remove(recordName)
781 if let ping = pendingPings[recordName] {
782 await publishPingDeliveryUpdate(.sent, recordName: recordName, ping: ping)
783 }
784 await removePendingPing(recordName: recordName)
785 clearPingDeliveryTimeout(recordName: recordName)
786 pingDeliveryWaiters.removeValue(forKey: recordName)?.resume()
787 }
788
789 private func failPendingPing(recordName: String, error: NSError? = nil) async {
790 scheduledPingRetries.remove(recordName)
791 if let ping = pendingPings[recordName] {
792 let failure: InviteDeliveryFailure = error?.code
793 == CKError.quotaExceeded.rawValue ? .quotaExceeded : .other
794 await publishPingDeliveryUpdate(
795 .failed,
796 recordName: recordName,
797 ping: ping,
798 failure: failure
799 )
800 }
801 await removePendingPing(recordName: recordName)
802 clearPingDeliveryTimeout(recordName: recordName)
803 pingDeliveryWaiters.removeValue(forKey: recordName)?
804 .resume(throwing: PingOutboxError.deliveryFailed(code: error?.code))
805 }
806
807 private func waitForPingDelivery(recordName: String) async throws {
808 try await withTaskCancellationHandler {
809 try await withCheckedThrowingContinuation { continuation in
810 pingDeliveryWaiters[recordName] = continuation
811 armPingDeliveryTimeout(recordName: recordName)
812 }
813 } onCancel: {
814 Task { await self.cancelPingDeliveryWait(recordName: recordName) }
815 }
816 }
817
818 private func cancelPingDeliveryWait(recordName: String) {
819 clearPingDeliveryTimeout(recordName: recordName)
820 pingDeliveryWaiters.removeValue(forKey: recordName)?
821 .resume(throwing: CancellationError())
822 }
823
824
825
826
827
828 private func armPingDeliveryTimeout(recordName: String) {
829 pingDeliveryTimeouts[recordName]?.cancel()
830 pingDeliveryTimeouts[recordName] = Task { [self] in
831 try? await Task.sleep(for: pingConfirmationTimeout)
832 guard !Task.isCancelled else { return }
833 timeoutPingDeliveryWait(recordName: recordName)
834 }
835 }
836
837 private func clearPingDeliveryTimeout(recordName: String) {
838 pingDeliveryTimeouts.removeValue(forKey: recordName)?.cancel()
839 }
840
841 private func timeoutPingDeliveryWait(recordName: String) {
842 pingDeliveryTimeouts.removeValue(forKey: recordName)
843 pingDeliveryWaiters.removeValue(forKey: recordName)?
844 .resume(throwing: PingOutboxError.deliveryPending)
845 }
846
847 private func restorePendingPings() async {
848 let ctx = pendingPingContext
849 pendingPings = await ctx.perform {
850 let req = NSFetchRequest<PendingPingEntity>(entityName: "PendingPingEntity")
851 let rows = (try? ctx.fetch(req)) ?? []
852 var restored: [String: PingPayload] = [:]
853 for row in rows {
854 guard let name = row.recordName,
855 let data = row.payloadData,
856 let ping = try? JSONDecoder().decode(PingPayload.self, from: data)
857 else {
858 ctx.delete(row)
859 continue
860 }
861 restored[name] = ping
862 }
863 if ctx.hasChanges { try? ctx.save() }
864 return restored
865 }
866 for (recordName, ping) in pendingPings {
867 await publishPingDeliveryUpdate(.queued, recordName: recordName, ping: ping)
868 }
869 }
870
871 private func publishPingDeliveryUpdate(
872 _ state: PingDeliveryState,
873 recordName: String,
874 ping: PingPayload,
875 failure: InviteDeliveryFailure? = nil
876 ) async {
877 guard ping.kind == .invite,
878 let addressee = ping.addressee,
879 !addressee.isEmpty,
880 let onPingDeliveryUpdate
881 else { return }
882 await onPingDeliveryUpdate(PingDeliveryUpdate(
883 recordName: recordName,
884 gameID: ping.gameID,
885 addressee: addressee,
886 state: state,
887 rollbackParticipantOnFailure: ping.rollbackParticipantOnFailure == true,
888 failure: failure
889 ))
890 }
891
892 private func reconcilePendingPingOutbox() {
893 for (recordName, ping) in pendingPings {
894 let engine = ping.databaseScope == .shared ? sharedEngine : privateEngine
895 let recordID = CKRecord.ID(recordName: recordName, zoneID: ping.recordZoneID)
896 engine?.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
897 }
898 }
899
900 func pendingInvitationPingCount() -> Int {
901 pendingPings.values.count { $0.kind == PingKind.invite }
902 }
903
904
905
906
907
908
909 @discardableResult
910 func enqueuePing(
911 kind: PingKind,
912 gameID: UUID,
913 authorID: String,
914 playerName: String,
915 payload: String? = nil,
916 addressee: String? = nil
917 ) async -> Bool {
918 let ctx = persistence.container.newBackgroundContext()
919 let zoneAndTitle: (info: ZoneInfo, title: String)? = await ctx.perform {
920 guard let info = self.zoneInfo(forGameID: gameID, in: ctx) else { return nil }
921 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
922 req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
923 req.fetchLimit = 1
924 let entity = try? ctx.fetch(req).first
925 let title = PuzzleNotificationText.title(for: entity)
926 return (info, title)
927 }
928 guard let zoneAndTitle else {
929 await trace(
930 "ping send: SKIPPED kind=\(kind.rawValue) " +
931 "game=\(gameID.uuidString) " +
932 "— no zone info (game not yet synced/shared on this device)"
933 )
934 return false
935 }
936 let engine = zoneAndTitle.info.scope == .shared ? sharedEngine : privateEngine
937 guard let engine else {
938 await trace(
939 "ping send: SKIPPED kind=\(kind.rawValue) " +
940 "game=\(gameID.uuidString) " +
941 "— no CKSyncEngine for " +
942 "\(zoneAndTitle.info.scope == .shared ? "shared" : "private") scope"
943 )
944 return false
945 }
946 let deviceID = RecordSerializer.localDeviceID
947 let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
948 let recordName = RecordSerializer.recordName(
949 forPingInGame: gameID,
950 authorID: authorID,
951 deviceID: deviceID,
952 eventTimestampMs: eventTimestampMs
953 )
954 let ping = PingPayload(
955 gameID: gameID,
956 authorID: authorID,
957 deviceID: deviceID,
958 playerName: playerName,
959 puzzleTitle: zoneAndTitle.title,
960 eventTimestampMs: eventTimestampMs,
961 kind: kind,
962 payload: payload,
963 addressee: addressee,
964 zoneName: zoneAndTitle.info.zoneID.zoneName,
965 zoneOwnerName: zoneAndTitle.info.zoneID.ownerName,
966 databaseScope: zoneAndTitle.info.scope,
967 rollbackParticipantOnFailure: nil
968 )
969 do {
970 try await storePendingPing(ping, recordName: recordName)
971 } catch {
972 await trace("ping send: failed to persist outbox record \(recordName) — \(error)")
973 return false
974 }
975 let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneAndTitle.info.zoneID)
976 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
977 await trace(
978 "ping send: enqueued kind=\(kind.rawValue) " +
979 "game=\(gameID.uuidString) " +
980 "target=\(zoneAndTitle.info.scope == .shared ? "shared" : "private") " +
981 "zone=\(zoneAndTitle.info.zoneID.zoneName) record=\(recordName)"
982 )
983 sendChangesDetached(on: engine)
984 return true
985 }
986
987
988
989
990
991
992
993
994
995
996
997
998 func enqueueFriendZonePing(
999 kind: PingKind,
1000 gameID: UUID,
1001 gameTitle: String,
1002 authorID: String,
1003 playerName: String,
1004 addressee: String,
1005 friendZoneID: CKRecordZone.ID,
1006 friendZoneScope: DatabaseScope,
1007 payload: String? = nil,
1008 rollbackParticipantOnFailure: Bool = false,
1009 waitForServerConfirmation: Bool = false
1010 ) async throws {
1011 let engine = friendZoneScope == .shared ? sharedEngine : privateEngine
1012 guard let engine else {
1013 throw PingOutboxError.syncEngineUnavailable
1014 }
1015 let deviceID = RecordSerializer.localDeviceID
1016 let eventTimestampMs = Int64(Date().timeIntervalSince1970 * 1000)
1017 let recordName = RecordSerializer.recordName(
1018 forPingInGame: gameID,
1019 authorID: authorID,
1020 deviceID: deviceID,
1021 eventTimestampMs: eventTimestampMs
1022 )
1023 let ping = PingPayload(
1024 gameID: gameID,
1025 authorID: authorID,
1026 deviceID: deviceID,
1027 playerName: playerName,
1028 puzzleTitle: gameTitle,
1029 eventTimestampMs: eventTimestampMs,
1030 kind: kind,
1031 payload: payload,
1032 addressee: addressee,
1033 zoneName: friendZoneID.zoneName,
1034 zoneOwnerName: friendZoneID.ownerName,
1035 databaseScope: friendZoneScope,
1036 rollbackParticipantOnFailure: rollbackParticipantOnFailure
1037 )
1038 try await storePendingPing(ping, recordName: recordName)
1039 let recordID = CKRecord.ID(recordName: recordName, zoneID: friendZoneID)
1040 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
1041 sendChangesDetached(on: engine)
1042 if waitForServerConfirmation {
1043 try await waitForPingDelivery(recordName: recordName)
1044 }
1045 }
1046
1047
1048
1049
1050
1051
1052
1053 func enqueueDecision(
1054 kind: String,
1055 key: String,
1056 payload: String? = nil,
1057 version: Int64? = nil
1058 ) {
1059 guard let engine = privateEngine else { return }
1060 let zoneID = RecordSerializer.accountZoneID
1061
1062
1063 engine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: zoneID))])
1064 registerDecisionSave(
1065 kind: kind, key: key, payload: payload, version: version,
1066 zoneID: zoneID, engine: engine
1067 )
1068 }
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079 @discardableResult
1080 func enqueueFriendDecision(
1081 kind: String,
1082 key: String,
1083 payload: String? = nil,
1084 version: Int64? = nil,
1085 friendZoneID: CKRecordZone.ID,
1086 friendZoneScope: DatabaseScope
1087 ) -> Bool {
1088 guard let engine = friendZoneScope == .shared ? sharedEngine : privateEngine else { return false }
1089 registerDecisionSave(
1090 kind: kind, key: key, payload: payload, version: version,
1091 zoneID: friendZoneID, engine: engine
1092 )
1093 return true
1094 }
1095
1096
1097
1098
1099 func enqueueNameDecision(
1100 authorID: String,
1101 name: String,
1102 version: Int64,
1103 zoneID: CKRecordZone.ID,
1104 scope: DatabaseScope
1105 ) {
1106 if zoneID == RecordSerializer.accountZoneID {
1107 enqueueDecision(
1108 kind: RecordSerializer.nameDecisionKind,
1109 key: authorID,
1110 payload: name,
1111 version: version
1112 )
1113 } else {
1114 enqueueFriendDecision(
1115 kind: RecordSerializer.nameDecisionKind,
1116 key: authorID,
1117 payload: name,
1118 version: version,
1119 friendZoneID: zoneID,
1120 friendZoneScope: scope
1121 )
1122 }
1123 }
1124
1125 private func registerDecisionSave(
1126 kind: String,
1127 key: String,
1128 payload: String?,
1129 version: Int64?,
1130 zoneID: CKRecordZone.ID,
1131 engine: CKSyncEngine
1132 ) {
1133 let name = RecordSerializer.decisionRecordName(kind: kind, key: key)
1134 let recordID = CKRecord.ID(recordName: name, zoneID: zoneID)
1135 let stateKey = Self.decisionStateKey(recordID)
1136 if let payload {
1137 pendingDecisionPayloads[stateKey] = payload
1138 persistPendingDecisionPayloads()
1139 }
1140 if let version {
1141 pendingDecisionVersions[stateKey] = version
1142 persistPendingDecisionVersions()
1143 }
1144 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
1145 sendChangesDetached(on: engine)
1146 }
1147
1148
1149
1150
1151
1152 func enqueueDecisionDeletion(kind: String, key: String) {
1153 guard let engine = privateEngine else { return }
1154 let name = RecordSerializer.decisionRecordName(kind: kind, key: key)
1155 let recordID = CKRecord.ID(recordName: name, zoneID: RecordSerializer.accountZoneID)
1156 engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
1157 sendChangesDetached(on: engine)
1158 }
1159
1160
1161
1162
1163 private func persistPendingDecisionPayloads() {
1164 if pendingDecisionPayloads.isEmpty {
1165 UserDefaults.standard.removeObject(
1166 forKey: Self.pendingDecisionPayloadsDefaultsKey
1167 )
1168 } else {
1169 UserDefaults.standard.set(
1170 pendingDecisionPayloads,
1171 forKey: Self.pendingDecisionPayloadsDefaultsKey
1172 )
1173 }
1174 }
1175
1176 private func restorePendingDecisionPayloads() {
1177 pendingDecisionPayloads = (UserDefaults.standard.dictionary(
1178 forKey: Self.pendingDecisionPayloadsDefaultsKey
1179 ) as? [String: String]) ?? [:]
1180 }
1181
1182
1183
1184 private func persistPendingDecisionVersions() {
1185 if pendingDecisionVersions.isEmpty {
1186 UserDefaults.standard.removeObject(
1187 forKey: Self.pendingDecisionVersionsDefaultsKey
1188 )
1189 } else {
1190 UserDefaults.standard.set(
1191 pendingDecisionVersions.mapValues { NSNumber(value: $0) },
1192 forKey: Self.pendingDecisionVersionsDefaultsKey
1193 )
1194 }
1195 }
1196
1197 private func restorePendingDecisionVersions() {
1198 let raw = (UserDefaults.standard.dictionary(
1199 forKey: Self.pendingDecisionVersionsDefaultsKey
1200 ) as? [String: NSNumber]) ?? [:]
1201 pendingDecisionVersions = raw.mapValues { $0.int64Value }
1202 }
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216 func deletePing(recordName: String, gameID: UUID) async {
1217 let ctx = persistence.container.newBackgroundContext()
1218 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
1219 let engine = info.scope == .shared ? sharedEngine : privateEngine
1220 guard let engine else { return }
1221 await failPendingPing(recordName: recordName)
1222 let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
1223 engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
1224 sendChangesDetached(on: engine)
1225 }
1226
1227
1228
1229
1230
1231 func deletePing(recordName: String, zoneID: CKRecordZone.ID, databaseScope: DatabaseScope) async {
1232 let engine = databaseScope == .shared ? sharedEngine : privateEngine
1233 guard let engine else { return }
1234 await failPendingPing(recordName: recordName)
1235 let recordID = CKRecord.ID(recordName: recordName, zoneID: zoneID)
1236 engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)])
1237 sendChangesDetached(on: engine)
1238 }
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254 func enqueuePlayer(gameID: UUID, authorID: String, reason: String, drain: Bool = true) async {
1255 let ctx = persistence.container.newBackgroundContext()
1256 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
1257
1258
1259
1260
1261
1262
1263
1264 guard !info.isAccessRevoked else {
1265 await trace(
1266 "enqueue Player[\(gameID.uuidString.prefix(8))] skipped " +
1267 "(access revoked) reason=\(reason)"
1268 )
1269 return
1270 }
1271 let engine = info.scope == .shared ? sharedEngine : privateEngine
1272 guard let engine else { return }
1273 let recordName = RecordSerializer.recordName(forPlayerInGame: gameID, authorID: authorID)
1274 let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
1275 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
1276 await trace("enqueue Player[\(gameID.uuidString.prefix(8))] reason=\(reason)")
1277
1278
1279
1280 guard drain else { return }
1281 if (playerSendBurstDepth[info.scope] ?? 0) > 0 {
1282 playerSendBurstPending.insert(info.scope)
1283 } else {
1284 sendChangesDetached(on: engine)
1285 }
1286 }
1287
1288
1289
1290 func enqueueGame(ckRecordName: String) {
1291 guard let gameID = gameID(fromRecordName: ckRecordName) else { return }
1292 let ctx = persistence.container.newBackgroundContext()
1293 guard let info = zoneInfo(forGameID: gameID, in: ctx) else { return }
1294 let engine = info.scope == .shared ? sharedEngine : privateEngine
1295 guard let engine else { return }
1296
1297 engine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: info.zoneID))])
1298 let recordID = CKRecord.ID(recordName: ckRecordName, zoneID: info.zoneID)
1299 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
1300 sendChangesDetached(on: engine)
1301 }
1302
1303
1304
1305
1306
1307
1308
1309
1310 func enqueueJournalUpload(gameID: UUID, authorID: String) {
1311 let ctx = persistence.container.newBackgroundContext()
1312 guard let info = zoneInfo(forGameID: gameID, in: ctx),
1313 !info.isAccessRevoked else { return }
1314
1315
1316
1317
1318 let engine = info.scope == .shared ? sharedEngine : privateEngine
1319 guard let engine else { return }
1320 let recordName = RecordSerializer.recordName(
1321 forJournalInGame: gameID,
1322 authorID: authorID,
1323 deviceID: RecordSerializer.localDeviceID
1324 )
1325 let recordID = CKRecord.ID(recordName: recordName, zoneID: info.zoneID)
1326 engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
1327 sendChangesDetached(on: engine)
1328 }
1329
1330
1331
1332 func fetchChanges(source: String = "manual") async throws {
1333 currentFetchSource = source
1334 defer { currentFetchSource = nil }
1335 async let p: Void = privateEngine?.fetchChanges() ?? ()
1336 async let s: Void = sharedEngine?.fetchChanges() ?? ()
1337 _ = try await (p, s)
1338 }
1339
1340
1341
1342
1343
1344
1345 func fetchChangesForGame(
1346 scope: CKDatabase.Scope,
1347 gameID: UUID,
1348 source: String = "manual"
1349 ) async throws -> Bool {
1350 let engine: CKSyncEngine?
1351 let scopeValue: DatabaseScope
1352 switch scope {
1353 case .private:
1354 engine = privateEngine
1355 scopeValue = .private
1356 case .shared:
1357 engine = sharedEngine
1358 scopeValue = .shared
1359 case .public:
1360 return false
1361 @unknown default:
1362 return false
1363 }
1364 guard let engine else { return false }
1365 let ctx = persistence.container.newBackgroundContext()
1366 guard let info = zoneInfo(forGameID: gameID, in: ctx),
1367 info.scope == scopeValue
1368 else { return false }
1369 currentFetchSource = source
1370 defer { currentFetchSource = nil }
1371 let options = CKSyncEngine.FetchChangesOptions(scope: .zoneIDs([info.zoneID]))
1372 try await engine.fetchChanges(options)
1373 return true
1374 }
1375
1376 func pushChanges() async throws {
1377 async let p: Void = privateEngine?.sendChanges() ?? ()
1378 async let s: Void = sharedEngine?.sendChanges() ?? ()
1379 _ = try await (p, s)
1380 }
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392 func resetSyncState() async {
1393 let ctx = syncStateContext
1394 let failureMessage: String? = await ctx.perform {
1395 let entity = SyncStateEntity.current(in: ctx)
1396 entity.ckPrivateEngineState = nil
1397 entity.ckSharedEngineState = nil
1398 do {
1399 try ctx.save()
1400 return nil
1401 } catch {
1402 return "resetSyncState ctx.save failed — \(error)"
1403 }
1404 }
1405 if let failureMessage { await trace(failureMessage) }
1406 privateEngine = CKSyncEngine(CKSyncEngine.Configuration(
1407 database: container.privateCloudDatabase,
1408 stateSerialization: nil,
1409 delegate: self
1410 ))
1411 sharedEngine = CKSyncEngine(CKSyncEngine.Configuration(
1412 database: container.sharedCloudDatabase,
1413 stateSerialization: nil,
1414 delegate: self
1415 ))
1416 reconcilePendingPingOutbox()
1417 pendingDecisionPayloads = [:]
1418 persistPendingDecisionPayloads()
1419 pendingDecisionVersions = [:]
1420 persistPendingDecisionVersions()
1421 decisionSystemFields = [:]
1422 pingPushCheckpoints = [:]
1423 seenPingRecords = [:]
1424 liveQueryCheckpoints = [:]
1425 loggedFirstSharedPushPayload = false
1426 playerSendBurstDepth = [:]
1427 playerSendBurstPending = []
1428 _ = await enqueueUnconfirmedMoves()
1429 }
1430
1431
1432
1433 func currentLocalAuthorID() async -> String? {
1434 guard let localAuthorIDProvider else { return nil }
1435 return await MainActor.run {
1436 localAuthorIDProvider()
1437 }
1438 }
1439
1440
1441 func trace(_ message: String) async {
1442 guard let tracer else { return }
1443 await tracer(message)
1444 }
1445
1446
1447
1448
1449
1450 private func decodeEngineState(_ data: Data?, label: String) async -> CKSyncEngine.State.Serialization? {
1451 guard let data else { return nil }
1452 do {
1453 return try JSONDecoder().decode(CKSyncEngine.State.Serialization.self, from: data)
1454 } catch {
1455 await trace("\(label) engine state decode failed (\(data.count) bytes) — cold-starting sync: \(describe(error))")
1456 return nil
1457 }
1458 }
1459
1460 private func saveEngineState(
1461 _ serialization: CKSyncEngine.State.Serialization,
1462 isPrivate: Bool
1463 ) async {
1464 let ctx = syncStateContext
1465 let failureMessage: String? = await ctx.perform {
1466 guard let data = try? JSONEncoder().encode(serialization) else {
1467 return "saveEngineState encode failed — engine state not persisted"
1468 }
1469 let entity = SyncStateEntity.current(in: ctx)
1470 if isPrivate {
1471 entity.ckPrivateEngineState = data
1472 } else {
1473 entity.ckSharedEngineState = data
1474 }
1475 do {
1476 try ctx.save()
1477 return nil
1478 } catch {
1479 return "saveEngineState ctx.save failed — \(error)"
1480 }
1481 }
1482 if let failureMessage { await trace(failureMessage) }
1483 }
1484
1485 private func handleFetchedDatabaseChanges(
1486 _ event: CKSyncEngine.Event.FetchedDatabaseChanges,
1487 isPrivate: Bool
1488 ) async {
1489 let src = currentFetchSource ?? "framework"
1490 await trace(
1491 "\(isPrivate ? "private" : "shared") db changes [src=\(src)]: " +
1492 "\(event.modifications.count) zone mods, \(event.deletions.count) zone deletions"
1493 )
1494 await noteRoundTripSuccess()
1495 if isPrivate {
1496 privateCompletedFetchExclusions = nil
1497 } else {
1498 sharedCompletedFetchExclusions = nil
1499 }
1500
1501 if isPrivate,
1502 event.modifications.contains(where: {
1503 $0.zoneID.zoneName == Archive.zoneName
1504 }) {
1505 await MainActor.run {
1506 NotificationCenter.default.post(name: .chronicleZoneDidChange, object: nil)
1507 }
1508 }
1509
1510
1511
1512
1513
1514
1515
1516
1517 let ctx = persistence.container.newBackgroundContext()
1518 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
1519 let deletedGameZones = Set(event.deletions.map(\.zoneID).filter {
1520 $0.zoneName.hasPrefix("game-")
1521 })
1522 let (rejoinedIDs, failureMessages): ([UUID], [String]) = await ctx.perform {
1523 var rejoined: [UUID] = []
1524 var messages: [String] = []
1525 if !isPrivate {
1526 for mod in event.modifications {
1527 let zoneID = mod.zoneID
1528 let zoneName = zoneID.zoneName
1529 guard zoneName.hasPrefix("game-") else { continue }
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541 guard zoneID.ownerName != CKCurrentUserDefaultName else {
1542 messages.append(
1543 "refused shared placeholder for own-owner zone \(zoneName)"
1544 )
1545 continue
1546 }
1547 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
1548 req.predicate = NSPredicate(format: "ckZoneName == %@", zoneName)
1549 req.fetchLimit = 1
1550 if (try? ctx.fetch(req).first) == nil {
1551
1552 let entity = GameEntity(context: ctx)
1553 let uuidString = String(zoneName.dropFirst("game-".count))
1554 let gid = UUID(uuidString: uuidString)
1555 entity.id = gid
1556 entity.ckRecordName = zoneName
1557 entity.ckZoneName = zoneName
1558 entity.ckZoneOwnerName = zoneID.ownerName
1559 entity.databaseScope = 1
1560 entity.syncVersion = GameSyncVersion.legacy
1561 entity.title = "Joining\u{2026}"
1562 entity.puzzleSource = ""
1563 entity.createdAt = Date()
1564 entity.updatedAt = Date()
1565
1566
1567
1568
1569
1570
1571 if let gid { rejoined.append(gid) }
1572 }
1573 }
1574 }
1575 if ctx.hasChanges {
1576 do {
1577 try ctx.save()
1578 } catch {
1579
1580
1581
1582 let nsError = error as NSError
1583 messages.append(
1584 "db-changes ctx.save FAILED — domain=\(nsError.domain) " +
1585 "code=\(nsError.code) \(nsError.localizedDescription)"
1586 )
1587 }
1588 }
1589 return (rejoined, messages)
1590 }
1591
1592 for message in failureMessages {
1593 await trace(message)
1594 }
1595 if !deletedGameZones.isEmpty {
1596 await applyZoneOrphaning(deletedGameZones, isPrivate: isPrivate, source: "fetch")
1597 }
1598
1599
1600
1601 for id in rejoinedIDs {
1602 enqueueDecisionDeletion(kind: "left", key: id.uuidString)
1603 if let cb = onGameJoined { await cb(id) }
1604 }
1605 }
1606
1607 private func handleFetchedRecordZoneChanges(
1608 _ event: CKSyncEngine.Event.FetchedRecordZoneChanges,
1609 isPrivate: Bool
1610 ) async {
1611 let scope = DatabaseScope(isPrivate: isPrivate)
1612 let src = currentFetchSource ?? "framework"
1613 await trace(
1614 "\(isPrivate ? "private" : "shared") fetch [src=\(src)]: " +
1615 "\(event.modifications.count) modifications, \(event.deletions.count) deletions"
1616 )
1617 await noteRoundTripSuccess()
1618 if !isPrivate, !loggedFirstSharedPushPayload, src == "push",
1619 event.modifications.count + event.deletions.count > 0 {
1620 loggedFirstSharedPushPayload = true
1621 await trace("✅ first shared-DB push payload received — silent-push path is live")
1622 }
1623
1624 let ctx = persistence.container.newBackgroundContext()
1625 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
1626 let localAuthorID = await currentLocalAuthorID()
1627 let effects: BatchEffects = await ctx.perform {
1628 var effects = BatchEffects()
1629 for mod in event.modifications {
1630 let record = mod.record
1631 guard !RecordSerializer.isGameScopedRecordType(record.recordType)
1632 || RecordSerializer.isTrustedGameScopedRecord(record)
1633 else {
1634 effects.traces.append(
1635 "rejected untrusted fetched record \(record.recordType) " +
1636 "\(record.recordID.recordName) in \(record.recordID.zoneID.zoneName)"
1637 )
1638 continue
1639 }
1640 switch record.recordType {
1641 case "Game":
1642 let entity = RecordSerializer.applyGameRecord(
1643 record,
1644 to: ctx,
1645 databaseScope: scope,
1646 onEngagementChange: { effects.engagementChanged.insert($0) },
1647 onCompletedTransition: { effects.completedTransitions.insert($0) },
1648 onContentKeyChange: { effects.contentKeysChanged.insert($0) },
1649 onStaleCredentials: { effects.staleCredentialRecords.insert($0) },
1650 onDiagnostic: { effects.traces.append($0) }
1651 )
1652 if let id = entity.id {
1653 effects.rosterRelevant.insert(id)
1654 effects.visibilityCandidateGameIDs.insert(id)
1655 }
1656 case "Moves":
1657 if let value = RecordSerializer.parseMovesRecord(record) {
1658 effects.visibilityCandidateGameIDs.insert(value.gameID)
1659 let cellsChanged = RecordSerializer.applyMovesRecord(
1660 record,
1661 value: value,
1662 to: ctx,
1663 databaseScope: scope,
1664 localAuthorID: localAuthorID,
1665 onNewAuthor: { _ in effects.rosterRelevant.insert(value.gameID) }
1666 )
1667 if cellsChanged { effects.movesUpdated.insert(value.gameID) }
1668 }
1669 case "Player":
1670 if let (gameID, _) = RecordSerializer.parsePlayerRecordName(record.recordID.recordName) {
1671 effects.visibilityCandidateGameIDs.insert(gameID)
1672 self.applyPlayerRecord(
1673 record,
1674 in: ctx,
1675 databaseScope: scope,
1676 localAuthorID: localAuthorID,
1677 onFirstTime: { effects.playersUpdated.insert($0) },
1678 onPresenceChange: { effects.playerPresenceChanged.insert($0) },
1679 onReadCursor: { effects.readCursors.append(($0, $1, $2)) }
1680 )
1681 effects.rosterRelevant.insert(gameID)
1682 }
1683 case "Ping":
1684 if let ping = Ping.parseRecord(record, fetchedFrom: isPrivate ? .private : .shared) {
1685 effects.pings.append(ping)
1686 }
1687 case "Decision":
1688 if let address = RecordSerializer.parseAccountPushAddressDecision(record, databaseScope: scope) {
1689 effects.accountPushAddresses.append(address)
1690 }
1691 if let parsed = RecordSerializer.parseAccountPushSecretDecision(record, databaseScope: scope) {
1692 effects.accountPushSecrets.append(parsed)
1693 }
1694 let wrote = RecordSerializer.applyDecisionRecord(
1695 record,
1696 to: ctx,
1697 localAuthorID: localAuthorID,
1698 databaseScope: scope
1699 )
1700
1701
1702
1703
1704
1705
1706 effects.traces.append(
1707 "decision applied=\(wrote) " +
1708 "\(record.recordID.recordName) " +
1709 "zone=\(record.recordID.zoneID.zoneName)/" +
1710 "\(record.recordID.zoneID.ownerName) scope=\(scope)"
1711 )
1712
1713
1714
1715
1716 if let (subject, _, version) = RecordSerializer.parseNameDecision(record),
1717 let localAuthorID, subject == localAuthorID {
1718 effects.selfNameVersions.append(version)
1719 }
1720
1721
1722
1723 if wrote,
1724 let (dKind, dKey) = RecordSerializer.parseDecisionRecordName(
1725 record.recordID.recordName
1726 ) {
1727 if dKind == "left", let gid = UUID(uuidString: dKey) {
1728 effects.removed.insert(gid)
1729 }
1730 if dKind == RecordSerializer.blockDecisionKind {
1731 effects.blockedFriendAuthorIDs.insert(dKey)
1732 }
1733
1734
1735
1736 if dKind == RecordSerializer.nameDecisionKind
1737 || dKind == RecordSerializer.nicknameDecisionKind {
1738 effects.friendNamesChanged = true
1739 }
1740 }
1741 case "Journal":
1742
1743
1744
1745
1746
1747
1748 if let (gid, _, _) = RecordSerializer.parseJournalRecordName(
1749 record.recordID.recordName
1750 ) {
1751 effects.journalsSynced.insert(gid)
1752 }
1753 case Archive.recordType, Archive.legacyRecordType:
1754
1755
1756
1757
1758 if let id = self.applyArchiveRecord(
1759 record,
1760 in: ctx,
1761 onDiagnostic: { effects.traces.append($0) }
1762 ) {
1763 effects.rosterRelevant.insert(id)
1764 effects.visibilityCandidateGameIDs.insert(id)
1765 }
1766 case CKRecord.SystemType.share:
1767
1768
1769
1770
1771
1772 if let share = record as? CKShare,
1773 let gameID = self.applyShareRecord(share, databaseScope: scope, in: ctx) {
1774 effects.credentialRotations.insert(gameID)
1775 effects.traces.append(
1776 "share roster shrank for \(gameID.uuidString) — rotating push credentials"
1777 )
1778 }
1779 default:
1780 break
1781 }
1782 }
1783 for deletion in event.deletions {
1784 guard !RecordSerializer.isGameScopedRecordType(deletion.recordType)
1785 || RecordSerializer.isTrustedGameScopedDeletion(
1786 recordID: deletion.recordID,
1787 recordType: deletion.recordType
1788 )
1789 else {
1790 effects.traces.append(
1791 "rejected untrusted fetched deletion \(deletion.recordType) " +
1792 "\(deletion.recordID.recordName) in \(deletion.recordID.zoneID.zoneName)"
1793 )
1794 continue
1795 }
1796 self.applyDeletion(
1797 recordID: deletion.recordID,
1798 recordType: deletion.recordType,
1799 databaseScope: scope,
1800 in: ctx
1801 )
1802 if let id = self.gameID(fromRecordName: deletion.recordID.recordName) {
1803 effects.rosterRelevant.insert(id)
1804 effects.visibilityCandidateGameIDs.insert(id)
1805 }
1806 }
1807 for gameID in effects.movesUpdated {
1808 effects.traces += self.replayCellCache(for: gameID, in: ctx)
1809 }
1810
1811
1812
1813
1814
1815
1816
1817 if ctx.hasChanges {
1818 do {
1819 try ctx.save()
1820 } catch {
1821 let nsError = error as NSError
1822 effects.traces.append(
1823 "fetchedRecordZoneChanges ctx.save FAILED " +
1824 "— domain=\(nsError.domain) code=\(nsError.code) " +
1825 "\(nsError.localizedDescription)"
1826 )
1827 }
1828 }
1829
1830
1831 if !effects.contentKeysChanged.isEmpty {
1832 GameEntity.rebuildContentKeyDirectory(in: ctx)
1833 }
1834 return effects
1835 }
1836
1837 for message in effects.traces {
1838 await trace(message)
1839 }
1840 if let onGameVisibilityCandidates, !effects.visibilityCandidateGameIDs.isEmpty {
1841 await onGameVisibilityCandidates(effects.visibilityCandidateGameIDs)
1842 }
1843 if let onRemoteMovesUpdated, !effects.movesUpdated.isEmpty {
1844 await onRemoteMovesUpdated(effects.movesUpdated)
1845 }
1846 if let onRemotePlayersUpdated, !effects.playersUpdated.isEmpty {
1847 await onRemotePlayersUpdated(effects.playersUpdated)
1848 }
1849 if let onRemotePlayerPresenceChanged, !effects.playerPresenceChanged.isEmpty {
1850 await onRemotePlayerPresenceChanged(effects.playerPresenceChanged)
1851 }
1852 if let onRemoteEngagementChanged, !effects.engagementChanged.isEmpty {
1853 await onRemoteEngagementChanged(effects.engagementChanged)
1854 }
1855 if let onPushCredentialRotationNeeded, !effects.credentialRotations.isEmpty {
1856 await onPushCredentialRotationNeeded(effects.credentialRotations)
1857 }
1858 if let onRemoteCredentialsChanged, !effects.contentKeysChanged.isEmpty {
1859 await onRemoteCredentialsChanged(effects.contentKeysChanged)
1860 }
1861 if let onIncomingReadCursor, !effects.readCursors.isEmpty {
1862 await onIncomingReadCursor(effects.readCursors)
1863 }
1864 if let onPings, !effects.pings.isEmpty {
1865 await onPings(effects.pings)
1866 }
1867 if let onAccountPushAddress {
1868 for address in effects.accountPushAddresses {
1869 await onAccountPushAddress(address)
1870 }
1871 }
1872
1873
1874
1875
1876
1877 if let onAccountPushSecret {
1878 for entry in effects.accountPushSecrets {
1879 await onAccountPushSecret(entry.secret, entry.version)
1880 }
1881 }
1882 if let localAuthorID, !localAuthorID.isEmpty,
1883 let maxVersion = effects.selfNameVersions.max() {
1884 NameVersionStore.adopt(maxVersion, authorID: localAuthorID)
1885 }
1886 if effects.friendNamesChanged {
1887 let mirrorCtx = persistence.container.newBackgroundContext()
1888 await mirrorCtx.perform {
1889 FriendEntity.rebuildNicknameDirectory(in: mirrorCtx)
1890 }
1891 }
1892 if !effects.blockedFriendAuthorIDs.isEmpty {
1893 await onBlockedFriendsChanged?(effects.blockedFriendAuthorIDs)
1894 }
1895 for id in effects.removed {
1896 if let cb = onGameRemoved { await cb(id) }
1897 }
1898
1899
1900
1901 for recordName in effects.staleCredentialRecords {
1902 enqueueGame(ckRecordName: recordName)
1903 }
1904
1905
1906
1907
1908 if let localAuthorID, !localAuthorID.isEmpty {
1909 for id in effects.completedTransitions {
1910 enqueueJournalUpload(gameID: id, authorID: localAuthorID)
1911 }
1912 }
1913 if let onGameCompleted {
1914 for id in effects.completedTransitions {
1915 await onGameCompleted(id)
1916 }
1917 }
1918 let deletedPings = event.deletions.compactMap { deletion -> (recordName: String, gameID: UUID)? in
1919 let recordName = deletion.recordID.recordName
1920 guard recordName.hasPrefix("ping-"),
1921 let gameID = gameID(fromRecordName: recordName)
1922 else { return nil }
1923 return (recordName, gameID)
1924 }
1925 if let onPingDeleted, !deletedPings.isEmpty {
1926 await onPingDeleted(deletedPings)
1927 }
1928 if !effects.rosterRelevant.isEmpty {
1929 NotificationCenter.default.post(
1930 name: .playerRosterShouldRefresh,
1931 object: nil,
1932 userInfo: ["gameIDs": effects.rosterRelevant]
1933 )
1934 }
1935 await notifyReplayJournalsSynced(effects.journalsSynced)
1936 }
1937
1938 func notifyReplayJournalsSynced(_ gameIDs: Set<UUID>) async {
1939 guard !gameIDs.isEmpty else { return }
1940 NotificationCenter.default.post(
1941 name: .replayJournalDidSync,
1942 object: nil,
1943 userInfo: ["gameIDs": gameIDs]
1944 )
1945 await onReplayJournalsSynced?(gameIDs)
1946 }
1947
1948 private nonisolated static func recordTypeSummary(_ counts: [String: Int]) -> String {
1949 counts
1950 .filter { $0.value > 0 }
1951 .sorted { lhs, rhs in
1952 if lhs.key == rhs.key { return lhs.value > rhs.value }
1953 return lhs.key < rhs.key
1954 }
1955 .map { "\($0.key)=\($0.value)" }
1956 .joined(separator: ", ")
1957 }
1958
1959 private nonisolated static func inferredRecordType(for recordID: CKRecord.ID) -> String {
1960 let name = recordID.recordName
1961 if name.hasPrefix("moves-") { return "Moves" }
1962 if name.hasPrefix("journal-") { return "Journal" }
1963 if name.hasPrefix("player-") { return "Player" }
1964 if name.hasPrefix("game-") { return "Game" }
1965 if name.hasPrefix("ping-") { return "Ping" }
1966 if name.hasPrefix("decision-") { return "Decision" }
1967 return "Unknown"
1968 }
1969
1970
1971
1972
1973
1974 nonisolated static func isTerminalPingSaveError(_ error: NSError) -> Bool {
1975 guard error.domain == CKErrorDomain,
1976 let code = CKError.Code(rawValue: error.code)
1977 else { return false }
1978 switch code {
1979 case .badContainer,
1980 .missingEntitlement,
1981 .notAuthenticated,
1982 .permissionFailure,
1983 .unknownItem,
1984 .invalidArguments,
1985 .serverRejectedRequest,
1986 .incompatibleVersion,
1987 .constraintViolation,
1988 .badDatabase,
1989 .quotaExceeded,
1990 .zoneNotFound,
1991 .limitExceeded,
1992 .userDeletedZone,
1993 .tooManyParticipants,
1994 .referenceViolation,
1995 .managedAccountRestricted:
1996 return true
1997 default:
1998 return false
1999 }
2000 }
2001
2002 nonisolated static func pingSaveRetryDelay(_ error: NSError) -> TimeInterval? {
2003 guard error.domain == CKErrorDomain,
2004 let code = CKError.Code(rawValue: error.code)
2005 else { return nil }
2006 switch code {
2007 case .internalError,
2008 .networkUnavailable,
2009 .networkFailure,
2010 .serviceUnavailable,
2011 .requestRateLimited,
2012 .zoneBusy,
2013 .operationCancelled,
2014 .serverResponseLost,
2015 .accountTemporarilyUnavailable:
2016 let serverDelay = (error.userInfo[CKErrorRetryAfterKey] as? NSNumber)?
2017 .doubleValue
2018 return max(3, serverDelay ?? 0)
2019 default:
2020 return nil
2021 }
2022 }
2023
2024 private func schedulePendingPingRetry(
2025 recordID: CKRecord.ID,
2026 isPrivate: Bool,
2027 after delay: TimeInterval
2028 ) {
2029 let recordName = recordID.recordName
2030 guard pendingPings[recordName] != nil,
2031 scheduledPingRetries.insert(recordName).inserted
2032 else { return }
2033 Task {
2034 try? await Task.sleep(for: .seconds(delay))
2035 scheduledPingRetries.remove(recordName)
2036 guard !Task.isCancelled, pendingPings[recordName] != nil else { return }
2037 let engine = isPrivate ? privateEngine : sharedEngine
2038 engine?.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)])
2039 if let engine { sendChangesDetached(on: engine) }
2040 }
2041 }
2042
2043 private func handleSentRecordZoneChanges(
2044 _ event: CKSyncEngine.Event.SentRecordZoneChanges,
2045 isPrivate: Bool
2046 ) async {
2047 var completionRecords: [UUID: Set<CompletionDurableRecordKind>] = [:]
2048 for record in event.savedRecords {
2049 let name = record.recordID.recordName
2050 if record.recordType == "Game",
2051 name.hasPrefix("game-"),
2052 record["completedAt"] as? Date != nil,
2053 let gameID = UUID(uuidString: String(name.dropFirst("game-".count))) {
2054 completionRecords[gameID, default: []].insert(.game)
2055 } else if record.recordType == "Moves",
2056 let gameID = RecordSerializer.parseMovesRecordName(name)?.0 {
2057 completionRecords[gameID, default: []].insert(.moves)
2058 } else if record.recordType == "Journal",
2059 let gameID = RecordSerializer.parseJournalRecordName(name)?.0 {
2060 completionRecords[gameID, default: []].insert(.journal)
2061 }
2062 }
2063 let savedTypes = Dictionary(
2064 grouping: event.savedRecords,
2065 by: \.recordType
2066 ).mapValues(\.count)
2067 let failedTypes = Dictionary(
2068 grouping: event.failedRecordSaves,
2069 by: { $0.record.recordType }
2070 ).mapValues(\.count)
2071 let deletedTypes = Dictionary(
2072 grouping: event.deletedRecordIDs,
2073 by: Self.inferredRecordType(for:)
2074 ).mapValues(\.count)
2075 let savedSummary = Self.recordTypeSummary(savedTypes)
2076 let failedSummary = Self.recordTypeSummary(failedTypes)
2077 let deletedSummary = Self.recordTypeSummary(deletedTypes)
2078
2079 await trace(
2080 "\(isPrivate ? "private" : "shared") sent: " +
2081 "\(event.savedRecords.count) saved" +
2082 "\(savedSummary.isEmpty ? "" : " (\(savedSummary))"), " +
2083 "\(event.failedRecordSaves.count) failed" +
2084 "\(failedSummary.isEmpty ? "" : " (\(failedSummary))"), " +
2085 "\(event.deletedRecordIDs.count) deleted" +
2086 "\(deletedSummary.isEmpty ? "" : " (\(deletedSummary))")"
2087 )
2088
2089
2090
2091 if event.failedRecordSaves.isEmpty {
2092 await noteRoundTripSuccess()
2093 }
2094 for record in event.savedRecords {
2095 let name = record.recordID.recordName
2096 if name.hasPrefix("ping-") {
2097 await confirmPendingPing(recordName: name)
2098 } else if name.hasPrefix("decision-") {
2099 let stateKey = Self.decisionStateKey(record.recordID)
2100 pendingDecisionPayloads.removeValue(forKey: stateKey)
2101 persistPendingDecisionPayloads()
2102 pendingDecisionVersions.removeValue(forKey: stateKey)
2103 persistPendingDecisionVersions()
2104 decisionSystemFields.removeValue(forKey: stateKey)
2105 }
2106 }
2107
2108
2109 let pendingVersionsSnapshot = pendingDecisionVersions
2110 let ctx = persistence.container.newBackgroundContext()
2111 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
2112 let (failureMessages, orphanedZones, resolvedDecisions, settledPings, settledJournals,
2113 resolvedAccountAddresses, resolvedAccountSecrets, decisionWins, recoveredSaves,
2114 batchFailedSaves, unresolvedFailureZones):
2115 ([String], Set<CKRecordZone.ID>, Set<CKRecord.ID>, Set<CKRecord.ID>, Set<CKRecord.ID>,
2116 [String], [(secret: String, version: Int64)],
2117 [(recordID: CKRecord.ID, stateKey: String, systemFields: Data)],
2118 [CKRecord.ID], [CKRecord.ID], Set<CKRecordZone.ID>) = await ctx.perform {
2119 var messages: [String] = []
2120 var orphaned = Set<CKRecordZone.ID>()
2121 var settledDecisions = Set<CKRecord.ID>()
2122 var settledPings = Set<CKRecord.ID>()
2123 var settledJournals = Set<CKRecord.ID>()
2124 var accountAddresses: [String] = []
2125 var accountSecrets: [(secret: String, version: Int64)] = []
2126
2127
2128
2129 var decisionWins: [(recordID: CKRecord.ID, stateKey: String, systemFields: Data)] = []
2130
2131
2132
2133
2134
2135
2136
2137
2138 var recoveredSaves: [CKRecord.ID] = []
2139
2140
2141
2142
2143
2144 var batchFailedSaves: [CKRecord.ID] = []
2145 var unresolvedFailureZones = Set<CKRecordZone.ID>()
2146 for record in event.savedRecords {
2147 self.writeBackSystemFields(record: record, in: ctx)
2148 let savedName = record.recordID.recordName
2149 if savedName.hasPrefix("game-") {
2150 self.clearPendingSaveFlag(for: savedName, in: ctx)
2151 } else if savedName.hasPrefix("journal-"),
2152 let (gid, _, _) = RecordSerializer.parseJournalRecordName(savedName) {
2153
2154
2155
2156 self.markJournalUploaded(gameID: gid, in: ctx)
2157 }
2158 }
2159 for failure in event.failedRecordSaves {
2160 let name = failure.record.recordID.recordName
2161 let err = failure.error as NSError
2162
2163
2164
2165
2166 var settled = false
2167 if err.domain == CKErrorDomain,
2168 err.code == CKError.batchRequestFailed.rawValue {
2169 batchFailedSaves.append(failure.record.recordID)
2170 settled = true
2171 } else if err.domain == CKErrorDomain,
2172 err.code == CKError.zoneNotFound.rawValue {
2173 orphaned.insert(failure.record.recordID.zoneID)
2174 } else if !isPrivate,
2175 self.isInvalidSharedZoneOwnerError(err) {
2176 orphaned.insert(failure.record.recordID.zoneID)
2177 } else if name.hasPrefix("ping-"),
2178 err.domain == CKErrorDomain,
2179 err.code == CKError.serverRecordChanged.rawValue {
2180
2181
2182
2183
2184 settledPings.insert(failure.record.recordID)
2185 settled = true
2186 messages.append("send: ping \(name) already present — settled")
2187 } else if name.hasPrefix("decision-"),
2188 err.domain == CKErrorDomain,
2189 err.code == CKError.serverRecordChanged.rawValue {
2190 let serverRecord = err.userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord
2191 let stateKey = Self.decisionStateKey(failure.record.recordID)
2192 let intended = pendingVersionsSnapshot[stateKey]
2193 let serverVersion = serverRecord.map(RecordSerializer.decisionVersion)
2194 if let intended, let serverRecord, let serverVersion,
2195 intended > serverVersion,
2196 let serverFields = RecordSerializer.encodeSystemFields(of: serverRecord) {
2197
2198
2199
2200
2201
2202
2203
2204
2205 decisionWins.append((failure.record.recordID, stateKey, serverFields))
2206 settled = true
2207 messages.append(
2208 "send: decision \(name) lost tag race but wins on version " +
2209 "(\(intended) > \(serverVersion)) — overwriting"
2210 )
2211 } else {
2212
2213
2214
2215
2216
2217
2218
2219 settledDecisions.insert(failure.record.recordID)
2220 if let serverRecord {
2221 let scope = DatabaseScope(isPrivate: isPrivate)
2222 if let address = RecordSerializer.parseAccountPushAddressDecision(serverRecord, databaseScope: scope) {
2223 accountAddresses.append(address)
2224 }
2225 if let parsed = RecordSerializer.parseAccountPushSecretDecision(serverRecord, databaseScope: scope) {
2226 accountSecrets.append(parsed)
2227 }
2228 }
2229 settled = true
2230 messages.append("send: decision \(name) already present — settled")
2231 }
2232 } else if name.hasPrefix("journal-"),
2233 err.domain == CKErrorDomain,
2234 err.code == CKError.serverRecordChanged.rawValue,
2235 let (gid, _, _) = RecordSerializer.parseJournalRecordName(name) {
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246 settledJournals.insert(failure.record.recordID)
2247 self.markJournalUploaded(gameID: gid, in: ctx)
2248 settled = true
2249 messages.append("send: journal \(name) already present — settled")
2250 } else if self.recoverServerChangedSave(failure.error, failedRecordName: name, in: ctx) {
2251 recoveredSaves.append(failure.record.recordID)
2252 settled = true
2253 messages.append(
2254 "send: recovered stale system fields for \(name) from CloudKit server record"
2255 )
2256 }
2257 guard !settled else { continue }
2258 unresolvedFailureZones.insert(failure.record.recordID.zoneID)
2259 let userInfo = err.userInfo
2260 .map { "\($0.key)=\($0.value)" }
2261 .joined(separator: " | ")
2262 messages.append(
2263 "send: failed to save \(name) — domain=\(err.domain) code=\(err.code) \(err.localizedDescription) | userInfo: \(userInfo)"
2264 )
2265 }
2266 if ctx.hasChanges {
2267 do {
2268 try ctx.save()
2269 } catch {
2270 let nsError = error as NSError
2271 messages.append(
2272 "send: writeBack ctx.save failed — domain=\(nsError.domain) code=\(nsError.code) \(nsError.localizedDescription)"
2273 )
2274 }
2275 }
2276 return (messages, orphaned, settledDecisions, settledPings, settledJournals,
2277 accountAddresses, accountSecrets, decisionWins, recoveredSaves,
2278 batchFailedSaves, unresolvedFailureZones)
2279 }
2280 if !orphanedZones.isEmpty {
2281 await applyZoneOrphaning(orphanedZones, isPrivate: isPrivate, source: "send")
2282 }
2283 let terminalPingFailures = event.failedRecordSaves.filter { failure in
2284 failure.record.recordID.recordName.hasPrefix("ping-")
2285 && Self.isTerminalPingSaveError(failure.error as NSError)
2286 }
2287 if !terminalPingFailures.isEmpty {
2288 let engine = isPrivate ? privateEngine : sharedEngine
2289 let changes = terminalPingFailures.map {
2290 CKSyncEngine.PendingRecordZoneChange.saveRecord($0.record.recordID)
2291 }
2292 engine?.state.remove(pendingRecordZoneChanges: changes)
2293 for failure in terminalPingFailures {
2294 let recordName = failure.record.recordID.recordName
2295 guard pendingPings[recordName] != nil else { continue }
2296 await failPendingPing(
2297 recordName: recordName,
2298 error: failure.error as NSError
2299 )
2300 }
2301 }
2302 for failure in event.failedRecordSaves {
2303 let recordID = failure.record.recordID
2304 guard recordID.recordName.hasPrefix("ping-"),
2305 let delay = Self.pingSaveRetryDelay(failure.error as NSError)
2306 else { continue }
2307 schedulePendingPingRetry(
2308 recordID: recordID,
2309 isPrivate: isPrivate,
2310 after: delay
2311 )
2312 }
2313
2314
2315
2316 let decisionEngine = isPrivate ? privateEngine : sharedEngine
2317 if !resolvedDecisions.isEmpty, let decisionEngine {
2318 settleDecisionRecords(resolvedDecisions, on: decisionEngine)
2319 }
2320
2321
2322
2323
2324 if !decisionWins.isEmpty, let decisionEngine {
2325 for win in decisionWins {
2326 decisionSystemFields[win.stateKey] = win.systemFields
2327 decisionEngine.state.add(
2328 pendingRecordZoneChanges: [.saveRecord(win.recordID)]
2329 )
2330 }
2331 sendChangesDetached(on: decisionEngine)
2332 }
2333
2334
2335
2336
2337
2338 if !recoveredSaves.isEmpty, let engine = isPrivate ? privateEngine : sharedEngine {
2339 engine.state.add(
2340 pendingRecordZoneChanges: recoveredSaves.map { .saveRecord($0) }
2341 )
2342 sendChangesDetached(on: engine)
2343 }
2344 if let onAccountPushAddress {
2345 for address in resolvedAccountAddresses {
2346 await onAccountPushAddress(address)
2347 }
2348 }
2349 if let onAccountPushSecret {
2350 for entry in resolvedAccountSecrets {
2351 await onAccountPushSecret(entry.secret, entry.version)
2352 }
2353 }
2354 if !settledJournals.isEmpty {
2355
2356
2357 let engine = isPrivate ? privateEngine : sharedEngine
2358 engine?.state.remove(
2359 pendingRecordZoneChanges: settledJournals.map { .saveRecord($0) }
2360 )
2361 }
2362 if !settledPings.isEmpty {
2363 let engine = isPrivate ? privateEngine : sharedEngine
2364 engine?.state.remove(
2365 pendingRecordZoneChanges: settledPings.map { .saveRecord($0) }
2366 )
2367 for recordID in settledPings {
2368 await confirmPendingPing(recordName: recordID.recordName)
2369 }
2370 }
2371 let retryableBatchSiblings = batchFailedSaves.filter {
2372 !orphanedZones.contains($0.zoneID)
2373 && !unresolvedFailureZones.contains($0.zoneID)
2374 }
2375 if !retryableBatchSiblings.isEmpty {
2376 await recoverBatchFailedSaves(retryableBatchSiblings, isPrivate: isPrivate)
2377 }
2378 for message in failureMessages {
2379 await trace(message)
2380 }
2381 if !completionRecords.isEmpty, let onCompletionRecordsSaved {
2382 await onCompletionRecordsSaved(completionRecords)
2383 }
2384 }
2385
2386 private func settleDecisionRecords(
2387 _ recordIDs: Set<CKRecord.ID>,
2388 on engine: CKSyncEngine
2389 ) {
2390 engine.state.remove(
2391 pendingRecordZoneChanges: recordIDs.map { .saveRecord($0) }
2392 )
2393 for recordID in recordIDs {
2394 let stateKey = Self.decisionStateKey(recordID)
2395 pendingDecisionPayloads.removeValue(forKey: stateKey)
2396 pendingDecisionVersions.removeValue(forKey: stateKey)
2397 decisionSystemFields.removeValue(forKey: stateKey)
2398 }
2399 persistPendingDecisionPayloads()
2400 persistPendingDecisionVersions()
2401 }
2402
2403
2404
2405
2406 private func recoverBatchFailedSaves(
2407 _ recordIDs: [CKRecord.ID],
2408 isPrivate: Bool
2409 ) async {
2410 guard let engine = isPrivate ? privateEngine : sharedEngine else { return }
2411 let scope = DatabaseScope(isPrivate: isPrivate)
2412 let pingSnapshot = pendingPings
2413 let decisionSnapshot = pendingDecisionPayloads
2414 let decisionVersionSnapshot = pendingDecisionVersions
2415 let decisionSystemFieldsSnapshot = decisionSystemFields
2416 let ctx = persistence.container.newBackgroundContext()
2417 var recovered: [CKRecord.ID] = []
2418 for recordID in recordIDs {
2419 guard buildRecord(
2420 for: recordID,
2421 in: ctx,
2422 databaseScope: scope,
2423 pings: pingSnapshot,
2424 decisions: decisionSnapshot,
2425 decisionVersions: decisionVersionSnapshot,
2426 decisionSystemFields: decisionSystemFieldsSnapshot
2427 ) != nil else {
2428 await trace(
2429 "send: atomic sibling \(recordID.recordName) is no longer reconstructable — dropped"
2430 )
2431 continue
2432 }
2433 recovered.append(recordID)
2434 }
2435 guard !recovered.isEmpty else { return }
2436 engine.state.add(
2437 pendingRecordZoneChanges: recovered.map { .saveRecord($0) }
2438 )
2439 await trace(
2440 "send: re-enqueued \(recovered.count) reconstructable atomic-failure sibling" +
2441 (recovered.count == 1 ? "" : "s")
2442 )
2443 sendChangesDetached(on: engine)
2444 }
2445
2446
2447
2448
2449 func recoverAtomicBatchForTesting(
2450 settledDecisionID: CKRecord.ID,
2451 batchFailedRecordIDs: [CKRecord.ID],
2452 scope: CKDatabase.Scope
2453 ) async {
2454 guard let engine = scope == .shared ? sharedEngine : privateEngine else { return }
2455 let allIDs = [settledDecisionID] + batchFailedRecordIDs
2456 engine.state.remove(
2457 pendingRecordZoneChanges: allIDs.map { .saveRecord($0) }
2458 )
2459 settleDecisionRecords([settledDecisionID], on: engine)
2460 await recoverBatchFailedSaves(
2461 batchFailedRecordIDs,
2462 isPrivate: scope != .shared
2463 )
2464 }
2465
2466 nonisolated func isInvalidSharedZoneOwnerError(_ error: NSError) -> Bool {
2467 let values = [error.localizedDescription] + error.userInfo.map { "\($0.value)" }
2468 return values.contains {
2469 $0.localizedCaseInsensitiveContains("Cannot convert userId to dsId") ||
2470 $0.localizedCaseInsensitiveContains("invalid userId")
2471 }
2472 }
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484 func applyZoneOrphaning(
2485 _ zones: Set<CKRecordZone.ID>,
2486 isPrivate: Bool,
2487 source: String = "sync"
2488 ) async {
2489 let engine = isPrivate ? privateEngine : sharedEngine
2490 if let engine {
2491 let toRemove = engine.state.pendingRecordZoneChanges.filter { change in
2492 switch change {
2493 case .saveRecord(let id):
2494 return zones.contains(id.zoneID)
2495 case .deleteRecord(let id):
2496 return zones.contains(id.zoneID)
2497 @unknown default:
2498 return false
2499 }
2500 }
2501 if !toRemove.isEmpty {
2502 engine.state.remove(pendingRecordZoneChanges: toRemove)
2503 }
2504 }
2505
2506 let orphanedPingNames = pendingPings.compactMap { name, ping in
2507 zones.contains(ping.recordZoneID) ? name : nil
2508 }
2509 for name in orphanedPingNames {
2510 await failPendingPing(recordName: name)
2511 }
2512
2513 let ctx = persistence.container.newBackgroundContext()
2514 ctx.mergePolicy = NSMergePolicy.mergeByPropertyObjectTrump
2515 let (removedIDs, revokedIDs, failureMessages): ([UUID], [UUID], [String]) = await ctx.perform {
2516 var removed: [UUID] = []
2517 var revoked: [UUID] = []
2518 var messages: [String] = []
2519 for zone in zones {
2520 let zoneName = zone.zoneName
2521 guard zoneName.hasPrefix("game-") else { continue }
2522 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
2523 req.predicate = NSPredicate(format: "ckZoneName == %@", zoneName)
2524 req.fetchLimit = 1
2525 guard let entity = try? ctx.fetch(req).first else { continue }
2526 if isPrivate {
2527
2528
2529
2530
2531
2532
2533 guard !entity.isSupersededByChronicle else { continue }
2534 if let id = entity.id { removed.append(id) }
2535 ctx.delete(entity)
2536 } else {
2537 if !entity.isAccessRevoked, let id = entity.id {
2538 revoked.append(id)
2539 }
2540 entity.isAccessRevoked = true
2541 }
2542 }
2543 if ctx.hasChanges {
2544 do {
2545 try ctx.save()
2546 } catch {
2547 let nsError = error as NSError
2548 messages.append(
2549 "orphan-zone ctx.save FAILED — domain=\(nsError.domain) " +
2550 "code=\(nsError.code) \(nsError.localizedDescription)"
2551 )
2552 }
2553 }
2554 return (removed, revoked, messages)
2555 }
2556
2557 for message in failureMessages {
2558 await trace(message)
2559 }
2560 await trace(
2561 "\(isPrivate ? "private" : "shared") orphaned \(zones.count) zone(s) [src=\(source)]: " +
2562 zones.map(\.zoneName).sorted().joined(separator: ", ")
2563 )
2564
2565 for id in removedIDs {
2566 if let cb = onGameRemoved { await cb(id) }
2567 }
2568 for id in revokedIDs {
2569 if let cb = onGameAccessRevoked { await cb(id) }
2570 }
2571 }
2572
2573
2574
2575
2576
2577 private nonisolated func recoverServerChangedSave(
2578 _ error: Error,
2579 failedRecordName: String,
2580 in ctx: NSManagedObjectContext
2581 ) -> Bool {
2582 let nsError = error as NSError
2583 guard nsError.domain == CKErrorDomain,
2584 nsError.code == CKError.serverRecordChanged.rawValue,
2585 let serverRecord = nsError.userInfo[CKRecordChangedErrorServerRecordKey] as? CKRecord,
2586 serverRecord.recordID.recordName == failedRecordName
2587 else { return false }
2588
2589 writeBackSystemFields(record: serverRecord, in: ctx)
2590 adoptNewerServerCredentials(from: serverRecord, in: ctx)
2591 return true
2592 }
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604 private nonisolated func adoptNewerServerCredentials(
2605 from serverRecord: CKRecord,
2606 in ctx: NSManagedObjectContext
2607 ) {
2608 let name = serverRecord.recordID.recordName
2609 guard name.hasPrefix("game-") else { return }
2610 let serverBlob = (serverRecord["pushCredential"] as? Data)
2611 .flatMap { String(data: $0, encoding: .utf8) }
2612 guard let serverBlob, let serverCreds = GamePushCredentials.decode(serverBlob) else { return }
2613
2614 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
2615 req.predicate = NSPredicate(format: "ckRecordName == %@", name)
2616 req.fetchLimit = 1
2617 guard let entity = try? ctx.fetch(req).first,
2618 entity.notification != serverBlob
2619 else { return }
2620 let localGen = GamePushCredentials.decode(entity.notification)?.generation
2621 guard localGen == nil || serverCreds.generation >= localGen! else { return }
2622 entity.notification = serverBlob
2623
2624
2625 GameEntity.rebuildContentKeyDirectory(in: ctx)
2626 }
2627
2628 private nonisolated func writeBackSystemFields(
2629 record: CKRecord,
2630 in ctx: NSManagedObjectContext
2631 ) {
2632 let name = record.recordID.recordName
2633 let entityName: String
2634 if name.hasPrefix("moves-") { entityName = "MovesEntity" }
2635 else if name.hasPrefix("player-") { entityName = "PlayerEntity" }
2636 else if name.hasPrefix("game-") { entityName = "GameEntity" }
2637 else { return }
2638
2639 let req = NSFetchRequest<NSManagedObject>(entityName: entityName)
2640 req.predicate = NSPredicate(format: "ckRecordName == %@", name)
2641 req.fetchLimit = 1
2642 guard let obj = try? ctx.fetch(req).first else { return }
2643 obj.setValue(RecordSerializer.encodeSystemFields(of: record), forKey: "ckSystemFields")
2644 if entityName == "GameEntity" {
2645 obj.setValue(Date(), forKey: "lastSyncedAt")
2646 }
2647 }
2648
2649
2650
2651
2652
2653
2654
2655
2656 private nonisolated func clearPendingSaveFlag(
2657 for recordName: String,
2658 in ctx: NSManagedObjectContext
2659 ) {
2660 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
2661 req.predicate = NSPredicate(format: "ckRecordName == %@", recordName)
2662 req.fetchLimit = 1
2663 guard let entity = try? ctx.fetch(req).first else { return }
2664 entity.hasPendingSave = false
2665 entity.hasPushPending = false
2666 }
2667
2668 private nonisolated func markJournalUploaded(
2669 gameID: UUID,
2670 in ctx: NSManagedObjectContext
2671 ) {
2672 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
2673 req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
2674 req.fetchLimit = 1
2675 guard let entity = try? ctx.fetch(req).first else { return }
2676 entity.journalUploaded = true
2677 }
2678
2679 private func completedFetchExclusions(
2680 isPrivate: Bool
2681 ) async -> Set<CKRecordZone.ID> {
2682 if isPrivate, let privateCompletedFetchExclusions {
2683 return privateCompletedFetchExclusions
2684 }
2685 if !isPrivate, let sharedCompletedFetchExclusions {
2686 return sharedCompletedFetchExclusions
2687 }
2688
2689 let database = isPrivate
2690 ? container.privateCloudDatabase
2691 : container.sharedCloudDatabase
2692 do {
2693 let zoneIDs = try await database.allRecordZones()
2694 .map(\.zoneID)
2695 .filter {
2696 RecordSerializer.gameID(fromGameRecordName: $0.zoneName) != nil
2697 }
2698 let recordIDs = zoneIDs.map {
2699 CKRecord.ID(recordName: $0.zoneName, zoneID: $0)
2700 }
2701 let cutoff = Date().addingTimeInterval(-7 * 24 * 60 * 60)
2702 var exclusions = Set<CKRecordZone.ID>()
2703 for start in stride(from: 0, to: recordIDs.count, by: 200) {
2704 let end = min(start + 200, recordIDs.count)
2705 let results = try await database.records(
2706 for: Array(recordIDs[start..<end]),
2707 desiredKeys: ["completedAt"]
2708 )
2709 for (recordID, result) in results {
2710 guard let record = try? result.get(),
2711 let completedAt = record["completedAt"] as? Date,
2712 completedAt < cutoff
2713 else { continue }
2714 exclusions.insert(recordID.zoneID)
2715 }
2716 }
2717 if isPrivate {
2718 privateCompletedFetchExclusions = exclusions
2719 } else {
2720 sharedCompletedFetchExclusions = exclusions
2721 }
2722 await trace(
2723 "\(isPrivate ? "private" : "shared") completed fetch exclusions: " +
2724 "\(exclusions.count) zone(s)"
2725 )
2726 return exclusions
2727 } catch {
2728 await trace(
2729 "\(isPrivate ? "private" : "shared") completed fetch exclusions failed: " +
2730 describe(error)
2731 )
2732 return []
2733 }
2734 }
2735
2736}
2737
2738
2739
2740extension SyncEngine: CKSyncEngineDelegate {
2741 func nextFetchChangesOptions(
2742 _ context: CKSyncEngine.FetchChangesContext,
2743 syncEngine: CKSyncEngine
2744 ) async -> CKSyncEngine.FetchChangesOptions {
2745 var options = context.options
2746 let isPrivate = scope(for: syncEngine) == .private
2747 var excluded = await completedFetchExclusions(isPrivate: isPrivate)
2748 if isPrivate { excluded.insert(Archive.zoneID) }
2749
2750 switch options.scope {
2751 case .all:
2752 options.scope = .allExcluding(Array(excluded))
2753 case .allExcluding(var zoneIDs):
2754 let existing = Set(zoneIDs)
2755 for zoneID in excluded where !existing.contains(zoneID) {
2756 zoneIDs.append(zoneID)
2757 }
2758 options.scope = .allExcluding(zoneIDs)
2759 case .zoneIDs(let zoneIDs):
2760 options.scope = .zoneIDs(zoneIDs.filter {
2761 !excluded.contains($0)
2762 })
2763 @unknown default:
2764 options.scope = .allExcluding(Array(excluded))
2765 }
2766 return options
2767 }
2768
2769 func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async {
2770 let isPrivate = scope(for: syncEngine) == .private
2771 switch event {
2772 case .stateUpdate(let e):
2773 await saveEngineState(e.stateSerialization, isPrivate: isPrivate)
2774
2775 case .accountChange(let e):
2776 await trace("account change: \(e.changeType)")
2777 if let onAccountChange { await onAccountChange() }
2778
2779 case .fetchedDatabaseChanges(let e):
2780 await handleFetchedDatabaseChanges(e, isPrivate: isPrivate)
2781
2782 case .fetchedRecordZoneChanges(let e):
2783 await handleFetchedRecordZoneChanges(e, isPrivate: isPrivate)
2784
2785 case .sentDatabaseChanges:
2786 break
2787
2788 case .sentRecordZoneChanges(let e):
2789 await handleSentRecordZoneChanges(e, isPrivate: isPrivate)
2790
2791 case .willFetchChanges, .didFetchChanges,
2792 .willFetchRecordZoneChanges, .didFetchRecordZoneChanges,
2793 .willSendChanges, .didSendChanges:
2794 break
2795
2796 @unknown default:
2797 break
2798 }
2799 }
2800
2801 func nextRecordZoneChangeBatch(
2802 _ context: CKSyncEngine.SendChangesContext,
2803 syncEngine: CKSyncEngine
2804 ) async -> CKSyncEngine.RecordZoneChangeBatch? {
2805 await makeRecordZoneChangeBatch(for: syncEngine)
2806 }
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820 func makeRecordZoneChangeBatch(
2821 for engine: CKSyncEngine
2822 ) async -> CKSyncEngine.RecordZoneChangeBatch? {
2823 let pending = engine.state.pendingRecordZoneChanges
2824 guard !pending.isEmpty else { return nil }
2825 await traceForeignPlayerWrites(in: pending)
2826 let scope = scope(for: engine)
2827 let pingSnapshot = pendingPings
2828 let decisionSnapshot = pendingDecisionPayloads
2829 let decisionVersionSnapshot = pendingDecisionVersions
2830 let decisionSystemFieldsSnapshot = decisionSystemFields
2831 let buildContext = persistence.container.newBackgroundContext()
2832 return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { [weak self] recordID in
2833 guard let self else { return nil }
2834 if let record = self.buildRecord(
2835 for: recordID,
2836 in: buildContext,
2837 databaseScope: scope,
2838 pings: pingSnapshot,
2839 decisions: decisionSnapshot,
2840 decisionVersions: decisionVersionSnapshot,
2841 decisionSystemFields: decisionSystemFieldsSnapshot
2842 ) {
2843 return record
2844 }
2845 engine.state.remove(pendingRecordZoneChanges: [.saveRecord(recordID)])
2846 return nil
2847 }
2848 }
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862 private func traceForeignPlayerWrites(
2863 in pending: [CKSyncEngine.PendingRecordZoneChange]
2864 ) async {
2865 guard let localAuthorID = await currentLocalAuthorID() else { return }
2866 var foreign: [(UUID, String)] = []
2867 for change in pending {
2868 guard case .saveRecord(let recordID) = change,
2869 let (gameID, authorID) =
2870 RecordSerializer.parsePlayerRecordName(recordID.recordName),
2871 authorID != localAuthorID
2872 else { continue }
2873 foreign.append((gameID, authorID))
2874 }
2875 guard !foreign.isEmpty else { return }
2876 let ctx = persistence.container.newBackgroundContext()
2877 for (gameID, authorID) in foreign {
2878 let presenceUntil: Date? = await ctx.perform {
2879 let req = NSFetchRequest<GameEntity>(entityName: "GameEntity")
2880 req.predicate = NSPredicate(format: "id == %@", gameID as CVarArg)
2881 req.fetchLimit = 1
2882 return (try? ctx.fetch(req).first)?.lastReadOtherMoveAt
2883 }
2884 let leaseDesc: String
2885 if let presenceUntil {
2886 let delta = Int(presenceUntil.timeIntervalSinceNow)
2887 leaseDesc = "presenceUntil=\(presenceUntil.ISO8601Format()) " +
2888 (delta > 0 ? "(future +\(delta)s)" : "(past \(-delta)s)")
2889 } else {
2890 leaseDesc = "presenceUntil=nil"
2891 }
2892 await trace(
2893 "‼️ OUTBOUND peer Player[\(gameID.uuidString.prefix(8))] " +
2894 "author=\(authorID.prefix(8)) local=\(localAuthorID.prefix(8)) " +
2895 "\(leaseDesc) — uploading a peer's slot"
2896 )
2897 }
2898 }
2899
2900
2901
2902 func makeRecordZoneChangeBatch(
2903 forTestingScope scope: CKDatabase.Scope
2904 ) async -> CKSyncEngine.RecordZoneChangeBatch? {
2905 let engine = scope == .shared ? sharedEngine : privateEngine
2906 guard let engine else { return nil }
2907 return await makeRecordZoneChangeBatch(for: engine)
2908 }
2909
2910 func pendingPingRecordNamesForTesting() -> [String] {
2911 Array(pendingPings.keys).sorted()
2912 }
2913
2914 func confirmPendingPingForTesting(recordName: String) async {
2915 await confirmPendingPing(recordName: recordName)
2916 }
2917
2918 func setPingConfirmationTimeoutForTesting(_ duration: Duration) {
2919 pingConfirmationTimeout = duration
2920 }
2921}