Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/rules/data-sync-storage.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,6 +186,7 @@ This path holds user data. A silent wrong answer here looks exactly like an empt
| Whether plugin secure fields moved out of `connections.json` into the Keychain, set only when every field moved and the save succeeded | UserDefaults `com.TablePro.pluginSecureFieldsMovedToKeychain`, device-local, never synced | `ConnectionStorage` |
| Whether a saved-queries store replaced a damaged file and waits for a full fetch, so push treats it as unreadable | Table `sync_refill` in the saved-queries SQLite store, dropped once a full fetch applied | `SQLFavoriteStorage` |
| Deletions the server reported for a sync category that is off, applied when the category is next read | UserDefaults, device-local, never synced | `SyncMetadataStorage.deferredDeletions` |
| The iCloud account this device last saved the CloudKit change subscription for; cleared when sync turns on, on Upload Again, when the data is found removed, and when an activation brings a change no notice announced | UserDefaults `com.TablePro.sync.subscribedAccountId`, device-local, never synced | `SyncMetadataStorage.subscribedAccountId` through `SyncPushChannel` |
| Where a connection came from (`origin`): this Mac, imported, iCloud | `connections.json`, never synced or exported | `ConnectionStorage` |
| Table load timings (no identifying data, never uploaded) | JSON lines | `TableLoadHistoryStore` |
| Reopen Last Session list (`LastSession.json`, plus `LastOpenConnections.json` holding only the ids that reconnect, which older builds read) | JSON | `LastOpenConnectionsStorage` |
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,15 @@ public actor CloudKitSyncEngine {
Self.logger.trace("Created or confirmed sync zone: \(Self.zoneName)")
}

// Every device saves the same id, so a save replaces the subscription rather than adding one.
public func saveSubscription() async throws {
guard let database else { throw Self.unavailable }
try await withRetry {
_ = try await database.save(SyncPushSubscription.make())
}
Self.logger.info("Saved the CloudKit change subscription")
}

// MARK: - Push

@discardableResult
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ public enum SyncTrigger: Equatable, Sendable {
case launch
/// The app came forward, or the system woke it to refresh.
case activation
/// CloudKit's silent notice that another device changed the private database.
case remoteChange
/// Something synced was edited on this device.
case localChange
/// `CKAccountChanged`: the person signed in or out, or the account became ready.
Expand Down Expand Up @@ -65,7 +67,7 @@ public enum SyncAdmission: Equatable, Sendable {
return .full
case .localChange:
return isDue ? .full : .none
case .activation, .networkRestored:
case .activation, .remoteChange, .networkRestored:
return isDue ? .full : .downloadOnly
}
case .signedOut, .accountNotReady, .accountRestricted:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,12 @@ public final class SyncMetadataStorage: @unchecked Sendable {
set { userDefaults.set(newValue, forKey: key("lastAccountId")) }
}

// Device-local: every device saves the change subscription once for the account it syncs with.
public var subscribedAccountId: String? {
get { userDefaults.string(forKey: key("subscribedAccountId")) }
set { userDefaults.set(newValue, forKey: key("subscribedAccountId")) }
}

@discardableResult
public func adoptAccount(_ accountId: String) -> SyncAccountChange {
guard let recorded = lastAccountId else {
Expand Down Expand Up @@ -281,6 +287,7 @@ public final class SyncMetadataStorage: @unchecked Sendable {
zoneState = .unknown
userDefaults.removeObject(forKey: key("lastSyncDate"))
userDefaults.removeObject(forKey: key("lastAccountId"))
userDefaults.removeObject(forKey: key("subscribedAccountId"))

for type in SyncRecordType.allCases {
clearDirty(type: type)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
import CloudKit
import Foundation
import os

// Registration for CloudKit's change notices and the subscription that sends them. Nothing here runs while sync is off.
@MainActor
public final class SyncPushChannel {
private static let logger = Logger(subsystem: "com.TablePro", category: "SyncPush")

private let registrar: SyncPushRegistrar
private let metadata: SyncMetadataStorage
private var isRequested = false
private var isRegistered = false
private var missedNotice = false
private var refusedAccount: String?
public private(set) var noticesReceived = 0

public init(registrar: SyncPushRegistrar, metadata: SyncMetadataStorage) {
self.registrar = registrar
self.metadata = metadata
}

public func register() {
guard !isRequested else { return }
isRequested = true
registrar.register()
}

// Only a registration this process asked for is taken back, so a launch with sync off calls nothing.
public func unregister() {
isRegistered = false
missedNotice = false
guard isRequested else { return }
isRequested = false
registrar.unregister()
}

public func registrationDidFinish(registered: Bool) {
guard isRequested else { return }
isRegistered = registered
}

public func noticeArrived() {
missedNotice = false
noticesReceived += 1
}

// While notices arrive, a download they did not start finds nothing new. One that does, with no notice since
// the last download began, means they stopped arriving. The subscription is saved again in case it is gone.
public func activationFoundUnannouncedChanges(noticesSince count: Int) -> Bool {
guard isLive, noticesReceived == count else { return false }
missedNotice = true
forgetSubscription()
return true
}

public var isLive: Bool {
guard isRegistered, !missedNotice, let account = metadata.lastAccountId else { return false }
return metadata.subscribedAccountId == account
}

// A failed save never fails the run. One CloudKit refuses is not sent again for that account until the next launch.
public func saveSubscriptionIfNeeded(_ save: () async throws -> Void) async {
guard let account = metadata.lastAccountId,
metadata.subscribedAccountId != account,
refusedAccount != account else { return }
do {
try await save()
metadata.subscribedAccountId = account
} catch {
Self.logger.error("Could not save the CloudKit change subscription: \(error.localizedDescription, privacy: .private)")
// Only a fault of the build or the app version stays until relaunch; anything else is tried on the next run.
switch SyncFailure(error) {
case .blocked(.unavailable), .blocked(.appUpdateRequired):
refusedAccount = account
default:
break
}
}
}

// Turning sync on, or finding TablePro's data removed from iCloud, saves the subscription again in case it is gone.
public func forgetSubscription() {
metadata.subscribedAccountId = nil
refusedAccount = nil
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
// Each app supplies its own: AppKit and UIKit answer a registration through the app delegate.
public struct SyncPushRegistrar: Sendable {
public let register: @MainActor @Sendable () -> Void
public let unregister: @MainActor @Sendable () -> Void

public init(
register: @escaping @MainActor @Sendable () -> Void,
unregister: @escaping @MainActor @Sendable () -> Void
) {
self.register = register
self.unregister = unregister
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import CloudKit
import Foundation

public enum SyncPushSubscription {
public static let id = "TableProSyncChanges"

// A database subscription outlives a deleted or purged zone and announces the zone coming back.
public static func make() -> CKDatabaseSubscription {
let subscription = CKDatabaseSubscription(subscriptionID: id)
let notificationInfo = CKSubscription.NotificationInfo()
// Silent: no alert, badge or sound, so the system asks the person nothing.
notificationInfo.shouldSendContentAvailable = true
subscription.notificationInfo = notificationInfo
return subscription
}

// The payload is only a signal: it starts the same download an activation does, and nothing in it is read.
public static func announcesChange(
_ userInfo: [AnyHashable: Any],
containerIdentifier: String = CloudKitSyncEngine.defaultContainerID
) -> Bool {
guard let notification = CKNotification(fromRemoteNotificationDictionary: userInfo) as? CKDatabaseNotification else {
return false
}
return notification.subscriptionID == id && notification.containerIdentifier == containerIdentifier
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ struct SyncAdmissionTests {
private var earlier: Date { now.addingTimeInterval(-1) }

private static let everyTrigger: [SyncTrigger] = [
.launch, .activation, .localChange, .accountChange, .networkRestored, .scheduledRetry, .userRequest
.launch, .activation, .remoteChange, .localChange, .accountChange, .networkRestored, .scheduledRetry, .userRequest
]

@Test("Nothing in the way admits every trigger", arguments: everyTrigger)
Expand All @@ -27,6 +27,7 @@ struct SyncAdmissionTests {
#expect(SyncAdmission.decide(for: .localChange, after: error, nextAttempt: later, now: now) == .none)
#expect(SyncAdmission.decide(for: .activation, after: error, nextAttempt: later, now: now) == .downloadOnly)
#expect(SyncAdmission.decide(for: .networkRestored, after: error, nextAttempt: later, now: now) == .downloadOnly)
#expect(SyncAdmission.decide(for: .remoteChange, after: error, nextAttempt: later, now: now) == .downloadOnly)
}

@Test("Full storage lets the person, the timer and an account change try the upload")
Expand Down Expand Up @@ -83,6 +84,7 @@ struct SyncAdmissionTests {
for error in [SyncError?.none, .blocked(.storageFull), .blocked(.dataDeletedFromICloud)] {
#expect(SyncAdmission.decide(for: .activation, after: error, nextAttempt: nil, throttledUntil: later, now: now) == .none)
#expect(SyncAdmission.decide(for: .scheduledRetry, after: error, nextAttempt: nil, throttledUntil: later, now: now) == .none)
#expect(SyncAdmission.decide(for: .remoteChange, after: error, nextAttempt: nil, throttledUntil: later, now: now) == .none)
#expect(SyncAdmission.decide(for: .userRequest, after: error, nextAttempt: nil, throttledUntil: later, now: now) != .none)
}
#expect(SyncAdmission.decide(for: .activation, after: nil, nextAttempt: nil, throttledUntil: earlier, now: now) == .full)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,16 @@ struct SyncMetadataStorageTests {
#expect(storage.lastAccountId == "account")
}

@Test("The subscribed account round-trips and a full reset forgets it")
func subscribedAccountIdRoundTrips() {
let storage = makeStorage()
#expect(storage.subscribedAccountId == nil)
storage.subscribedAccountId = "account"
#expect(storage.subscribedAccountId == "account")
storage.clearAll()
#expect(storage.subscribedAccountId == nil)
}

@Test("The first account seen on a device that never synced is recorded and nothing queued is dropped")
func firstAccountIsRecorded() {
let defaults = ScratchDefaults.make() ?? .standard
Expand Down
Loading
Loading