From 6aaf9a60a913d296991d0c25ab17bf6ac817779a Mon Sep 17 00:00:00 2001 From: Sarah Wolff Date: Thu, 9 Jul 2026 14:38:58 -0400 Subject: [PATCH 1/2] feat(icloud): add private sync engine --- Piperly.xcodeproj/project.pbxproj | 44 + Piperly/App/PiperlyApp.swift | 29 +- Piperly/Models/Book.swift | 20 +- Piperly/Models/Bookmark.swift | 22 +- Piperly/Models/ReaderProfile.swift | 34 +- Piperly/Models/SavedWord.swift | 23 +- Piperly/Piperly.entitlements | 18 + Piperly/Services/BookStore.swift | 543 +++++++++- .../Services/Sync/CloudKitLibrarySync.swift | 658 ++++++++++++ .../Sync/LibraryConflictResolver.swift | 55 + Piperly/Services/Sync/LibraryRecord.swift | 118 +++ .../Services/Sync/LibraryRecordCodec.swift | 203 ++++ Piperly/Services/Sync/LibrarySyncing.swift | 278 +++++ Piperly/Services/Sync/SyncStateStore.swift | 219 ++++ Piperly/Services/Sync/SyncStatus.swift | 288 ++++++ PiperlyTests/CloudKitSyncTests.swift | 969 ++++++++++++++++++ docs/adr/0002-cloudkit-sync-implementation.md | 36 +- project.yml | 10 + 18 files changed, 3535 insertions(+), 32 deletions(-) create mode 100644 Piperly/Piperly.entitlements create mode 100644 Piperly/Services/Sync/CloudKitLibrarySync.swift create mode 100644 Piperly/Services/Sync/LibraryConflictResolver.swift create mode 100644 Piperly/Services/Sync/LibraryRecord.swift create mode 100644 Piperly/Services/Sync/LibraryRecordCodec.swift create mode 100644 Piperly/Services/Sync/LibrarySyncing.swift create mode 100644 Piperly/Services/Sync/SyncStateStore.swift create mode 100644 Piperly/Services/Sync/SyncStatus.swift create mode 100644 PiperlyTests/CloudKitSyncTests.swift diff --git a/Piperly.xcodeproj/project.pbxproj b/Piperly.xcodeproj/project.pbxproj index 679ef92..663484c 100644 --- a/Piperly.xcodeproj/project.pbxproj +++ b/Piperly.xcodeproj/project.pbxproj @@ -14,15 +14,18 @@ 203DF207BABAB9FE753A085B /* TableOfContentsSheet.swift in Sources */ = {isa = PBXBuildFile; fileRef = 15436967F2E7E08C3F4C37D4 /* TableOfContentsSheet.swift */; }; 20C1E80632CEF51395EA5F53 /* WordChip.swift in Sources */ = {isa = PBXBuildFile; fileRef = CF7224C03C200554F5861400 /* WordChip.swift */; }; 2123F3B71AD6460312BAC3A6 /* PrivacyInfo.xcprivacy in Resources */ = {isa = PBXBuildFile; fileRef = 37668E902B9B08AB7690046F /* PrivacyInfo.xcprivacy */; }; + 2AE312EBA1F3BEB9D7B15CEE /* LibraryRecordCodec.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1D2F068169DAE06D75030A39 /* LibraryRecordCodec.swift */; }; 3999B9FA53792DA07DC6F6A2 /* ReadiumNavigator in Frameworks */ = {isa = PBXBuildFile; productRef = 17B713292E77005A7751B9DC /* ReadiumNavigator */; }; 3AC16D4D89F0CBC50AC41C91 /* PiperlyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CEE3796984A778CA18D6B83F /* PiperlyTests.swift */; }; 3B10D4AA0162D1197528A3E0 /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 8F3144A8110DA7D4264D5545 /* LaunchScreen.storyboard */; }; 3CF38A165C6ED0FFF26DDB03 /* the-secret-garden.epub in Resources */ = {isa = PBXBuildFile; fileRef = CA7DA1D35BE11C0F88B3203D /* the-secret-garden.epub */; }; 4599435ED40B97ABFEE6DF62 /* WordsView.swift in Sources */ = {isa = PBXBuildFile; fileRef = ABACED436F78084BF8A2BAEA /* WordsView.swift */; }; 48B1869DE73286878F0EABC7 /* WordTapCoordinator.swift in Sources */ = {isa = PBXBuildFile; fileRef = EE753ECD378C1FB1B62B5BEE /* WordTapCoordinator.swift */; }; + 4CB3CB697D6FC2D125D0CADC /* LibraryRecord.swift in Sources */ = {isa = PBXBuildFile; fileRef = C236C568C7927FEA271E2B08 /* LibraryRecord.swift */; }; 4FF6E8B0F50C76A327C6F2F8 /* Book.swift in Sources */ = {isa = PBXBuildFile; fileRef = 505AE8E196D11F1F4CEC38BA /* Book.swift */; }; 509EE15C974BA348E532B3FA /* TTSEngine.swift in Sources */ = {isa = PBXBuildFile; fileRef = B76C4471CF32D1EEEE0468DA /* TTSEngine.swift */; }; 52EE85A98AEF0DA058B3482D /* ReaderProfile.swift in Sources */ = {isa = PBXBuildFile; fileRef = 07DB7B7BEB14F0757464F4FD /* ReaderProfile.swift */; }; + 540553AA18B7BD706C08CA22 /* SyncStatus.swift in Sources */ = {isa = PBXBuildFile; fileRef = 79209FD4DBEB0A7745E96BCA /* SyncStatus.swift */; }; 552ECE15A6B18EA34CCCD77F /* PiperlyUITests.swift in Sources */ = {isa = PBXBuildFile; fileRef = EA4D52458E36471558AFE41A /* PiperlyUITests.swift */; }; 5993B684DE4B64E826F6BDE0 /* SavedWord.swift in Sources */ = {isa = PBXBuildFile; fileRef = C1B8090D26F5F0FCD944BCCD /* SavedWord.swift */; }; 5FC02FE57992316415BAA4FF /* VoicePickerSheet.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0F33AE51FAB9D371EE0F1F67 /* VoicePickerSheet.swift */; }; @@ -37,10 +40,15 @@ 96A0782B38BA02C7827B1F6F /* Typography.swift in Sources */ = {isa = PBXBuildFile; fileRef = B0B5EA42469618622432905D /* Typography.swift */; }; A4D9861B907C32BA65FA94BA /* ReaderToolbar.swift in Sources */ = {isa = PBXBuildFile; fileRef = 79007FAFBAC9B7FCDF89D151 /* ReaderToolbar.swift */; }; A9B8672F77616A3D902F1BB5 /* BookCard.swift in Sources */ = {isa = PBXBuildFile; fileRef = 020FF465ED5DAE55F3F23078 /* BookCard.swift */; }; + AA8EF4C5E8B7096587E9AC6C /* CloudKitLibrarySync.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90EA411DA826F78E32B4DA71 /* CloudKitLibrarySync.swift */; }; AE1CBD6D4C45DD851FA3DDC9 /* PiperlyApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0575D688D631F115AF497590 /* PiperlyApp.swift */; }; + AEB761A1B95187D81344E32E /* LibraryConflictResolver.swift in Sources */ = {isa = PBXBuildFile; fileRef = 144FD302072287A2F625E295 /* LibraryConflictResolver.swift */; }; + B24843B385E539F6569F539E /* CloudKitSyncTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = B342D7030508E0F3805E6C75 /* CloudKitSyncTests.swift */; }; + B523FF1F444626551DA6B19A /* LibrarySyncing.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9C922ABB693CC6E51B89A685 /* LibrarySyncing.swift */; }; C16B65EFFFBD4432864334EA /* ReaderTheme.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0B48C597C42056AFD320ACB1 /* ReaderTheme.swift */; }; C8CD69CC9A21D1069657FB65 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 456BD662A32FF2E09E8B91CA /* Assets.xcassets */; }; C8EB86567BED41A31D9493EB /* Colors.swift in Sources */ = {isa = PBXBuildFile; fileRef = 32263DACC627AF31FFB42A6F /* Colors.swift */; }; + D08A7543219A4B94086FC580 /* SyncStateStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = 93B5EEAF793B1FBB4652973E /* SyncStateStore.swift */; }; D70FB9ABBE67AD59491D9F22 /* ReaderNavigator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1E04B476A4331F7545247076 /* ReaderNavigator.swift */; }; DC10B557D03A8F34EB5681B6 /* ReadiumShared in Frameworks */ = {isa = PBXBuildFile; productRef = FB84F84F12F294A465FEFEB0 /* ReadiumShared */; }; E6C03BC61FD764CBCFB96B15 /* ReaderView.swift in Sources */ = {isa = PBXBuildFile; fileRef = F50E2DE40A7757EF922301E5 /* ReaderView.swift */; }; @@ -73,8 +81,10 @@ 07DB7B7BEB14F0757464F4FD /* ReaderProfile.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReaderProfile.swift; sourceTree = ""; }; 0B48C597C42056AFD320ACB1 /* ReaderTheme.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReaderTheme.swift; sourceTree = ""; }; 0F33AE51FAB9D371EE0F1F67 /* VoicePickerSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = VoicePickerSheet.swift; sourceTree = ""; }; + 144FD302072287A2F625E295 /* LibraryConflictResolver.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibraryConflictResolver.swift; sourceTree = ""; }; 15436967F2E7E08C3F4C37D4 /* TableOfContentsSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TableOfContentsSheet.swift; sourceTree = ""; }; 180FD98DD38FFD512B905060 /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = ""; }; + 1D2F068169DAE06D75030A39 /* LibraryRecordCodec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibraryRecordCodec.swift; sourceTree = ""; }; 1E04B476A4331F7545247076 /* ReaderNavigator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReaderNavigator.swift; sourceTree = ""; }; 2051654FEEB7BC3200F4830D /* SettingsView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SettingsView.swift; sourceTree = ""; }; 219B546B88E956F5EC6324D7 /* reader-theme.css */ = {isa = PBXFileReference; lastKnownFileType = text.css; path = "reader-theme.css"; sourceTree = ""; }; @@ -88,22 +98,29 @@ 67C736D8D95AF555808BAB07 /* WordListSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WordListSheet.swift; sourceTree = ""; }; 6D67EDBA545BF502AADA33A5 /* LibraryView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibraryView.swift; sourceTree = ""; }; 79007FAFBAC9B7FCDF89D151 /* ReaderToolbar.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReaderToolbar.swift; sourceTree = ""; }; + 79209FD4DBEB0A7745E96BCA /* SyncStatus.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SyncStatus.swift; sourceTree = ""; }; 8F3144A8110DA7D4264D5545 /* LaunchScreen.storyboard */ = {isa = PBXFileReference; lastKnownFileType = file.storyboard; path = LaunchScreen.storyboard; sourceTree = ""; }; 907A4ACDFF28240D2A04EC58 /* ImportButton.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ImportButton.swift; sourceTree = ""; }; + 90EA411DA826F78E32B4DA71 /* CloudKitLibrarySync.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudKitLibrarySync.swift; sourceTree = ""; }; + 93B5EEAF793B1FBB4652973E /* SyncStateStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SyncStateStore.swift; sourceTree = ""; }; + 9C922ABB693CC6E51B89A685 /* LibrarySyncing.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibrarySyncing.swift; sourceTree = ""; }; 9DB2CC0ED8AAE37072017ABF /* ReadingState.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReadingState.swift; sourceTree = ""; }; AA3C687F79D0D61F50394188 /* PiperlyTests.xctest */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.cfbundle; path = PiperlyTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; }; ABACED436F78084BF8A2BAEA /* WordsView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WordsView.swift; sourceTree = ""; }; AEC8DDABC8527ECA9066D42E /* word-tap.js */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.javascript; path = "word-tap.js"; sourceTree = ""; }; B0B5EA42469618622432905D /* Typography.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Typography.swift; sourceTree = ""; }; + B342D7030508E0F3805E6C75 /* CloudKitSyncTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudKitSyncTests.swift; sourceTree = ""; }; B76C4471CF32D1EEEE0468DA /* TTSEngine.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TTSEngine.swift; sourceTree = ""; }; BB264E643F353A189D2BDFC4 /* StickerPicker.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = StickerPicker.swift; sourceTree = ""; }; C1B8090D26F5F0FCD944BCCD /* SavedWord.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SavedWord.swift; sourceTree = ""; }; + C236C568C7927FEA271E2B08 /* LibraryRecord.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibraryRecord.swift; sourceTree = ""; }; CA7DA1D35BE11C0F88B3203D /* the-secret-garden.epub */ = {isa = PBXFileReference; path = "the-secret-garden.epub"; sourceTree = ""; }; CD4617B4737EF21A2663B076 /* BookStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookStore.swift; sourceTree = ""; }; CEE3796984A778CA18D6B83F /* PiperlyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PiperlyTests.swift; sourceTree = ""; }; CF7224C03C200554F5861400 /* WordChip.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WordChip.swift; sourceTree = ""; }; CFADC6967714E5F36F446A79 /* ReadingSettingsSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReadingSettingsSheet.swift; sourceTree = ""; }; D9F98151594647A2B03041EC /* PiperlyUITests.xctest */ = {isa = PBXFileReference; includeInIndex = 0; lastKnownFileType = wrapper.cfbundle; path = PiperlyUITests.xctest; sourceTree = BUILT_PRODUCTS_DIR; }; + DB8BC2605DA2DA30847D4501 /* Piperly.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = Piperly.entitlements; sourceTree = ""; }; EA4D52458E36471558AFE41A /* PiperlyUITests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PiperlyUITests.swift; sourceTree = ""; }; EE753ECD378C1FB1B62B5BEE /* WordTapCoordinator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = WordTapCoordinator.swift; sourceTree = ""; }; F2A1B958B2C979E3FC7F5F17 /* BookmarkListSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = BookmarkListSheet.swift; sourceTree = ""; }; @@ -128,6 +145,7 @@ 08E2BD084CDA80547AB4D334 /* Piperly */ = { isa = PBXGroup; children = ( + DB8BC2605DA2DA30847D4501 /* Piperly.entitlements */, 3748B5FADB0987FCE8E5F1A1 /* App */, 66B02D397374D2014B9C2592 /* Models */, BB9A5A1F59DA7F83FD23C1C6 /* Resources */, @@ -252,6 +270,20 @@ path = PiperlyUITests; sourceTree = ""; }; + B63D8F9DD8FB16D8DDBBC8DD /* Sync */ = { + isa = PBXGroup; + children = ( + 90EA411DA826F78E32B4DA71 /* CloudKitLibrarySync.swift */, + 144FD302072287A2F625E295 /* LibraryConflictResolver.swift */, + C236C568C7927FEA271E2B08 /* LibraryRecord.swift */, + 1D2F068169DAE06D75030A39 /* LibraryRecordCodec.swift */, + 9C922ABB693CC6E51B89A685 /* LibrarySyncing.swift */, + 93B5EEAF793B1FBB4652973E /* SyncStateStore.swift */, + 79209FD4DBEB0A7745E96BCA /* SyncStatus.swift */, + ); + path = Sync; + sourceTree = ""; + }; BB9A5A1F59DA7F83FD23C1C6 /* Resources */ = { isa = PBXGroup; children = ( @@ -268,6 +300,7 @@ E08365D0FFA5F691EF0C82C9 /* PiperlyTests */ = { isa = PBXGroup; children = ( + B342D7030508E0F3805E6C75 /* CloudKitSyncTests.swift */, CEE3796984A778CA18D6B83F /* PiperlyTests.swift */, ); path = PiperlyTests; @@ -288,6 +321,7 @@ children = ( CD4617B4737EF21A2663B076 /* BookStore.swift */, B76C4471CF32D1EEEE0468DA /* TTSEngine.swift */, + B63D8F9DD8FB16D8DDBBC8DD /* Sync */, ); path = Services; sourceTree = ""; @@ -459,6 +493,7 @@ isa = PBXSourcesBuildPhase; buildActionMask = 2147483647; files = ( + B24843B385E539F6569F539E /* CloudKitSyncTests.swift in Sources */, 3AC16D4D89F0CBC50AC41C91 /* PiperlyTests.swift in Sources */, ); runOnlyForDeploymentPostprocessing = 0; @@ -480,9 +515,14 @@ F55EF49167FD7539DAA7D369 /* BookStore.swift in Sources */, 0E530D72404395441FD653A0 /* Bookmark.swift in Sources */, 6C211085478661C47382156D /* BookmarkListSheet.swift in Sources */, + AA8EF4C5E8B7096587E9AC6C /* CloudKitLibrarySync.swift in Sources */, C8EB86567BED41A31D9493EB /* Colors.swift in Sources */, 06D163B795C07C40FDD4C639 /* ContentView.swift in Sources */, 876B3E27B8C741FF25C8D629 /* ImportButton.swift in Sources */, + AEB761A1B95187D81344E32E /* LibraryConflictResolver.swift in Sources */, + 4CB3CB697D6FC2D125D0CADC /* LibraryRecord.swift in Sources */, + 2AE312EBA1F3BEB9D7B15CEE /* LibraryRecordCodec.swift in Sources */, + B523FF1F444626551DA6B19A /* LibrarySyncing.swift in Sources */, F6C0D6F691FDBE460E9C4C03 /* LibraryView.swift in Sources */, AE1CBD6D4C45DD851FA3DDC9 /* PiperlyApp.swift in Sources */, D70FB9ABBE67AD59491D9F22 /* ReaderNavigator.swift in Sources */, @@ -495,6 +535,8 @@ 5993B684DE4B64E826F6BDE0 /* SavedWord.swift in Sources */, 1A5A241B59677748491E3A21 /* SettingsView.swift in Sources */, 67DA759D33D6283C457B577B /* StickerPicker.swift in Sources */, + D08A7543219A4B94086FC580 /* SyncStateStore.swift in Sources */, + 540553AA18B7BD706C08CA22 /* SyncStatus.swift in Sources */, 509EE15C974BA348E532B3FA /* TTSEngine.swift in Sources */, 203DF207BABAB9FE753A085B /* TableOfContentsSheet.swift in Sources */, 96A0782B38BA02C7827B1F6F /* Typography.swift in Sources */, @@ -528,6 +570,7 @@ isa = XCBuildConfiguration; buildSettings = { ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon; + CODE_SIGN_ENTITLEMENTS = Piperly/Piperly.entitlements; CODE_SIGN_IDENTITY = "iPhone Developer"; CODE_SIGN_STYLE = Automatic; CURRENT_PROJECT_VERSION = 1; @@ -710,6 +753,7 @@ isa = XCBuildConfiguration; buildSettings = { ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon; + CODE_SIGN_ENTITLEMENTS = Piperly/Piperly.entitlements; CODE_SIGN_IDENTITY = "iPhone Developer"; CODE_SIGN_STYLE = Automatic; CURRENT_PROJECT_VERSION = 1; diff --git a/Piperly/App/PiperlyApp.swift b/Piperly/App/PiperlyApp.swift index a8893a6..ba5389d 100644 --- a/Piperly/App/PiperlyApp.swift +++ b/Piperly/App/PiperlyApp.swift @@ -18,11 +18,38 @@ import SwiftUI @main struct PiperlyApp: App { - @StateObject private var bookStore = BookStore() + @StateObject private var bookStore: BookStore private let ttsEngine = TTSEngine() @State private var showVoiceSetup = false @Environment(\.scenePhase) private var scenePhase + @MainActor + init() { + let router = LibrarySyncRouter() + let store = BookStore(librarySync: router) + _bookStore = StateObject(wrappedValue: store) + + guard CloudKitLibrarySync.isEnabled() else { return } + Task { + guard let cloudSync = try? CloudKitLibrarySync( + enabled: true, + localSnapshotProvider: { [weak store] in + store?.librarySnapshotRecords() ?? [] + }, + remoteChangeHandler: { [weak store] changes, scope in + guard let store else { return .complete } + if scope.isCurrentAccount { + return router.applyingCurrentAccountChanges(scope: scope) { + store.applyRemoteChanges(changes) + } + } + return store.applyRemoteChanges(changes) + } + ) else { return } + await router.use(cloudSync) + } + } + var body: some Scene { WindowGroup { ContentView(ttsEngine: ttsEngine) diff --git a/Piperly/Models/Book.swift b/Piperly/Models/Book.swift index c465ccd..9b723ef 100644 --- a/Piperly/Models/Book.swift +++ b/Piperly/Models/Book.swift @@ -23,6 +23,7 @@ struct Book: Identifiable, Codable { let author: String let fileName: String var coverImageName: String? + var modifiedAt: Date init( id: UUID = UUID(), @@ -30,7 +31,8 @@ struct Book: Identifiable, Codable { title: String, author: String, fileName: String, - coverImageName: String? = nil + coverImageName: String? = nil, + modifiedAt: Date = .now ) { self.id = id self.contentIdentity = contentIdentity @@ -38,5 +40,21 @@ struct Book: Identifiable, Codable { self.author = author self.fileName = fileName self.coverImageName = coverImageName + self.modifiedAt = modifiedAt + } + + private enum CodingKeys: String, CodingKey { + case id, contentIdentity, title, author, fileName, coverImageName, modifiedAt + } + + init(from decoder: Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + id = try container.decode(UUID.self, forKey: .id) + contentIdentity = try container.decode(String.self, forKey: .contentIdentity) + title = try container.decode(String.self, forKey: .title) + author = try container.decode(String.self, forKey: .author) + fileName = try container.decode(String.self, forKey: .fileName) + coverImageName = try container.decodeIfPresent(String.self, forKey: .coverImageName) + modifiedAt = try container.decodeIfPresent(Date.self, forKey: .modifiedAt) ?? .distantPast } } diff --git a/Piperly/Models/Bookmark.swift b/Piperly/Models/Bookmark.swift index 1489a02..4406943 100644 --- a/Piperly/Models/Bookmark.swift +++ b/Piperly/Models/Bookmark.swift @@ -26,6 +26,7 @@ struct Bookmark: Identifiable, Codable, Hashable { let progression: Double let sticker: BookmarkSticker let createdAt: Date + var modifiedAt: Date init( id: UUID = UUID(), @@ -35,7 +36,8 @@ struct Bookmark: Identifiable, Codable, Hashable { title: String?, progression: Double, sticker: BookmarkSticker, - createdAt: Date = .now + createdAt: Date = .now, + modifiedAt: Date = .now ) { self.id = id self.profileID = profileID @@ -45,6 +47,24 @@ struct Bookmark: Identifiable, Codable, Hashable { self.progression = progression self.sticker = sticker self.createdAt = createdAt + self.modifiedAt = modifiedAt + } + + private enum CodingKeys: String, CodingKey { + case id, profileID, bookID, locatorJSON, title, progression, sticker, createdAt, modifiedAt + } + + init(from decoder: Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + id = try container.decode(UUID.self, forKey: .id) + profileID = try container.decode(UUID.self, forKey: .profileID) + bookID = try container.decode(UUID.self, forKey: .bookID) + locatorJSON = try container.decode(String.self, forKey: .locatorJSON) + title = try container.decodeIfPresent(String.self, forKey: .title) + progression = try container.decode(Double.self, forKey: .progression) + sticker = try container.decode(BookmarkSticker.self, forKey: .sticker) + createdAt = try container.decode(Date.self, forKey: .createdAt) + modifiedAt = try container.decodeIfPresent(Date.self, forKey: .modifiedAt) ?? createdAt } } diff --git a/Piperly/Models/ReaderProfile.swift b/Piperly/Models/ReaderProfile.swift index 4d37255..433a3c7 100644 --- a/Piperly/Models/ReaderProfile.swift +++ b/Piperly/Models/ReaderProfile.swift @@ -58,6 +58,8 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { var fontSize: Double var readerTheme: String var hasCompletedVoiceSetup: Bool + var metadataModifiedAt: Date + var preferencesModifiedAt: Date init( id: UUID = UUID(), @@ -69,7 +71,9 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { speechRate: Double = Self.defaultSpeechRate, fontSize: Double = Self.defaultFontSize, readerTheme: String = Self.defaultReaderTheme, - hasCompletedVoiceSetup: Bool = false + hasCompletedVoiceSetup: Bool = false, + metadataModifiedAt: Date = .now, + preferencesModifiedAt: Date = .now ) throws { self.id = id self.name = try Self.validatedNickname(name) @@ -81,6 +85,8 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { self.fontSize = fontSize self.readerTheme = readerTheme self.hasCompletedVoiceSetup = hasCompletedVoiceSetup + self.metadataModifiedAt = metadataModifiedAt + self.preferencesModifiedAt = preferencesModifiedAt } init() { @@ -94,6 +100,8 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { fontSize = Self.defaultFontSize readerTheme = Self.defaultReaderTheme hasCompletedVoiceSetup = false + metadataModifiedAt = .now + preferencesModifiedAt = .now } mutating func updateNickname(_ name: String) throws { @@ -142,6 +150,9 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { case fontSize case readerTheme case hasCompletedVoiceSetup + case metadataModifiedAt + case preferencesModifiedAt + case modifiedAt } init(from decoder: Decoder) throws { @@ -161,5 +172,26 @@ struct ReaderProfile: Identifiable, Codable, Hashable, Sendable { ?? Self.defaultReaderTheme hasCompletedVoiceSetup = try container.decodeIfPresent(Bool.self, forKey: .hasCompletedVoiceSetup) ?? false + let legacyModifiedAt = try container.decodeIfPresent(Date.self, forKey: .modifiedAt) ?? createdAt + metadataModifiedAt = try container.decodeIfPresent(Date.self, forKey: .metadataModifiedAt) + ?? legacyModifiedAt + preferencesModifiedAt = try container.decodeIfPresent(Date.self, forKey: .preferencesModifiedAt) + ?? legacyModifiedAt + } + + func encode(to encoder: Encoder) throws { + var container = encoder.container(keyedBy: CodingKeys.self) + try container.encode(id, forKey: .id) + try container.encode(name, forKey: .name) + try container.encode(avatarSymbol, forKey: .avatarSymbol) + try container.encode(colorName, forKey: .colorName) + try container.encode(createdAt, forKey: .createdAt) + try container.encode(voiceIdentifier, forKey: .voiceIdentifier) + try container.encode(speechRate, forKey: .speechRate) + try container.encode(fontSize, forKey: .fontSize) + try container.encode(readerTheme, forKey: .readerTheme) + try container.encode(hasCompletedVoiceSetup, forKey: .hasCompletedVoiceSetup) + try container.encode(metadataModifiedAt, forKey: .metadataModifiedAt) + try container.encode(preferencesModifiedAt, forKey: .preferencesModifiedAt) } } diff --git a/Piperly/Models/SavedWord.swift b/Piperly/Models/SavedWord.swift index 197177e..ad15d5f 100644 --- a/Piperly/Models/SavedWord.swift +++ b/Piperly/Models/SavedWord.swift @@ -26,6 +26,7 @@ struct SavedWord: Identifiable, Codable, Hashable, Sendable { var tapCount: Int let savedAt: Date var lastTappedAt: Date + var modifiedAt: Date init( id: UUID = UUID(), @@ -36,7 +37,8 @@ struct SavedWord: Identifiable, Codable, Hashable, Sendable { bookTitle: String, tapCount: Int = 1, savedAt: Date = .now, - lastTappedAt: Date = .now + lastTappedAt: Date = .now, + modifiedAt: Date = .now ) { self.id = id self.profileID = profileID @@ -47,5 +49,24 @@ struct SavedWord: Identifiable, Codable, Hashable, Sendable { self.tapCount = tapCount self.savedAt = savedAt self.lastTappedAt = lastTappedAt + self.modifiedAt = modifiedAt + } + + private enum CodingKeys: String, CodingKey { + case id, profileID, word, displayWord, bookID, bookTitle, tapCount, savedAt, lastTappedAt, modifiedAt + } + + init(from decoder: Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + id = try container.decode(UUID.self, forKey: .id) + profileID = try container.decode(UUID.self, forKey: .profileID) + word = try container.decode(String.self, forKey: .word) + displayWord = try container.decode(String.self, forKey: .displayWord) + bookID = try container.decode(UUID.self, forKey: .bookID) + bookTitle = try container.decode(String.self, forKey: .bookTitle) + tapCount = try container.decode(Int.self, forKey: .tapCount) + savedAt = try container.decode(Date.self, forKey: .savedAt) + lastTappedAt = try container.decode(Date.self, forKey: .lastTappedAt) + modifiedAt = try container.decodeIfPresent(Date.self, forKey: .modifiedAt) ?? lastTappedAt } } diff --git a/Piperly/Piperly.entitlements b/Piperly/Piperly.entitlements new file mode 100644 index 0000000..1c9db8e --- /dev/null +++ b/Piperly/Piperly.entitlements @@ -0,0 +1,18 @@ + + + + + aps-environment + development + com.apple.developer.icloud-container-identifiers + + iCloud.com.piperly.app + + com.apple.developer.icloud-services + + CloudKit + + com.apple.developer.ubiquity-kvstore-identifier + $(TeamIdentifierPrefix)com.piperly.app + + diff --git a/Piperly/Services/BookStore.swift b/Piperly/Services/BookStore.swift index 2a92f08..04b3764 100644 --- a/Piperly/Services/BookStore.swift +++ b/Piperly/Services/BookStore.swift @@ -20,7 +20,9 @@ import SwiftUI @preconcurrency import ReadiumShared @preconcurrency import ReadiumStreamer +// swiftlint:disable file_length @MainActor +// swiftlint:disable:next type_body_length class BookStore: ObservableObject { @Published var books: [Book] = [] @Published var profiles: [ReaderProfile] = [] @@ -28,11 +30,13 @@ class BookStore: ObservableObject { @Published var readingStates: [ReadingState] = [] @Published var bookmarks: [Bookmark] = [] @Published var savedWords: [SavedWord] = [] + @Published private(set) var syncOutboxStatus: LibraryOutboxStatus = .ready private let documentsURL: URL private let coversURL: URL private let importSnapshotsURL: URL private let userDefaults: UserDefaults + private let librarySync: any LibrarySyncing private let booksKey = "piperly_books" private let profilesKey = "piperly_reader_profiles" private let selectedProfileKey = "piperly_selected_profile_id" @@ -45,21 +49,32 @@ class BookStore: ObservableObject { private var importsByContentIdentity: [String: Task] = [:] nonisolated private static let fileReadChunkSize = 1_048_576 - convenience init(userDefaults: UserDefaults = .standard) { + convenience init( + userDefaults: UserDefaults = .standard, + librarySync: any LibrarySyncing = DisabledLibrarySync() + ) { let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0] self.init( documentsURL: docs.appendingPathComponent("Books", isDirectory: true), coversURL: docs.appendingPathComponent("Covers", isDirectory: true), - userDefaults: userDefaults + userDefaults: userDefaults, + librarySync: librarySync ) } - init(documentsURL: URL, coversURL: URL, userDefaults: UserDefaults) { + init( + documentsURL: URL, + coversURL: URL, + userDefaults: UserDefaults, + librarySync: any LibrarySyncing = DisabledLibrarySync() + ) { self.documentsURL = documentsURL self.coversURL = coversURL self.importSnapshotsURL = documentsURL.deletingLastPathComponent() .appendingPathComponent(".PiperlyImportSnapshots", isDirectory: true) self.userDefaults = userDefaults + self.librarySync = librarySync + self.syncOutboxStatus = librarySync.currentOutboxStatus() try? FileManager.default.createDirectory(at: documentsURL, withIntermediateDirectories: true) try? FileManager.default.createDirectory(at: coversURL, withIntermediateDirectories: true) @@ -166,6 +181,9 @@ class BookStore: ObservableObject { avatarSymbol: avatarSymbol, colorName: colorName ) + guard persistSyncRecords(syncRecords(for: profile)) else { + throw BookStoreError.syncOutboxUnavailable + } profiles.append(profile) selectedProfileID = profile.id saveProfiles() @@ -175,15 +193,49 @@ class BookStore: ObservableObject { func updateProfile(_ profileID: UUID, name: String, avatarSymbol: String, colorName: String) throws { guard let index = profiles.firstIndex(where: { $0.id == profileID }) else { return } - try profiles[index].updateNickname(Self.sanitizedProfileName(name)) - profiles[index].avatarSymbol = avatarSymbol - profiles[index].colorName = colorName + var updated = profiles[index] + try updated.updateNickname(Self.sanitizedProfileName(name)) + updated.avatarSymbol = avatarSymbol + updated.colorName = colorName + updated.metadataModifiedAt = .now + guard persistSyncRecords([syncProfileRecord(for: updated)]) else { + throw BookStoreError.syncOutboxUnavailable + } + profiles[index] = updated saveProfiles() } func deleteProfile(_ profileID: UUID) { guard profiles.count > 1, profiles.contains(where: { $0.id == profileID }) else { return } + let removedStates = readingStates.filter { $0.profileID == profileID } + let removedBookmarks = bookmarks.filter { $0.profileID == profileID } + let removedWords = savedWords.filter { $0.profileID == profileID } + var operations: [LibraryOutboxOperation] = [ + .delete(LibraryRecordReference( + recordType: "ReaderProfile", + recordName: "profile-\(profileID.uuidString.lowercased())" + )), + .delete(LibraryRecordReference( + recordType: "ReaderPreferences", + recordName: "preferences-\(profileID.uuidString.lowercased())" + )), + ] + operations += removedStates.compactMap(readingStateReference).map(LibraryOutboxOperation.delete) + operations += removedBookmarks.map { + .delete(LibraryRecordReference( + recordType: "Bookmark", + recordName: "bookmark-\($0.id.uuidString.lowercased())" + )) + } + operations += removedWords.map { + .delete(LibraryRecordReference( + recordType: "SavedWord", + recordName: "word-\($0.id.uuidString.lowercased())" + )) + } + guard persistSyncOperations(operations) else { return } + profiles.removeAll { $0.id == profileID } readingStates.removeAll { $0.profileID == profileID } bookmarks.removeAll { $0.profileID == profileID } @@ -206,7 +258,11 @@ class BookStore: ObservableObject { func updateActiveProfile(_ update: (inout ReaderProfile) -> Void) { guard let index = profiles.firstIndex(where: { $0.id == activeProfileID }) else { return } - update(&profiles[index]) + var updated = profiles[index] + update(&updated) + updated.preferencesModifiedAt = .now + guard persistSyncRecords([syncPreferencesRecord(for: updated)]) else { return } + profiles[index] = updated saveProfiles() } @@ -312,6 +368,12 @@ class BookStore: ObservableObject { saveBooks() saveReadingStates() saveSavedWords() + do { + try librarySync.flush() + syncOutboxStatus = .ready + } catch { + syncOutboxStatus = .blocked + } } func importBook(from sourceURL: URL) async throws -> Book { @@ -397,6 +459,14 @@ class BookStore: ObservableObject { coverImageName: coverName ) + guard persistSyncRecord(syncRecord(for: book)) else { + try? FileManager.default.removeItem(at: destURL) + if let coverName { + try? FileManager.default.removeItem(at: coversURL.appendingPathComponent(coverName)) + } + throw BookStoreError.syncOutboxUnavailable + } + books.append(book) saveBooks() return book @@ -486,30 +556,44 @@ class BookStore: ObservableObject { func updateProgress(for bookID: UUID, progression: Double) { let profileID = activeProfileID + let state: ReadingState if let index = readingStates.firstIndex(where: { $0.bookID == bookID && $0.profileID == profileID }) { - readingStates[index].lastReadProgression = progression - readingStates[index].updatedAt = .now + var updated = readingStates[index] + updated.lastReadProgression = progression + updated.updatedAt = .now + state = updated + guard persistSyncRecord(syncRecord(for: state)) else { return } + readingStates[index] = updated } else { - readingStates.append(ReadingState( + state = ReadingState( profileID: profileID, bookID: bookID, lastReadProgression: progression - )) + ) + guard persistSyncRecord(syncRecord(for: state)) else { return } + readingStates.append(state) } scheduleSaveReadingStates() } func updateLocator(for bookID: UUID, locatorJSON: String) { let profileID = activeProfileID + let state: ReadingState if let index = readingStates.firstIndex(where: { $0.bookID == bookID && $0.profileID == profileID }) { - readingStates[index].lastReadLocatorJSON = locatorJSON - readingStates[index].updatedAt = .now + var updated = readingStates[index] + updated.lastReadLocatorJSON = locatorJSON + updated.updatedAt = .now + state = updated + guard persistSyncRecord(syncRecord(for: state)) else { return } + readingStates[index] = updated } else { - readingStates.append(ReadingState( + state = ReadingState( profileID: profileID, bookID: bookID, lastReadLocatorJSON: locatorJSON - )) + ) + guard persistSyncRecord(syncRecord(for: state)) else { return } + readingStates.append(state) } scheduleSaveReadingStates() } @@ -544,11 +628,18 @@ class BookStore: ObservableObject { progression: progression, sticker: sticker ) + guard persistSyncRecord(syncRecord(for: bookmark)) else { return } bookmarks.append(bookmark) saveBookmarks() } func removeBookmark(_ id: UUID) { + guard bookmarks.contains(where: { $0.id == id }) else { return } + let reference = LibraryRecordReference( + recordType: "Bookmark", + recordName: "bookmark-\(id.uuidString.lowercased())" + ) + guard persistSyncOperations([.delete(reference)]) else { return } bookmarks.removeAll { $0.id == id } saveBookmarks() } @@ -594,8 +685,12 @@ class BookStore: ObservableObject { let canonical = word.lowercased() let profileID = activeProfileID if let index = savedWords.firstIndex(where: { $0.word == canonical && $0.bookID == bookID && $0.profileID == profileID }) { - savedWords[index].tapCount += 1 - savedWords[index].lastTappedAt = .now + var updated = savedWords[index] + updated.tapCount += 1 + updated.lastTappedAt = .now + updated.modifiedAt = .now + guard persistSyncRecord(syncRecord(for: updated)) else { return false } + savedWords[index] = updated scheduleSaveWords() return false } else { @@ -606,6 +701,7 @@ class BookStore: ObservableObject { bookID: bookID, bookTitle: bookTitle ) + guard persistSyncRecord(syncRecord(for: saved)) else { return false } savedWords.append(saved) scheduleSaveWords() return true @@ -613,6 +709,12 @@ class BookStore: ObservableObject { } func removeWord(_ id: UUID) { + guard savedWords.contains(where: { $0.id == id }) else { return } + let reference = LibraryRecordReference( + recordType: "SavedWord", + recordName: "word-\(id.uuidString.lowercased())" + ) + guard persistSyncOperations([.delete(reference)]) else { return } savedWords.removeAll { $0.id == id } saveSavedWords() } @@ -647,6 +749,31 @@ class BookStore: ObservableObject { } func deleteBook(_ book: Book) { + let removedStates = readingStates.filter { $0.bookID == book.id } + let removedBookmarks = bookmarks.filter { $0.bookID == book.id } + let removedWords = savedWords.filter { $0.bookID == book.id } + var operations: [LibraryOutboxOperation] = [ + .delete(LibraryRecordReference(recordType: "Book", recordName: book.contentIdentity.lowercased())), + ] + operations += removedStates.map { + .delete(LibraryRecordReference( + recordType: "ReadingState", + recordName: "reading-\($0.profileID.uuidString.lowercased())-\(book.contentIdentity.lowercased())" + )) + } + operations += removedBookmarks.map { + .delete(LibraryRecordReference( + recordType: "Bookmark", + recordName: "bookmark-\($0.id.uuidString.lowercased())" + )) + } + operations += removedWords.map { + .delete(LibraryRecordReference( + recordType: "SavedWord", + recordName: "word-\($0.id.uuidString.lowercased())" + )) + } + guard persistSyncOperations(operations) else { return } let url = bookURL(for: book) try? FileManager.default.removeItem(at: url) if let coverName = book.coverImageName { @@ -707,15 +834,395 @@ class BookStore: ObservableObject { guard FileManager.default.fileExists(atPath: url.path), let publication = try? await openPublication(at: url), let coverName = await extractCover(from: publication) else { continue } - books[i].coverImageName = coverName + var updated = books[i] + updated.coverImageName = coverName + updated.modifiedAt = .now + guard persistSyncRecord(syncRecord(for: updated)) else { + try? FileManager.default.removeItem(at: coversURL.appendingPathComponent(coverName)) + continue + } + books[i] = updated changed = true } if changed { saveBooks() } } + + // MARK: - Library Sync + + func librarySnapshotRecords() -> [LibraryRecord] { + books.map(syncRecord) + + profiles.flatMap(syncRecords) + + readingStates.compactMap(syncRecord) + + bookmarks.compactMap(syncRecord) + + savedWords.compactMap(syncRecord) + } + + private func syncRecord(for book: Book) -> LibraryRecord { + .book(SyncedBook( + id: book.id, + contentIdentity: book.contentIdentity, + title: book.title, + author: book.author, + originalExtension: URL(fileURLWithPath: book.fileName).pathExtension, + hasCover: book.coverImageName != nil, + modifiedAt: book.modifiedAt + )) + } + + private func syncRecords(for profile: ReaderProfile) -> [LibraryRecord] { + [syncProfileRecord(for: profile), syncPreferencesRecord(for: profile)] + } + + private func syncProfileRecord(for profile: ReaderProfile) -> LibraryRecord { + .readerProfile(SyncedReaderProfile( + id: profile.id, + nickname: profile.name, + avatarSymbol: profile.avatarSymbol, + colorName: profile.colorName, + createdAt: profile.createdAt, + modifiedAt: profile.metadataModifiedAt + )) + } + + private func syncPreferencesRecord(for profile: ReaderProfile) -> LibraryRecord { + .readerPreferences(SyncedReaderPreferences( + profileID: profile.id, + voiceIdentifier: profile.voiceIdentifier, + speechRate: profile.speechRate, + fontSize: profile.fontSize, + readerTheme: profile.readerTheme, + hasCompletedVoiceSetup: profile.hasCompletedVoiceSetup, + modifiedAt: profile.preferencesModifiedAt + )) + } + + private func syncRecord(for state: ReadingState) -> LibraryRecord? { + guard let bookIdentity = books.first(where: { $0.id == state.bookID })?.contentIdentity else { return nil } + return .readingState(SyncedReadingState( + profileID: state.profileID, + bookIdentity: bookIdentity, + progression: state.lastReadProgression, + locatorJSON: state.lastReadLocatorJSON, + modifiedAt: state.updatedAt + )) + } + + private func syncRecord(for bookmark: Bookmark) -> LibraryRecord? { + guard let bookIdentity = books.first(where: { $0.id == bookmark.bookID })?.contentIdentity else { return nil } + return .bookmark(SyncedBookmark( + id: bookmark.id, + profileID: bookmark.profileID, + bookIdentity: bookIdentity, + locatorJSON: bookmark.locatorJSON, + title: bookmark.title, + progression: bookmark.progression, + sticker: bookmark.sticker.rawValue, + createdAt: bookmark.createdAt, + modifiedAt: bookmark.modifiedAt + )) + } + + private func syncRecord(for word: SavedWord) -> LibraryRecord? { + guard let bookIdentity = books.first(where: { $0.id == word.bookID })?.contentIdentity else { return nil } + return .savedWord(SyncedSavedWord( + id: word.id, + profileID: word.profileID, + bookIdentity: bookIdentity, + canonicalWord: word.word, + displayWord: word.displayWord, + bookTitle: word.bookTitle, + tapCount: word.tapCount, + savedAt: word.savedAt, + lastTappedAt: word.lastTappedAt, + modifiedAt: word.modifiedAt + )) + } + + private func readingStateReference(for state: ReadingState) -> LibraryRecordReference? { + guard let identity = books.first(where: { $0.id == state.bookID })?.contentIdentity else { return nil } + return LibraryRecordReference( + recordType: "ReadingState", + recordName: "reading-\(state.profileID.uuidString.lowercased())-\(identity.lowercased())" + ) + } + + private func persistSyncRecord(_ record: LibraryRecord?) -> Bool { + guard let record else { + syncOutboxStatus = .blocked + return false + } + return persistSyncRecords([record]) + } + + private func persistSyncRecords(_ records: [LibraryRecord]) -> Bool { + persistSyncOperations(records.map(LibraryOutboxOperation.save)) + } + + private func persistSyncOperations(_ operations: [LibraryOutboxOperation]) -> Bool { + do { + try librarySync.enqueue(operations) + syncOutboxStatus = .ready + return true + } catch { + syncOutboxStatus = .blocked + return false + } + } + + /// Applies a complete fetched batch without using the local mutation + /// methods, which prevents downloaded records from being queued again. + func applyRemoteChanges(_ changes: [LibraryRemoteChange]) -> RemoteApplicationResult { + let deletions = changes.compactMap { change -> LibraryRecordReference? in + guard case .delete(let reference) = change else { return nil } + return reference + } + let unresolvedDeletions = deletions.filter { !applyRemoteDelete($0) } + + let records = changes.compactMap { change -> LibraryRecord? in + guard case .save(let record) = change else { return nil } + return record + }.sorted { $0.remoteApplicationOrder < $1.remoteApplicationOrder } + let unresolved = records.filter { !applyRemoteSave($0) } + + saveBooks() + saveProfiles() + saveReadingStates() + saveBookmarks() + saveSavedWords() + if !profiles.isEmpty { ensureDefaultProfile() } + return RemoteApplicationResult( + unresolvedRecords: unresolved, + unresolvedDeletions: unresolvedDeletions + ) + } + + // swiftlint:disable:next function_body_length cyclomatic_complexity + private func applyRemoteSave(_ record: LibraryRecord) -> Bool { + switch record { + case .book(let remote): + guard let existing = books.first(where: { $0.contentIdentity == remote.contentIdentity }) else { + books.append(Book( + id: remote.id, + contentIdentity: remote.contentIdentity, + title: remote.title, + author: remote.author, + fileName: Self.storageFileName(for: remote.contentIdentity), + modifiedAt: remote.modifiedAt + )) + return true + } + let local = SyncedBook( + id: existing.id, + contentIdentity: existing.contentIdentity, + title: existing.title, + author: existing.author, + originalExtension: URL(fileURLWithPath: existing.fileName).pathExtension, + hasCover: existing.coverImageName != nil, + modifiedAt: existing.modifiedAt + ) + guard case .book(let merged) = LibraryConflictResolver.merge(local: .book(local), remote: record), + let index = books.firstIndex(where: { $0.id == existing.id }) else { return true } + books[index] = Book( + id: existing.id, + contentIdentity: merged.contentIdentity, + title: merged.title, + author: merged.author, + fileName: existing.fileName, + coverImageName: existing.coverImageName, + modifiedAt: merged.modifiedAt + ) + return true + case .readerProfile(let remote): + if let index = profiles.firstIndex(where: { $0.id == remote.id }) { + guard remote.modifiedAt >= profiles[index].metadataModifiedAt else { return true } + let existing = profiles[index] + guard let merged = try? ReaderProfile( + id: remote.id, + name: remote.nickname, + avatarSymbol: remote.avatarSymbol, + colorName: remote.colorName, + createdAt: remote.createdAt, + voiceIdentifier: existing.voiceIdentifier, + speechRate: existing.speechRate, + fontSize: existing.fontSize, + readerTheme: existing.readerTheme, + hasCompletedVoiceSetup: existing.hasCompletedVoiceSetup, + metadataModifiedAt: remote.modifiedAt, + preferencesModifiedAt: existing.preferencesModifiedAt + ) else { return true } + profiles[index] = merged + } else { + guard let profile = try? ReaderProfile( + id: remote.id, + name: remote.nickname, + avatarSymbol: remote.avatarSymbol, + colorName: remote.colorName, + createdAt: remote.createdAt, + metadataModifiedAt: remote.modifiedAt, + preferencesModifiedAt: .distantPast + ) else { return true } + profiles.append(profile) + } + return true + case .readerPreferences(let remote): + guard let index = profiles.firstIndex(where: { $0.id == remote.profileID }) else { return false } + guard remote.modifiedAt >= profiles[index].preferencesModifiedAt else { return true } + profiles[index].voiceIdentifier = remote.voiceIdentifier + profiles[index].speechRate = remote.speechRate + profiles[index].fontSize = remote.fontSize + profiles[index].readerTheme = remote.readerTheme + profiles[index].hasCompletedVoiceSetup = remote.hasCompletedVoiceSetup + profiles[index].preferencesModifiedAt = remote.modifiedAt + return true + case .readingState(let remote): + guard profiles.contains(where: { $0.id == remote.profileID }), + let bookID = books.first(where: { $0.contentIdentity == remote.bookIdentity })?.id else { return false } + if let index = readingStates.firstIndex(where: { $0.profileID == remote.profileID && $0.bookID == bookID }) { + guard remote.modifiedAt >= readingStates[index].updatedAt else { return true } + readingStates[index].lastReadProgression = remote.progression + readingStates[index].lastReadLocatorJSON = remote.locatorJSON + readingStates[index].updatedAt = remote.modifiedAt + } else { + readingStates.append(ReadingState( + profileID: remote.profileID, + bookID: bookID, + lastReadProgression: remote.progression, + lastReadLocatorJSON: remote.locatorJSON, + updatedAt: remote.modifiedAt + )) + } + return true + case .bookmark(let remote): + guard profiles.contains(where: { $0.id == remote.profileID }), + let bookID = books.first(where: { $0.contentIdentity == remote.bookIdentity })?.id else { return false } + guard let sticker = BookmarkSticker(rawValue: remote.sticker) else { return true } + let value = Bookmark( + id: remote.id, + profileID: remote.profileID, + bookID: bookID, + locatorJSON: remote.locatorJSON, + title: remote.title, + progression: remote.progression, + sticker: sticker, + createdAt: remote.createdAt, + modifiedAt: remote.modifiedAt + ) + if let index = bookmarks.firstIndex(where: { $0.id == remote.id }) { + if remote.modifiedAt >= bookmarks[index].modifiedAt { bookmarks[index] = value } + } else { + bookmarks.append(value) + } + return true + case .savedWord(let remote): + guard profiles.contains(where: { $0.id == remote.profileID }), + let bookID = books.first(where: { $0.contentIdentity == remote.bookIdentity })?.id else { return false } + let value = SavedWord( + id: remote.id, + profileID: remote.profileID, + word: remote.canonicalWord, + displayWord: remote.displayWord, + bookID: bookID, + bookTitle: remote.bookTitle, + tapCount: remote.tapCount, + savedAt: remote.savedAt, + lastTappedAt: remote.lastTappedAt, + modifiedAt: remote.modifiedAt + ) + if let index = savedWords.firstIndex(where: { $0.id == remote.id }) { + let local = syncedSavedWord(savedWords[index], bookIdentity: remote.bookIdentity) + guard case .savedWord(let merged) = LibraryConflictResolver.merge( + local: .savedWord(local), + remote: record + ) else { return true } + savedWords[index] = SavedWord( + id: merged.id, + profileID: merged.profileID, + word: merged.canonicalWord, + displayWord: merged.displayWord, + bookID: bookID, + bookTitle: merged.bookTitle, + tapCount: merged.tapCount, + savedAt: merged.savedAt, + lastTappedAt: merged.lastTappedAt, + modifiedAt: merged.modifiedAt + ) + } else { + savedWords.append(value) + } + return true + } + } + + private func syncedSavedWord(_ word: SavedWord, bookIdentity: String) -> SyncedSavedWord { + SyncedSavedWord( + id: word.id, + profileID: word.profileID, + bookIdentity: bookIdentity, + canonicalWord: word.word, + displayWord: word.displayWord, + bookTitle: word.bookTitle, + tapCount: word.tapCount, + savedAt: word.savedAt, + lastTappedAt: word.lastTappedAt, + modifiedAt: word.modifiedAt + ) + } + + private func applyRemoteDelete(_ reference: LibraryRecordReference) -> Bool { + switch reference.recordType { + case "Book": + guard let book = books.first(where: { $0.contentIdentity == reference.recordName }) else { return true } + try? FileManager.default.removeItem(at: bookURL(for: book)) + if let coverImageName = book.coverImageName { + try? FileManager.default.removeItem(at: coversURL.appendingPathComponent(coverImageName)) + } + books.removeAll { $0.id == book.id } + readingStates.removeAll { $0.bookID == book.id } + bookmarks.removeAll { $0.bookID == book.id } + savedWords.removeAll { $0.bookID == book.id } + return true + case "ReaderProfile": + guard let id = uuid(from: reference.recordName, prefix: "profile-") else { return true } + if profiles.count == 1, profiles[0].id == id { + let replacement = ReaderProfile() + guard persistSyncRecords(syncRecords(for: replacement)) else { return false } + profiles.append(replacement) + selectedProfileID = replacement.id + } + profiles.removeAll { $0.id == id } + readingStates.removeAll { $0.profileID == id } + bookmarks.removeAll { $0.profileID == id } + savedWords.removeAll { $0.profileID == id } + return true + case "ReadingState": + readingStates.removeAll { readingStateReference(for: $0) == reference } + return true + case "Bookmark": + if let id = uuid(from: reference.recordName, prefix: "bookmark-") { + bookmarks.removeAll { $0.id == id } + } + return true + case "SavedWord": + if let id = uuid(from: reference.recordName, prefix: "word-") { + savedWords.removeAll { $0.id == id } + } + return true + case "ReaderPreferences": + return true + default: + return true + } + } + + private func uuid(from recordName: String, prefix: String) -> UUID? { + guard recordName.hasPrefix(prefix) else { return nil } + return UUID(uuidString: String(recordName.dropFirst(prefix.count))) + } } enum BookStoreError: Error { case invalidURL case unreadableBook case contentIdentityCollision + case syncOutboxUnavailable } diff --git a/Piperly/Services/Sync/CloudKitLibrarySync.swift b/Piperly/Services/Sync/CloudKitLibrarySync.swift new file mode 100644 index 0000000..e793adf --- /dev/null +++ b/Piperly/Services/Sync/CloudKitLibrarySync.swift @@ -0,0 +1,658 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import CloudKit +import Foundation +import UIKit + +actor CloudKitLibrarySync: LibrarySyncSink { + typealias RemoteChangeHandler = @MainActor @Sendable ( + [LibraryRemoteChange], + RemoteApplicationScope + ) -> RemoteApplicationResult + typealias LocalSnapshotProvider = @MainActor @Sendable () -> [LibraryRecord] + + static let containerIdentifier = "iCloud.com.piperly.app" + static let enabledDefaultsKey = "piperly_icloud_sync_enabled" + + static func isEnabled(in defaults: UserDefaults = .standard) -> Bool { + defaults.bool(forKey: enabledDefaultsKey) + } + + private let container: CKContainer + private let stateStore: SyncStateStore + private let remoteChangeHandler: RemoteChangeHandler + private let localSnapshotProvider: LocalSnapshotProvider + private let automaticallySync: Bool + private var snapshot: SyncStateSnapshot + private var engine: CKSyncEngine? + private var needsAccountConfirmation = false + private var accountTransitionInProgress = false + private(set) var status: LibrarySyncStatus + + init( + enabled: Bool, + container: CKContainer = CKContainer(identifier: CloudKitLibrarySync.containerIdentifier), + stateURL: URL = CloudKitLibrarySync.defaultStateURL, + automaticallySync: Bool = true, + localSnapshotProvider: @escaping LocalSnapshotProvider = { [] }, + remoteChangeHandler: @escaping RemoteChangeHandler + ) throws { + self.container = container + stateStore = SyncStateStore(fileURL: stateURL) + self.remoteChangeHandler = remoteChangeHandler + self.localSnapshotProvider = localSnapshotProvider + self.automaticallySync = automaticallySync + snapshot = try stateStore.load() + status = enabled ? .idle : .disabled + needsAccountConfirmation = enabled + + if enabled { + Task { await self.prepareInitialAccount() } + } + } + + static var defaultStateURL: URL { + FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0] + .appendingPathComponent("Piperly", isDirectory: true) + .appendingPathComponent("CloudKitSync.json") + } + + private func prepareInitialAccount() async { + guard let currentUser = try? await container.userRecordID() else { + status = .blocked(.accountUnavailable) + return + } + if SyncCurrentAccountOperations.hasOperations(snapshot: snapshot) { + SyncCurrentAccountOperations.reQuarantine(snapshot: &snapshot) + snapshot.confirmedAccountRecordName = nil + } + guard snapshot.confirmedAccountRecordName == currentUser.recordName else { + SyncAccountTransition.quarantine(snapshot: &snapshot) + needsAccountConfirmation = true + status = .accountConfirmationRequired + persistSnapshot() + return + } + SyncAccountTransition.resolve(policy: .keepLocalAndUploadAfterFetch, snapshot: &snapshot) + needsAccountConfirmation = false + persistSnapshot() + start() + } + + func start(automaticallySync override: Bool? = nil, restorePending: Bool = true) { + guard status != .disabled, engine == nil, !needsAccountConfirmation else { return } + Task { @MainActor in + UIApplication.shared.registerForRemoteNotifications() + } + var configuration = CKSyncEngine.Configuration( + database: container.privateCloudDatabase, + stateSerialization: snapshot.engineState, + delegate: self + ) + configuration.automaticallySync = override ?? automaticallySync + configuration.subscriptionID = "PiperlyLibrary-private" + let newEngine = CKSyncEngine(configuration) + engine = newEngine + if restorePending { restorePendingChanges(to: newEngine) } + } + + func acceptSave(_ record: LibraryRecord, scope: RemoteApplicationScope) async throws { + let reference = record.reference + if scope.isCurrentAccount { + guard let accountRecordName = scope.accountRecordName, + let transitionGeneration = scope.transitionGeneration else { return } + if matchesActiveTransition(scope) { + SyncCurrentAccountOperations.recordSave( + record, + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration, + snapshot: &snapshot + ) + } else if matchesConfirmedTransition(scope) { + snapshot.pendingDeletes.removeAll { $0 == reference } + snapshot.pendingSaves[reference.recordName] = record + } else { + quarantineSave(record) + requireNewAccountConfirmation() + } + try persistSnapshotOrThrow() + return + } + if needsAccountConfirmation || accountTransitionInProgress { + snapshot.quarantinedDeletes.removeAll { $0 == reference } + snapshot.quarantinedSaves[reference.recordName] = record + try persistSnapshotOrThrow() + return + } + snapshot.pendingDeletes.removeAll { $0 == reference } + snapshot.pendingSaves[reference.recordName] = record + try persistSnapshotOrThrow() + guard let engine = activeEngine() else { return } + engine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID(for: reference))]) + } + + func acceptDelete( + _ reference: LibraryRecordReference, + scope: RemoteApplicationScope + ) async throws { + if scope.isCurrentAccount { + guard let accountRecordName = scope.accountRecordName, + let transitionGeneration = scope.transitionGeneration else { return } + if matchesActiveTransition(scope) { + SyncCurrentAccountOperations.recordDelete( + reference, + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration, + snapshot: &snapshot + ) + } else if matchesConfirmedTransition(scope) { + snapshot.pendingSaves[reference.recordName] = nil + snapshot.pendingDeletes.removeAll { $0 == reference } + snapshot.pendingDeletes.append(reference) + } else { + quarantineDelete(reference) + requireNewAccountConfirmation() + } + try persistSnapshotOrThrow() + return + } + if needsAccountConfirmation || accountTransitionInProgress { + snapshot.quarantinedSaves[reference.recordName] = nil + snapshot.quarantinedDeletes.removeAll { $0 == reference } + snapshot.quarantinedDeletes.append(reference) + try persistSnapshotOrThrow() + return + } + snapshot.pendingSaves[reference.recordName] = nil + snapshot.pendingDeletes.removeAll { $0 == reference } + snapshot.pendingDeletes.append(reference) + try persistSnapshotOrThrow() + guard let engine = activeEngine() else { return } + engine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID(for: reference))]) + } + + func syncNow() async throws { + guard let engine = activeEngine() else { return } + try await engine.fetchChanges(CKSyncEngine.FetchChangesOptions()) + try await engine.sendChanges(CKSyncEngine.SendChangesOptions()) + } + + func accountState() async -> SyncAccountState { + guard status != .disabled else { return .couldNotDetermine } + do { + switch try await container.accountStatus() { + case .available: + return .available + case .noAccount: + return .noAccount + case .restricted: + return .restricted + case .temporarilyUnavailable: + return .temporarilyUnavailable + case .couldNotDetermine: + return .couldNotDetermine + @unknown default: + return .couldNotDetermine + } + } catch { + return .couldNotDetermine + } + } + + func confirmAccountChange(policy: AccountTransitionPolicy) async throws { + guard needsAccountConfirmation else { return } + do { + let generation = beginAccountTransition() + let currentUser = try await container.userRecordID() + try requireAccountTransition(generation) + snapshot.accountTransitionAccountRecordName = currentUser.recordName + let initialLocalRecords = await localSnapshotProvider() + try requireAccountTransition(generation) + try persistSnapshotOrThrow() + start(automaticallySync: false, restorePending: false) + guard let fetchEngine = engine else { + throw SyncAccountTransitionError.accountChangedDuringConfirmation + } + try await fetchEngine.fetchChanges(CKSyncEngine.FetchChangesOptions()) + try requireAccountTransition(generation) + await fetchEngine.cancelOperations() + try requireAccountTransition(generation) + engine = nil + let firstVerification = try await container.userRecordID() + try requireAccountTransition(generation) + try SyncAccountTransitionValidator.validate( + initialRecordName: currentUser.recordName, + verifiedRecordName: firstVerification.recordName + ) + let applicationResult = await applyStagedAccountChanges( + policy: policy, + initialLocalRecords: initialLocalRecords, + accountRecordName: currentUser.recordName, + transitionGeneration: generation + ) + try requireAccountTransition(generation) + let postMergeLocalRecords = await localSnapshotProvider() + try requireAccountTransition(generation) + let finalVerification = try await container.userRecordID() + try requireAccountTransition(generation) + try SyncAccountTransitionValidator.validate( + initialRecordName: currentUser.recordName, + verifiedRecordName: finalVerification.recordName + ) + snapshot.deferredRemoteRecords = Dictionary( + uniqueKeysWithValues: applicationResult.unresolvedRecords.map { + ($0.reference.recordName, $0) + } + ) + snapshot.deferredRemoteDeletions = applicationResult.unresolvedDeletions + snapshot.accountTransitionRemoteRecords = [:] + snapshot.accountTransitionRemoteDeletions = [] + SyncAccountTransition.refreshQuarantinedSaves( + from: postMergeLocalRecords, + snapshot: &snapshot + ) + SyncAccountTransition.resolve(policy: policy, snapshot: &snapshot) + guard SyncCurrentAccountOperations.commitIfMatching( + accountRecordName: finalVerification.recordName, + transitionGeneration: generation, + snapshot: &snapshot + ) else { + throw SyncAccountTransitionError.accountChangedDuringConfirmation + } + SyncInitialLibrarySeeder.seedIfNeeded( + records: postMergeLocalRecords, + policy: policy, + snapshot: &snapshot + ) + snapshot.confirmedAccountRecordName = finalVerification.recordName + snapshot.accountTransitionAccountRecordName = nil + try requireAccountTransition(generation) + accountTransitionInProgress = false + needsAccountConfirmation = false + status = .idle + try persistSnapshotOrThrow() + start() + } catch { + failAccountTransitionIfActive() + throw error + } + } + + private func matchesActiveTransition(_ scope: RemoteApplicationScope) -> Bool { + accountTransitionInProgress + && scope.accountRecordName == snapshot.accountTransitionAccountRecordName + && scope.transitionGeneration == snapshot.accountTransitionGeneration + } + + private func matchesConfirmedTransition(_ scope: RemoteApplicationScope) -> Bool { + !accountTransitionInProgress + && !needsAccountConfirmation + && scope.accountRecordName == snapshot.confirmedAccountRecordName + && scope.transitionGeneration == snapshot.accountTransitionGeneration + } + + private func quarantineSave(_ record: LibraryRecord) { + snapshot.quarantinedDeletes.removeAll { $0 == record.reference } + snapshot.quarantinedSaves[record.reference.recordName] = record + } + + private func quarantineDelete(_ reference: LibraryRecordReference) { + snapshot.quarantinedSaves[reference.recordName] = nil + snapshot.quarantinedDeletes.removeAll { $0 == reference } + snapshot.quarantinedDeletes.append(reference) + } + + private func requireNewAccountConfirmation() { + if accountTransitionInProgress { + invalidateAccountTransition() + return + } + if let engine { Task { await engine.cancelOperations() } } + engine = nil + SyncAccountTransition.quarantine(snapshot: &snapshot) + snapshot.confirmedAccountRecordName = nil + needsAccountConfirmation = true + status = .accountConfirmationRequired + } + + private func activeEngine() -> CKSyncEngine? { + guard status != .disabled, !needsAccountConfirmation, !accountTransitionInProgress else { return nil } + if engine == nil { start() } + return engine + } + + private func restorePendingChanges(to engine: CKSyncEngine) { + engine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: LibraryRecordCodec.zoneID))]) + let saves = snapshot.pendingSaves.values.map { record in + CKSyncEngine.PendingRecordZoneChange.saveRecord(recordID(for: record.reference)) + } + let deletes = snapshot.pendingDeletes.map { reference in + CKSyncEngine.PendingRecordZoneChange.deleteRecord(recordID(for: reference)) + } + engine.state.add(pendingRecordZoneChanges: saves + deletes) + } + + private func recordID(for reference: LibraryRecordReference) -> CKRecord.ID { + CKRecord.ID(recordName: reference.recordName, zoneID: LibraryRecordCodec.zoneID) + } + + private func persistSnapshot() { + do { + try stateStore.save(snapshot) + } catch { + status = .blocked(.missingLocalData) + } + } + + private func persistSnapshotOrThrow() throws { + do { + try stateStore.save(snapshot) + } catch { + status = .blocked(.missingLocalData) + throw error + } + } +} + +extension CloudKitLibrarySync: CKSyncEngineDelegate { + func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) async { + switch event { + case .stateUpdate(let update): + snapshot.engineState = update.stateSerialization + persistSnapshot() + case .accountChange where accountTransitionInProgress: + abortAccountTransition(syncEngine: syncEngine) + case .accountChange(let change) where accountRequiresConfirmation(change): + abortAccountTransition(syncEngine: syncEngine) + case .accountChange: + break + case .fetchedRecordZoneChanges(let changes): + await handleFetched(changes) + case .sentRecordZoneChanges(let changes): + handleSent(changes, syncEngine: syncEngine) + case .sentDatabaseChanges(let changes): + handleSentDatabaseChanges(changes, syncEngine: syncEngine) + case .willFetchChanges, .willSendChanges: + status = .syncing + case .didFetchChanges, .didSendChanges: + if !needsAccountConfirmation { status = .idle } + case .fetchedDatabaseChanges(let changes): + if changes.deletions.contains(where: { $0.zoneID == LibraryRecordCodec.zoneID }) { + syncEngine.state.add(pendingDatabaseChanges: [ + .saveZone(CKRecordZone(zoneID: LibraryRecordCodec.zoneID)), + ]) + } + case .willFetchRecordZoneChanges, .didFetchRecordZoneChanges: + break + @unknown default: + break + } + } + + func nextRecordZoneChangeBatch( + _ context: CKSyncEngine.SendChangesContext, + syncEngine: CKSyncEngine + ) async -> CKSyncEngine.RecordZoneChangeBatch? { + guard !needsAccountConfirmation, !accountTransitionInProgress else { return nil } + let pending = syncEngine.state.pendingRecordZoneChanges.filter { context.options.scope.contains($0) } + let records = snapshot.pendingSaves + let systemFields = snapshot.systemFields + return await CKSyncEngine.RecordZoneChangeBatch(pendingChanges: pending) { recordID in + guard let record = records[recordID.recordName] else { return nil } + return try? LibraryRecordCodec.encode(record, systemFields: systemFields[recordID.recordName]) + } + } + + private func handleFetched(_ event: CKSyncEngine.Event.FetchedRecordZoneChanges) async { + guard !needsAccountConfirmation else { return } + if accountTransitionInProgress { + stageFetchedForAccountTransition(event) + persistSnapshot() + return + } + var records = snapshot.deferredRemoteRecords + var deletionReferences = snapshot.deferredRemoteDeletions + for modification in event.modifications where modification.record.recordID.zoneID == LibraryRecordCodec.zoneID { + let record = modification.record + guard let decoded = try? LibraryRecordCodec.decode(record) else { continue } + let reference = decoded.reference + let hasTombstone = FetchedRecordReconciler.isTombstoned( + reference, + pendingDeletes: snapshot.pendingDeletes, + quarantinedDeletes: snapshot.quarantinedDeletes + ) + if hasTombstone { + records[reference.recordName] = nil + engine?.state.add(pendingRecordZoneChanges: [.deleteRecord(record.recordID)]) + continue + } + let value: LibraryRecord + if let pending = snapshot.pendingSaves[record.recordID.recordName] { + value = LibraryConflictResolver.merge(local: pending, remote: decoded) + snapshot.pendingSaves[record.recordID.recordName] = value + } else { + value = decoded + } + snapshot.systemFields[record.recordID.recordName] = LibraryRecordCodec.systemFieldsData(for: record) + records[reference.recordName] = value + } + for deletion in event.deletions where deletion.recordID.zoneID == LibraryRecordCodec.zoneID { + let reference = LibraryRecordReference( + recordType: deletion.recordType, + recordName: deletion.recordID.recordName + ) + FetchedRecordReconciler.applyRemoteDeletion(reference, snapshot: &snapshot) + records[reference.recordName] = nil + deletionReferences.removeAll { $0 == reference } + deletionReferences.append(reference) + } + let saves = records.values.map(LibraryRemoteChange.save) + let changes = deletionReferences.map(LibraryRemoteChange.delete) + saves + if changes.isEmpty { + snapshot.deferredRemoteRecords = records + } else { + let result = await remoteChangeHandler(changes, .normal) + snapshot.deferredRemoteRecords = Dictionary( + uniqueKeysWithValues: result.unresolvedRecords.map { ($0.reference.recordName, $0) } + ) + snapshot.deferredRemoteDeletions = result.unresolvedDeletions + } + persistSnapshot() + } + + private func stageFetchedForAccountTransition( + _ event: CKSyncEngine.Event.FetchedRecordZoneChanges + ) { + for modification in event.modifications where modification.record.recordID.zoneID == LibraryRecordCodec.zoneID { + let record = modification.record + guard let decoded = try? LibraryRecordCodec.decode(record) else { continue } + snapshot.accountTransitionRemoteDeletions.removeAll { $0 == decoded.reference } + snapshot.accountTransitionRemoteRecords[decoded.reference.recordName] = decoded + snapshot.systemFields[record.recordID.recordName] = LibraryRecordCodec.systemFieldsData(for: record) + } + for deletion in event.deletions where deletion.recordID.zoneID == LibraryRecordCodec.zoneID { + let reference = LibraryRecordReference( + recordType: deletion.recordType, + recordName: deletion.recordID.recordName + ) + snapshot.accountTransitionRemoteRecords[reference.recordName] = nil + snapshot.accountTransitionRemoteDeletions.removeAll { $0 == reference } + snapshot.accountTransitionRemoteDeletions.append(reference) + snapshot.systemFields[reference.recordName] = nil + } + } + + private func handleSent( + _ event: CKSyncEngine.Event.SentRecordZoneChanges, + syncEngine: CKSyncEngine + ) { + for record in event.savedRecords { + snapshot.systemFields[record.recordID.recordName] = LibraryRecordCodec.systemFieldsData(for: record) + if let pending = snapshot.pendingSaves[record.recordID.recordName], + let sent = try? LibraryRecordCodec.decode(record), pending == sent { + snapshot.pendingSaves[record.recordID.recordName] = nil + } else if let pending = snapshot.pendingSaves[record.recordID.recordName] { + syncEngine.state.add(pendingRecordZoneChanges: [ + .saveRecord(recordID(for: pending.reference)), + ]) + } + } + for recordID in event.deletedRecordIDs { + snapshot.pendingDeletes.removeAll { $0.recordName == recordID.recordName } + snapshot.systemFields[recordID.recordName] = nil + if let pending = snapshot.pendingSaves[recordID.recordName] { + syncEngine.state.add(pendingRecordZoneChanges: [ + .saveRecord(self.recordID(for: pending.reference)), + ]) + } + } + for failure in event.failedRecordSaves { + handleSaveFailure(failure, syncEngine: syncEngine) + } + for (recordID, error) in event.failedRecordDeletes { + apply(error: error) + if case .retryable = CloudKitErrorClassifier.classify(error) { + syncEngine.state.add(pendingRecordZoneChanges: [.deleteRecord(recordID)]) + } + } + persistSnapshot() + } + + private func handleSaveFailure( + _ failure: CKSyncEngine.Event.SentRecordZoneChanges.FailedRecordSave, + syncEngine: CKSyncEngine + ) { + let recordID = failure.record.recordID + if failure.error.code == .serverRecordChanged, + let serverRecord = failure.error.serverRecord, + let remote = try? LibraryRecordCodec.decode(serverRecord), + let local = snapshot.pendingSaves[recordID.recordName] { + snapshot.pendingSaves[recordID.recordName] = LibraryConflictResolver.merge(local: local, remote: remote) + snapshot.systemFields[recordID.recordName] = LibraryRecordCodec.systemFieldsData(for: serverRecord) + syncEngine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)]) + return + } + if failure.error.code == .zoneNotFound { + syncEngine.state.add(pendingDatabaseChanges: [.saveZone(CKRecordZone(zoneID: LibraryRecordCodec.zoneID))]) + syncEngine.state.add(pendingRecordZoneChanges: [.saveRecord(recordID)]) + return + } + apply(error: failure.error) + if let pending = CloudKitRetryPolicy.pendingSave(recordID: recordID, error: failure.error) { + syncEngine.state.add(pendingRecordZoneChanges: [pending]) + } + } + + private func handleSentDatabaseChanges( + _ event: CKSyncEngine.Event.SentDatabaseChanges, + syncEngine: CKSyncEngine + ) { + for failure in event.failedZoneSaves { + apply(error: failure.error) + if case .retryable = CloudKitErrorClassifier.classify(failure.error) { + syncEngine.state.add(pendingDatabaseChanges: [.saveZone(failure.zone)]) + } + } + } + + private func apply(error: CKError) { + let failure = CloudKitErrorClassifier.classify(error) + if case .retryable(let retryAfter) = failure { + status = .waitingToRetry(retryAfter) + } else { + status = .blocked(failure) + } + } + + private func accountRequiresConfirmation(_ change: CKSyncEngine.Event.AccountChange) -> Bool { + switch change.changeType { + case .signIn(let currentUser): + currentUser.recordName != snapshot.confirmedAccountRecordName + case .signOut, .switchAccounts: + true + @unknown default: + true + } + } + + private func beginAccountTransition() -> Int { + SyncCurrentAccountOperations.reQuarantine(snapshot: &snapshot) + snapshot.accountTransitionGeneration += 1 + engine = nil + snapshot.engineState = nil + snapshot.systemFields = [:] + snapshot.accountTransitionRemoteRecords = [:] + snapshot.accountTransitionRemoteDeletions = [] + snapshot.accountTransitionAccountRecordName = nil + needsAccountConfirmation = false + accountTransitionInProgress = true + status = .syncing + return snapshot.accountTransitionGeneration + } + + private func requireAccountTransition(_ generation: Int) throws { + try SyncAccountTransitionValidator.validateGeneration( + expected: generation, + current: snapshot.accountTransitionGeneration, + isTransitionActive: accountTransitionInProgress + ) + } + + private func applyStagedAccountChanges( + policy: AccountTransitionPolicy, + initialLocalRecords: [LibraryRecord], + accountRecordName: String, + transitionGeneration: Int + ) async -> RemoteApplicationResult { + let changes = AccountTransitionRemoteReconciler.changes( + records: Array(snapshot.accountTransitionRemoteRecords.values), + deletions: snapshot.accountTransitionRemoteDeletions, + policy: policy, + initialLocalRecords: initialLocalRecords, + quarantinedSaves: Array(snapshot.quarantinedSaves.values), + quarantinedDeletes: snapshot.quarantinedDeletes + ) + guard !changes.isEmpty else { return .complete } + return await remoteChangeHandler( + changes, + .currentAccount( + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration + ) + ) + } + + private func failAccountTransitionIfActive() { + guard accountTransitionInProgress else { return } + if let engine { Task { await engine.cancelOperations() } } + invalidateAccountTransition() + persistSnapshot() + } + + private func invalidateAccountTransition() { + SyncCurrentAccountOperations.reQuarantine(snapshot: &snapshot) + snapshot.accountTransitionGeneration += 1 + engine = nil + snapshot.engineState = nil + snapshot.systemFields = [:] + snapshot.confirmedAccountRecordName = nil + snapshot.accountTransitionRemoteRecords = [:] + snapshot.accountTransitionRemoteDeletions = [] + snapshot.accountTransitionAccountRecordName = nil + SyncAccountTransition.quarantine(snapshot: &snapshot) + needsAccountConfirmation = true + accountTransitionInProgress = false + status = .accountConfirmationRequired + } + + private func abortAccountTransition(syncEngine: CKSyncEngine) { + invalidateAccountTransition() + persistSnapshot() + Task { await syncEngine.cancelOperations() } + } +} + +enum SyncAccountTransitionError: Error, Equatable { + case accountChangedDuringConfirmation +} diff --git a/Piperly/Services/Sync/LibraryConflictResolver.swift b/Piperly/Services/Sync/LibraryConflictResolver.swift new file mode 100644 index 0000000..b73d930 --- /dev/null +++ b/Piperly/Services/Sync/LibraryConflictResolver.swift @@ -0,0 +1,55 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import Foundation + +enum LibraryConflictResolver { + static func merge(local: LibraryRecord, remote: LibraryRecord) -> LibraryRecord { + switch (local, remote) { + case (.book(let local), .book(let remote)): + return .book(merge(local: local, remote: remote)) + case (.readerProfile(let local), .readerProfile(let remote)): + return .readerProfile(local.modifiedAt >= remote.modifiedAt ? local : remote) + case (.readerPreferences(let local), .readerPreferences(let remote)): + return .readerPreferences(local.modifiedAt >= remote.modifiedAt ? local : remote) + case (.readingState(let local), .readingState(let remote)): + return .readingState(local.modifiedAt >= remote.modifiedAt ? local : remote) + case (.bookmark(let local), .bookmark(let remote)): + return .bookmark(local.modifiedAt >= remote.modifiedAt ? local : remote) + case (.savedWord(let local), .savedWord(let remote)): + return .savedWord(merge(local: local, remote: remote)) + default: + return remote + } + } + + private static func merge(local: SyncedBook, remote: SyncedBook) -> SyncedBook { + let newest = local.modifiedAt >= remote.modifiedAt ? local : remote + let older = local.modifiedAt >= remote.modifiedAt ? remote : local + return SyncedBook( + id: local.id, + contentIdentity: local.contentIdentity, + title: newest.title.isEmpty ? older.title : newest.title, + author: newest.author.isEmpty ? older.author : newest.author, + originalExtension: newest.originalExtension, + hasCover: newest.hasCover || older.hasCover, + modifiedAt: max(local.modifiedAt, remote.modifiedAt) + ) + } + + private static func merge(local: SyncedSavedWord, remote: SyncedSavedWord) -> SyncedSavedWord { + let newest = local.modifiedAt >= remote.modifiedAt ? local : remote + return SyncedSavedWord( + id: newest.id, + profileID: newest.profileID, + bookIdentity: newest.bookIdentity, + canonicalWord: newest.canonicalWord, + displayWord: newest.displayWord, + bookTitle: newest.bookTitle, + tapCount: max(local.tapCount, remote.tapCount), + savedAt: min(local.savedAt, remote.savedAt), + lastTappedAt: max(local.lastTappedAt, remote.lastTappedAt), + modifiedAt: max(local.modifiedAt, remote.modifiedAt) + ) + } +} diff --git a/Piperly/Services/Sync/LibraryRecord.swift b/Piperly/Services/Sync/LibraryRecord.swift new file mode 100644 index 0000000..2630f34 --- /dev/null +++ b/Piperly/Services/Sync/LibraryRecord.swift @@ -0,0 +1,118 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import Foundation + +struct SyncedBook: Codable, Sendable, Equatable { + let id: UUID + let contentIdentity: String + var title: String + var author: String + let originalExtension: String + var hasCover: Bool + var modifiedAt: Date +} + +struct SyncedReaderProfile: Codable, Sendable, Equatable { + let id: UUID + var nickname: String + var avatarSymbol: String + var colorName: String + let createdAt: Date + var modifiedAt: Date +} + +struct SyncedReaderPreferences: Codable, Sendable, Equatable { + let profileID: UUID + var voiceIdentifier: String + var speechRate: Double + var fontSize: Double + var readerTheme: String + var hasCompletedVoiceSetup: Bool + var modifiedAt: Date +} + +struct SyncedReadingState: Codable, Sendable, Equatable { + let profileID: UUID + let bookIdentity: String + var progression: Double + var locatorJSON: String? + var modifiedAt: Date +} + +struct SyncedBookmark: Codable, Sendable, Equatable { + let id: UUID + let profileID: UUID + let bookIdentity: String + var locatorJSON: String + var title: String? + var progression: Double + var sticker: String + let createdAt: Date + var modifiedAt: Date +} + +struct SyncedSavedWord: Codable, Sendable, Equatable { + let id: UUID + let profileID: UUID + let bookIdentity: String + var canonicalWord: String + var displayWord: String + var bookTitle: String + var tapCount: Int + var savedAt: Date + var lastTappedAt: Date + var modifiedAt: Date +} + +struct LibraryRecordReference: Codable, Sendable, Hashable { + let recordType: String + let recordName: String +} + +enum LibraryRecord: Codable, Sendable, Equatable { + case book(SyncedBook) + case readerProfile(SyncedReaderProfile) + case readerPreferences(SyncedReaderPreferences) + case readingState(SyncedReadingState) + case bookmark(SyncedBookmark) + case savedWord(SyncedSavedWord) + + var reference: LibraryRecordReference { + switch self { + case .book(let value): + LibraryRecordReference(recordType: "Book", recordName: value.contentIdentity.lowercased()) + case .readerProfile(let value): + LibraryRecordReference(recordType: "ReaderProfile", recordName: "profile-\(value.id.cloudRecordName)") + case .readerPreferences(let value): + LibraryRecordReference( + recordType: "ReaderPreferences", + recordName: "preferences-\(value.profileID.cloudRecordName)" + ) + case .readingState(let value): + LibraryRecordReference( + recordType: "ReadingState", + recordName: "reading-\(value.profileID.cloudRecordName)-\(value.bookIdentity.lowercased())" + ) + case .bookmark(let value): + LibraryRecordReference(recordType: "Bookmark", recordName: "bookmark-\(value.id.cloudRecordName)") + case .savedWord(let value): + LibraryRecordReference(recordType: "SavedWord", recordName: "word-\(value.id.cloudRecordName)") + } + } +} + +extension LibraryRecord { + var remoteApplicationOrder: Int { + switch self { + case .book, .readerProfile: + 0 + case .readerPreferences, .readingState, .bookmark, .savedWord: + 1 + } + } +} + +private extension UUID { + var cloudRecordName: String { uuidString.lowercased() } +} diff --git a/Piperly/Services/Sync/LibraryRecordCodec.swift b/Piperly/Services/Sync/LibraryRecordCodec.swift new file mode 100644 index 0000000..df76e07 --- /dev/null +++ b/Piperly/Services/Sync/LibraryRecordCodec.swift @@ -0,0 +1,203 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import CloudKit +import Foundation + +enum LibraryRecordCodecError: Error, Equatable { + case unsupportedRecordType(String) + case missingField(String) + case invalidField(String) +} + +enum LibraryRecordCodec { + static let zoneID = CKRecordZone.ID(zoneName: "PiperlyLibrary", ownerName: CKCurrentUserDefaultName) + + static func encode(_ value: LibraryRecord, systemFields: Data? = nil) throws -> CKRecord { + let reference = value.reference + let recordID = CKRecord.ID(recordName: reference.recordName, zoneID: zoneID) + let record: CKRecord + if let systemFields, + let decoded = try? CKRecord(systemFieldsData: systemFields), + decoded.recordID == recordID { + record = decoded + } else { + record = CKRecord(recordType: reference.recordType, recordID: recordID) + } + + switch value { + case .book(let book): + record["localID"] = book.id.uuidString.lowercased() + record["title"] = book.title + record["author"] = book.author + record["originalExtension"] = book.originalExtension + record["hasCover"] = book.hasCover ? 1 : 0 + record["modifiedAt"] = book.modifiedAt + case .readerProfile(let profile): + record["nickname"] = profile.nickname + record["avatarSymbol"] = profile.avatarSymbol + record["colorName"] = profile.colorName + record["createdAt"] = profile.createdAt + record["modifiedAt"] = profile.modifiedAt + case .readerPreferences(let preferences): + record["profileID"] = preferences.profileID.uuidString.lowercased() + record["voiceIdentifier"] = preferences.voiceIdentifier + record["speechRate"] = preferences.speechRate + record["fontSize"] = preferences.fontSize + record["readerTheme"] = preferences.readerTheme + record["hasCompletedVoiceSetup"] = preferences.hasCompletedVoiceSetup ? 1 : 0 + record["modifiedAt"] = preferences.modifiedAt + case .readingState(let state): + record["profileID"] = state.profileID.uuidString.lowercased() + record["bookIdentity"] = state.bookIdentity.lowercased() + record["progression"] = state.progression + record["locatorJSON"] = state.locatorJSON + record["modifiedAt"] = state.modifiedAt + case .bookmark(let bookmark): + record["profileID"] = bookmark.profileID.uuidString.lowercased() + record["bookIdentity"] = bookmark.bookIdentity.lowercased() + record["locatorJSON"] = bookmark.locatorJSON + record["title"] = bookmark.title + record["progression"] = bookmark.progression + record["sticker"] = bookmark.sticker + record["createdAt"] = bookmark.createdAt + record["modifiedAt"] = bookmark.modifiedAt + case .savedWord(let word): + record["profileID"] = word.profileID.uuidString.lowercased() + record["bookIdentity"] = word.bookIdentity.lowercased() + record["canonicalWord"] = word.canonicalWord + record["displayWord"] = word.displayWord + record["bookTitle"] = word.bookTitle + record["tapCount"] = word.tapCount + record["savedAt"] = word.savedAt + record["lastTappedAt"] = word.lastTappedAt + record["modifiedAt"] = word.modifiedAt + } + return record + } + + static func decode(_ record: CKRecord) throws -> LibraryRecord { + switch record.recordType { + case "Book": + return .book(SyncedBook( + id: try uuid("localID", record), + contentIdentity: record.recordID.recordName.lowercased(), + title: try string("title", record), + author: try string("author", record), + originalExtension: try string("originalExtension", record), + hasCover: try bool("hasCover", record), + modifiedAt: try date("modifiedAt", record) + )) + case "ReaderProfile": + return .readerProfile(SyncedReaderProfile( + id: try recordUUID(record, prefix: "profile-"), + nickname: try string("nickname", record), + avatarSymbol: try string("avatarSymbol", record), + colorName: try string("colorName", record), + createdAt: try date("createdAt", record), + modifiedAt: try date("modifiedAt", record) + )) + case "ReaderPreferences": + return .readerPreferences(SyncedReaderPreferences( + profileID: try uuid("profileID", record), + voiceIdentifier: try string("voiceIdentifier", record), + speechRate: try double("speechRate", record), + fontSize: try double("fontSize", record), + readerTheme: try string("readerTheme", record), + hasCompletedVoiceSetup: try bool("hasCompletedVoiceSetup", record), + modifiedAt: try date("modifiedAt", record) + )) + case "ReadingState": + return .readingState(SyncedReadingState( + profileID: try uuid("profileID", record), + bookIdentity: try string("bookIdentity", record), + progression: try double("progression", record), + locatorJSON: record["locatorJSON"] as? String, + modifiedAt: try date("modifiedAt", record) + )) + case "Bookmark": + return .bookmark(SyncedBookmark( + id: try recordUUID(record, prefix: "bookmark-"), + profileID: try uuid("profileID", record), + bookIdentity: try string("bookIdentity", record), + locatorJSON: try string("locatorJSON", record), + title: record["title"] as? String, + progression: try double("progression", record), + sticker: try string("sticker", record), + createdAt: try date("createdAt", record), + modifiedAt: try date("modifiedAt", record) + )) + case "SavedWord": + return .savedWord(SyncedSavedWord( + id: try recordUUID(record, prefix: "word-"), + profileID: try uuid("profileID", record), + bookIdentity: try string("bookIdentity", record), + canonicalWord: try string("canonicalWord", record), + displayWord: try string("displayWord", record), + bookTitle: try string("bookTitle", record), + tapCount: try int("tapCount", record), + savedAt: try date("savedAt", record), + lastTappedAt: try date("lastTappedAt", record), + modifiedAt: try date("modifiedAt", record) + )) + default: + throw LibraryRecordCodecError.unsupportedRecordType(record.recordType) + } + } + + static func systemFieldsData(for record: CKRecord) -> Data { + let archiver = NSKeyedArchiver(requiringSecureCoding: true) + record.encodeSystemFields(with: archiver) + archiver.finishEncoding() + return archiver.encodedData + } + + private static func string(_ key: String, _ record: CKRecord) throws -> String { + guard let value = record[key] as? String else { throw LibraryRecordCodecError.missingField(key) } + return value + } + + private static func date(_ key: String, _ record: CKRecord) throws -> Date { + guard let value = record[key] as? Date else { throw LibraryRecordCodecError.missingField(key) } + return value + } + + private static func double(_ key: String, _ record: CKRecord) throws -> Double { + guard let value = record[key] as? NSNumber else { throw LibraryRecordCodecError.missingField(key) } + return value.doubleValue + } + + private static func int(_ key: String, _ record: CKRecord) throws -> Int { + guard let value = record[key] as? NSNumber else { throw LibraryRecordCodecError.missingField(key) } + return value.intValue + } + + private static func bool(_ key: String, _ record: CKRecord) throws -> Bool { + guard let value = record[key] as? NSNumber else { throw LibraryRecordCodecError.missingField(key) } + return value.boolValue + } + + private static func uuid(_ key: String, _ record: CKRecord) throws -> UUID { + guard let value = UUID(uuidString: try string(key, record)) else { + throw LibraryRecordCodecError.invalidField(key) + } + return value + } + + private static func recordUUID(_ record: CKRecord, prefix: String) throws -> UUID { + guard record.recordID.recordName.hasPrefix(prefix), + let value = UUID(uuidString: String(record.recordID.recordName.dropFirst(prefix.count))) else { + throw LibraryRecordCodecError.invalidField("recordName") + } + return value + } +} + +private extension CKRecord { + convenience init?(systemFieldsData: Data) throws { + let unarchiver = try NSKeyedUnarchiver(forReadingFrom: systemFieldsData) + unarchiver.requiresSecureCoding = true + defer { unarchiver.finishDecoding() } + self.init(coder: unarchiver) + } +} diff --git a/Piperly/Services/Sync/LibrarySyncing.swift b/Piperly/Services/Sync/LibrarySyncing.swift new file mode 100644 index 0000000..7edf341 --- /dev/null +++ b/Piperly/Services/Sync/LibrarySyncing.swift @@ -0,0 +1,278 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import Foundation + +protocol LibrarySyncing: Sendable { + func enqueue(_ operations: [LibraryOutboxOperation]) throws + func flush() throws + func currentOutboxStatus() -> LibraryOutboxStatus +} + +extension LibrarySyncing { + func currentOutboxStatus() -> LibraryOutboxStatus { .ready } + + func enqueueSave(_ record: LibraryRecord) throws { + try enqueue([.save(record)]) + } + + func enqueueDelete(_ reference: LibraryRecordReference) throws { + try enqueue([.delete(reference)]) + } +} + +protocol LibrarySyncSink: Sendable { + func acceptSave(_ record: LibraryRecord, scope: RemoteApplicationScope) async throws + func acceptDelete(_ reference: LibraryRecordReference, scope: RemoteApplicationScope) async throws +} + +struct RemoteApplicationScope: Codable, Sendable, Equatable { + let accountRecordName: String? + let transitionGeneration: Int? + + static let normal = RemoteApplicationScope( + accountRecordName: nil, + transitionGeneration: nil + ) + + static func currentAccount( + accountRecordName: String, + transitionGeneration: Int + ) -> RemoteApplicationScope { + RemoteApplicationScope( + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration + ) + } + + var isCurrentAccount: Bool { + accountRecordName != nil && transitionGeneration != nil + } +} + +enum LibraryRemoteChange: Sendable, Equatable { + case save(LibraryRecord) + case delete(LibraryRecordReference) +} + +struct RemoteApplicationResult: Sendable, Equatable { + let unresolvedRecords: [LibraryRecord] + let unresolvedDeletions: [LibraryRecordReference] + + static let complete = RemoteApplicationResult(unresolvedRecords: [], unresolvedDeletions: []) +} + +struct DisabledLibrarySync: LibrarySyncing { + func enqueue(_ operations: [LibraryOutboxOperation]) throws {} + func flush() throws {} +} + +enum LibraryOutboxStatus: Sendable, Equatable { + case ready + case blocked +} + +enum LibraryOutboxError: Error, Equatable { + case unavailable +} + +struct LibraryOutboxOperation: Codable, Sendable, Equatable { + enum Intent: String, Codable, Sendable { + case save + case delete + } + + let intent: Intent + let reference: LibraryRecordReference + let record: LibraryRecord? + let scope: RemoteApplicationScope? + + var effectiveScope: RemoteApplicationScope { scope ?? .normal } + + static func save(_ record: LibraryRecord) -> LibraryOutboxOperation { + LibraryOutboxOperation(intent: .save, reference: record.reference, record: record, scope: nil) + } + + static func delete(_ reference: LibraryRecordReference) -> LibraryOutboxOperation { + LibraryOutboxOperation(intent: .delete, reference: reference, record: nil, scope: nil) + } +} + +private final class LockedLibraryOutbox: @unchecked Sendable { + private let lock = NSRecursiveLock() + private let store: LibraryOutboxStore + private var operations: [LibraryOutboxOperation] + private var failure: Error? + private var currentAccountScopes: [RemoteApplicationScope] = [] + + init(store: LibraryOutboxStore) { + self.store = store + do { + operations = try store.load() + failure = nil + } catch { + operations = [] + failure = error + } + } + + func append(_ newOperations: [LibraryOutboxOperation]) throws { + try lock.withLock { + guard failure == nil else { throw LibraryOutboxError.unavailable } + var updated = operations + for originalOperation in newOperations { + let operation = currentAccountScopes.last.map { scope in + LibraryOutboxOperation( + intent: originalOperation.intent, + reference: originalOperation.reference, + record: originalOperation.record, + scope: scope + ) + } ?? originalOperation + updated.removeAll { $0.reference == operation.reference } + updated.append(operation) + } + do { + try store.save(updated) + } catch { + failure = error + throw LibraryOutboxError.unavailable + } + operations = updated + } + } + + func first() -> LibraryOutboxOperation? { + lock.withLock { operations.first } + } + + func removeFirst(ifMatching operation: LibraryOutboxOperation) throws { + try lock.withLock { + guard failure == nil else { throw LibraryOutboxError.unavailable } + guard operations.first == operation else { return } + let updated = Array(operations.dropFirst()) + do { + try store.save(updated) + } catch { + failure = error + throw LibraryOutboxError.unavailable + } + operations = updated + } + } + + func flush() throws { + try lock.withLock { + guard failure == nil else { throw LibraryOutboxError.unavailable } + do { + try store.save(operations) + } catch { + failure = error + throw LibraryOutboxError.unavailable + } + } + } + + func snapshot() -> [LibraryOutboxOperation] { + lock.withLock { operations } + } + + func status() -> LibraryOutboxStatus { + lock.withLock { failure == nil ? .ready : .blocked } + } + + func applyingCurrentAccountChanges( + scope: RemoteApplicationScope, + _ body: () -> RemoteApplicationResult + ) -> RemoteApplicationResult { + lock.withLock { currentAccountScopes.append(scope) } + defer { lock.withLock { _ = currentAccountScopes.popLast() } } + return body() + } +} + +actor LibrarySyncRouter: LibrarySyncing { + nonisolated private let outbox: LockedLibraryOutbox + private var target: (any LibrarySyncSink)? + + init(fileURL: URL = LibraryOutboxStore.defaultURL) { + outbox = LockedLibraryOutbox(store: LibraryOutboxStore(fileURL: fileURL)) + } + + func use(_ target: any LibrarySyncSink) async { + self.target = target + await drain() + } + + nonisolated func enqueue(_ operations: [LibraryOutboxOperation]) throws { + try outbox.append(operations) + Task { await self.drain() } + } + + nonisolated func flush() throws { + try outbox.flush() + } + + nonisolated func pendingOperations() -> [LibraryOutboxOperation] { + outbox.snapshot() + } + + nonisolated func outboxStatus() -> LibraryOutboxStatus { + outbox.status() + } + + nonisolated func currentOutboxStatus() -> LibraryOutboxStatus { + outbox.status() + } + + nonisolated func applyingCurrentAccountChanges( + scope: RemoteApplicationScope, + _ body: () -> RemoteApplicationResult + ) -> RemoteApplicationResult { + outbox.applyingCurrentAccountChanges(scope: scope, body) + } + + private func drain() async { + guard let target else { return } + while let operation = outbox.first() { + do { + switch operation.intent { + case .save: + guard let record = operation.record else { return } + try await target.acceptSave(record, scope: operation.effectiveScope) + case .delete: + try await target.acceptDelete(operation.reference, scope: operation.effectiveScope) + } + try outbox.removeFirst(ifMatching: operation) + } catch { + return + } + } + } +} + +final class FakeLibrarySync: LibrarySyncing, @unchecked Sendable { + private let lock = NSLock() + private var savedRecords: [LibraryRecord] = [] + private var deletedRecords: [LibraryRecordReference] = [] + + func enqueue(_ operations: [LibraryOutboxOperation]) throws { + lock.withLock { + for operation in operations { + savedRecords.removeAll { $0.reference == operation.reference } + deletedRecords.removeAll { $0 == operation.reference } + if let record = operation.record { + savedRecords.append(record) + } else { + deletedRecords.append(operation.reference) + } + } + } + } + + func flush() throws {} + + func snapshot() -> (saved: [LibraryRecord], deleted: [LibraryRecordReference]) { + lock.withLock { (savedRecords, deletedRecords) } + } +} diff --git a/Piperly/Services/Sync/SyncStateStore.swift b/Piperly/Services/Sync/SyncStateStore.swift new file mode 100644 index 0000000..a1874d7 --- /dev/null +++ b/Piperly/Services/Sync/SyncStateStore.swift @@ -0,0 +1,219 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import CloudKit +import Foundation + +struct SyncStateSnapshot: Codable, Sendable { + var engineState: CKSyncEngine.State.Serialization? + var pendingSaves: [String: LibraryRecord] + var pendingDeletes: [LibraryRecordReference] + var systemFields: [String: Data] + var deferredRemoteRecords: [String: LibraryRecord] + var deferredRemoteDeletions: [LibraryRecordReference] + var quarantinedSaves: [String: LibraryRecord] + var quarantinedDeletes: [LibraryRecordReference] + var confirmedAccountRecordName: String? + var didSeedExistingLibrary: Bool + var accountTransitionRemoteRecords: [String: LibraryRecord] + var accountTransitionRemoteDeletions: [LibraryRecordReference] + var accountTransitionGeneration: Int + var accountTransitionAccountRecordName: String? + var currentAccountSaves: [String: LibraryRecord] + var currentAccountDeletes: [LibraryRecordReference] + var currentAccountRecordName: String? + var currentAccountTransitionGeneration: Int? + + static let empty = SyncStateSnapshot( + engineState: nil, + pendingSaves: [:], + pendingDeletes: [], + systemFields: [:], + deferredRemoteRecords: [:], + deferredRemoteDeletions: [], + quarantinedSaves: [:], + quarantinedDeletes: [], + confirmedAccountRecordName: nil, + didSeedExistingLibrary: false, + accountTransitionRemoteRecords: [:], + accountTransitionRemoteDeletions: [], + accountTransitionGeneration: 0, + accountTransitionAccountRecordName: nil, + currentAccountSaves: [:], + currentAccountDeletes: [], + currentAccountRecordName: nil, + currentAccountTransitionGeneration: nil + ) + + private enum CodingKeys: String, CodingKey { + case engineState, pendingSaves, pendingDeletes, systemFields + case deferredRemoteRecords, quarantinedSaves, quarantinedDeletes, confirmedAccountRecordName + case didSeedExistingLibrary + case deferredRemoteDeletions, accountTransitionRemoteRecords, accountTransitionRemoteDeletions + case accountTransitionGeneration, accountTransitionAccountRecordName + case currentAccountSaves, currentAccountDeletes + case currentAccountRecordName, currentAccountTransitionGeneration + } + + init( + engineState: CKSyncEngine.State.Serialization?, + pendingSaves: [String: LibraryRecord], + pendingDeletes: [LibraryRecordReference], + systemFields: [String: Data], + deferredRemoteRecords: [String: LibraryRecord], + deferredRemoteDeletions: [LibraryRecordReference], + quarantinedSaves: [String: LibraryRecord], + quarantinedDeletes: [LibraryRecordReference], + confirmedAccountRecordName: String?, + didSeedExistingLibrary: Bool, + accountTransitionRemoteRecords: [String: LibraryRecord], + accountTransitionRemoteDeletions: [LibraryRecordReference], + accountTransitionGeneration: Int, + accountTransitionAccountRecordName: String?, + currentAccountSaves: [String: LibraryRecord], + currentAccountDeletes: [LibraryRecordReference], + currentAccountRecordName: String?, + currentAccountTransitionGeneration: Int? + ) { + self.engineState = engineState + self.pendingSaves = pendingSaves + self.pendingDeletes = pendingDeletes + self.systemFields = systemFields + self.deferredRemoteRecords = deferredRemoteRecords + self.deferredRemoteDeletions = deferredRemoteDeletions + self.quarantinedSaves = quarantinedSaves + self.quarantinedDeletes = quarantinedDeletes + self.confirmedAccountRecordName = confirmedAccountRecordName + self.didSeedExistingLibrary = didSeedExistingLibrary + self.accountTransitionRemoteRecords = accountTransitionRemoteRecords + self.accountTransitionRemoteDeletions = accountTransitionRemoteDeletions + self.accountTransitionGeneration = accountTransitionGeneration + self.accountTransitionAccountRecordName = accountTransitionAccountRecordName + self.currentAccountSaves = currentAccountSaves + self.currentAccountDeletes = currentAccountDeletes + self.currentAccountRecordName = currentAccountRecordName + self.currentAccountTransitionGeneration = currentAccountTransitionGeneration + } + + init(from decoder: Decoder) throws { + let container = try decoder.container(keyedBy: CodingKeys.self) + engineState = try container.decodeIfPresent(CKSyncEngine.State.Serialization.self, forKey: .engineState) + pendingSaves = try container.decodeIfPresent([String: LibraryRecord].self, forKey: .pendingSaves) ?? [:] + pendingDeletes = try container.decodeIfPresent([LibraryRecordReference].self, forKey: .pendingDeletes) ?? [] + systemFields = try container.decodeIfPresent([String: Data].self, forKey: .systemFields) ?? [:] + deferredRemoteRecords = try container.decodeIfPresent( + [String: LibraryRecord].self, + forKey: .deferredRemoteRecords + ) ?? [:] + deferredRemoteDeletions = try container.decodeIfPresent( + [LibraryRecordReference].self, + forKey: .deferredRemoteDeletions + ) ?? [] + quarantinedSaves = try container.decodeIfPresent( + [String: LibraryRecord].self, + forKey: .quarantinedSaves + ) ?? [:] + quarantinedDeletes = try container.decodeIfPresent( + [LibraryRecordReference].self, + forKey: .quarantinedDeletes + ) ?? [] + confirmedAccountRecordName = try container.decodeIfPresent( + String.self, + forKey: .confirmedAccountRecordName + ) + didSeedExistingLibrary = try container.decodeIfPresent(Bool.self, forKey: .didSeedExistingLibrary) + ?? false + accountTransitionRemoteRecords = try container.decodeIfPresent( + [String: LibraryRecord].self, + forKey: .accountTransitionRemoteRecords + ) ?? [:] + accountTransitionRemoteDeletions = try container.decodeIfPresent( + [LibraryRecordReference].self, + forKey: .accountTransitionRemoteDeletions + ) ?? [] + accountTransitionGeneration = try container.decodeIfPresent( + Int.self, + forKey: .accountTransitionGeneration + ) ?? 0 + accountTransitionAccountRecordName = try container.decodeIfPresent( + String.self, + forKey: .accountTransitionAccountRecordName + ) + currentAccountSaves = try container.decodeIfPresent( + [String: LibraryRecord].self, + forKey: .currentAccountSaves + ) ?? [:] + currentAccountDeletes = try container.decodeIfPresent( + [LibraryRecordReference].self, + forKey: .currentAccountDeletes + ) ?? [] + currentAccountRecordName = try container.decodeIfPresent( + String.self, + forKey: .currentAccountRecordName + ) + currentAccountTransitionGeneration = try container.decodeIfPresent( + Int.self, + forKey: .currentAccountTransitionGeneration + ) + } +} + +struct SyncStateStore: Sendable { + let fileURL: URL + + func load() throws -> SyncStateSnapshot { + guard FileManager.default.fileExists(atPath: fileURL.path) else { return .empty } + return try JSONDecoder().decode(SyncStateSnapshot.self, from: Data(contentsOf: fileURL)) + } + + func save(_ snapshot: SyncStateSnapshot) throws { + try FileManager.default.createDirectory( + at: fileURL.deletingLastPathComponent(), + withIntermediateDirectories: true + ) + try JSONEncoder().encode(snapshot).write( + to: fileURL, + options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication] + ) + } + + func reset() throws { + guard FileManager.default.fileExists(atPath: fileURL.path) else { return } + try FileManager.default.removeItem(at: fileURL) + } +} + +struct LibraryOutboxStore: Sendable { + let fileURL: URL + + static let defaultURL = FileManager.default.urls( + for: .applicationSupportDirectory, + in: .userDomainMask + )[0] + .appendingPathComponent("Piperly", isDirectory: true) + .appendingPathComponent("LibrarySyncOutbox.json") + + func load() throws -> [LibraryOutboxOperation] { + do { + return try JSONDecoder().decode([LibraryOutboxOperation].self, from: Data(contentsOf: fileURL)) + } catch { + let fileError = error as NSError + if fileError.domain == NSCocoaErrorDomain, + fileError.code == NSFileReadNoSuchFileError { + return [] + } + throw error + } + } + + func save(_ operations: [LibraryOutboxOperation]) throws { + try FileManager.default.createDirectory( + at: fileURL.deletingLastPathComponent(), + withIntermediateDirectories: true + ) + try JSONEncoder().encode(operations).write( + to: fileURL, + options: [.atomic, .completeFileProtectionUntilFirstUserAuthentication] + ) + } +} diff --git a/Piperly/Services/Sync/SyncStatus.swift b/Piperly/Services/Sync/SyncStatus.swift new file mode 100644 index 0000000..60518fd --- /dev/null +++ b/Piperly/Services/Sync/SyncStatus.swift @@ -0,0 +1,288 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import CloudKit +import Foundation + +enum SyncAccountState: Sendable, Equatable { + case available + case noAccount + case restricted + case temporarilyUnavailable + case couldNotDetermine +} + +enum SyncFailure: Sendable, Equatable { + case retryable(retryAfter: Date?) + case accountUnavailable + case accountRestricted + case quotaExceeded + case permissionDenied + case invalidSchema + case missingLocalData + case unknown(code: Int) +} + +enum LibrarySyncStatus: Sendable, Equatable { + case disabled + case idle + case syncing + case waitingToRetry(Date?) + case accountConfirmationRequired + case blocked(SyncFailure) +} + +enum AccountTransitionPolicy: Sendable, Equatable { + case discardPendingChanges + case keepLocalAndUploadAfterFetch +} + +enum SyncAccountTransition { + static func quarantine(snapshot: inout SyncStateSnapshot) { + snapshot.quarantinedSaves.merge(snapshot.pendingSaves) { _, current in current } + for deletion in snapshot.pendingDeletes { + snapshot.quarantinedSaves[deletion.recordName] = nil + snapshot.quarantinedDeletes.removeAll { $0 == deletion } + snapshot.quarantinedDeletes.append(deletion) + } + snapshot.pendingSaves = [:] + snapshot.pendingDeletes = [] + } + + static func resolve(policy: AccountTransitionPolicy, snapshot: inout SyncStateSnapshot) { + switch policy { + case .discardPendingChanges: + snapshot.quarantinedSaves = [:] + snapshot.quarantinedDeletes = [] + case .keepLocalAndUploadAfterFetch: + snapshot.pendingSaves = snapshot.quarantinedSaves + snapshot.pendingDeletes = snapshot.quarantinedDeletes + snapshot.quarantinedSaves = [:] + snapshot.quarantinedDeletes = [] + } + } + + static func refreshQuarantinedSaves( + from records: [LibraryRecord], + snapshot: inout SyncStateSnapshot + ) { + let recordsByReference = Dictionary(uniqueKeysWithValues: records.map { ($0.reference, $0) }) + for (recordName, record) in snapshot.quarantinedSaves { + if let refreshed = recordsByReference[record.reference] { + snapshot.quarantinedSaves[recordName] = refreshed + } + } + } +} + +enum SyncInitialLibrarySeeder { + static func seedIfNeeded( + records: [LibraryRecord], + policy: AccountTransitionPolicy, + snapshot: inout SyncStateSnapshot + ) { + guard !snapshot.didSeedExistingLibrary else { return } + if policy == .keepLocalAndUploadAfterFetch { + for record in records where !snapshot.pendingDeletes.contains(record.reference) { + snapshot.pendingSaves[record.reference.recordName] = record + } + } + snapshot.didSeedExistingLibrary = true + } +} + +enum SyncCurrentAccountOperations { + static func hasOperations(snapshot: SyncStateSnapshot) -> Bool { + !snapshot.currentAccountSaves.isEmpty || !snapshot.currentAccountDeletes.isEmpty + } + + static func recordSave( + _ record: LibraryRecord, + accountRecordName: String, + transitionGeneration: Int, + snapshot: inout SyncStateSnapshot + ) { + prepareBucket( + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration, + snapshot: &snapshot + ) + snapshot.currentAccountDeletes.removeAll { $0 == record.reference } + snapshot.currentAccountSaves[record.reference.recordName] = record + } + + static func recordDelete( + _ reference: LibraryRecordReference, + accountRecordName: String, + transitionGeneration: Int, + snapshot: inout SyncStateSnapshot + ) { + prepareBucket( + accountRecordName: accountRecordName, + transitionGeneration: transitionGeneration, + snapshot: &snapshot + ) + snapshot.currentAccountSaves[reference.recordName] = nil + snapshot.currentAccountDeletes.removeAll { $0 == reference } + snapshot.currentAccountDeletes.append(reference) + } + + static func commitIfMatching( + accountRecordName: String, + transitionGeneration: Int, + snapshot: inout SyncStateSnapshot + ) -> Bool { + guard hasOperations(snapshot: snapshot) else { + clear(snapshot: &snapshot) + return true + } + guard snapshot.currentAccountRecordName == accountRecordName, + snapshot.currentAccountTransitionGeneration == transitionGeneration else { + reQuarantine(snapshot: &snapshot) + return false + } + for (recordName, record) in snapshot.currentAccountSaves { + snapshot.pendingDeletes.removeAll { $0 == record.reference } + snapshot.pendingSaves[recordName] = record + } + for deletion in snapshot.currentAccountDeletes { + snapshot.pendingSaves[deletion.recordName] = nil + snapshot.pendingDeletes.removeAll { $0 == deletion } + snapshot.pendingDeletes.append(deletion) + } + clear(snapshot: &snapshot) + return true + } + + static func reQuarantine(snapshot: inout SyncStateSnapshot) { + for (recordName, record) in snapshot.currentAccountSaves { + snapshot.quarantinedDeletes.removeAll { $0 == record.reference } + snapshot.quarantinedSaves[recordName] = record + } + for deletion in snapshot.currentAccountDeletes { + snapshot.quarantinedSaves[deletion.recordName] = nil + snapshot.quarantinedDeletes.removeAll { $0 == deletion } + snapshot.quarantinedDeletes.append(deletion) + } + clear(snapshot: &snapshot) + } + + private static func prepareBucket( + accountRecordName: String, + transitionGeneration: Int, + snapshot: inout SyncStateSnapshot + ) { + if hasOperations(snapshot: snapshot) + && (snapshot.currentAccountRecordName != accountRecordName + || snapshot.currentAccountTransitionGeneration != transitionGeneration) { + reQuarantine(snapshot: &snapshot) + } + snapshot.currentAccountRecordName = accountRecordName + snapshot.currentAccountTransitionGeneration = transitionGeneration + } + + private static func clear(snapshot: inout SyncStateSnapshot) { + snapshot.currentAccountSaves = [:] + snapshot.currentAccountDeletes = [] + snapshot.currentAccountRecordName = nil + snapshot.currentAccountTransitionGeneration = nil + } +} + +enum CloudKitErrorClassifier { + static func classify(_ error: CKError, now: Date = .now) -> SyncFailure { + switch error.code { + case .networkUnavailable, .networkFailure, .serviceUnavailable, + .requestRateLimited, .zoneBusy, .accountTemporarilyUnavailable, + .operationCancelled: + let retryAfter = error.retryAfterSeconds.map { now.addingTimeInterval($0) } + return .retryable(retryAfter: retryAfter) + case .notAuthenticated: + return .accountUnavailable + case .managedAccountRestricted: + return .accountRestricted + case .quotaExceeded: + return .quotaExceeded + case .permissionFailure: + return .permissionDenied + case .badContainer, .invalidArguments, .serverRejectedRequest: + return .invalidSchema + case .assetFileNotFound: + return .missingLocalData + default: + return .unknown(code: error.code.rawValue) + } + } +} + +enum CloudKitRetryPolicy { + static func pendingSave( + recordID: CKRecord.ID, + error: CKError + ) -> CKSyncEngine.PendingRecordZoneChange? { + guard case .retryable = CloudKitErrorClassifier.classify(error) else { return nil } + return .saveRecord(recordID) + } +} + +enum FetchedRecordReconciler { + static func isTombstoned( + _ reference: LibraryRecordReference, + pendingDeletes: [LibraryRecordReference], + quarantinedDeletes: [LibraryRecordReference] + ) -> Bool { + pendingDeletes.contains(reference) || quarantinedDeletes.contains(reference) + } + + static func applyRemoteDeletion( + _ reference: LibraryRecordReference, + snapshot: inout SyncStateSnapshot + ) { + snapshot.pendingSaves[reference.recordName] = nil + snapshot.pendingDeletes.removeAll { $0 == reference } + snapshot.deferredRemoteRecords[reference.recordName] = nil + snapshot.systemFields[reference.recordName] = nil + } +} + +enum SyncAccountTransitionValidator { + static func validate(initialRecordName: String, verifiedRecordName: String) throws { + guard initialRecordName == verifiedRecordName else { + throw SyncAccountTransitionError.accountChangedDuringConfirmation + } + } + + static func validateGeneration( + expected: Int, + current: Int, + isTransitionActive: Bool + ) throws { + guard isTransitionActive, expected == current else { + throw SyncAccountTransitionError.accountChangedDuringConfirmation + } + } +} + +enum AccountTransitionRemoteReconciler { + static func changes( + records: [LibraryRecord], + deletions: [LibraryRecordReference], + policy: AccountTransitionPolicy, + initialLocalRecords: [LibraryRecord], + quarantinedSaves: [LibraryRecord], + quarantinedDeletes: [LibraryRecordReference] + ) -> [LibraryRemoteChange] { + var records = records + var deletions = deletions + if policy == .keepLocalAndUploadAfterFetch { + let protectedReferences = Set( + initialLocalRecords.map(\.reference) + quarantinedSaves.map(\.reference) + ) + let localDeletions = Set(quarantinedDeletes) + deletions.removeAll { protectedReferences.contains($0) } + records.removeAll { localDeletions.contains($0.reference) } + } + return deletions.map(LibraryRemoteChange.delete) + + records.map(LibraryRemoteChange.save) + } +} diff --git a/PiperlyTests/CloudKitSyncTests.swift b/PiperlyTests/CloudKitSyncTests.swift new file mode 100644 index 0000000..abf1092 --- /dev/null +++ b/PiperlyTests/CloudKitSyncTests.swift @@ -0,0 +1,969 @@ +import CloudKit +import Foundation +import Testing +@testable import Piperly + +@Suite("CloudKit record codec") +struct CloudKitRecordCodecTests { + private let profileID = UUID(uuidString: "11111111-1111-1111-1111-111111111111")! + private let bookIdentity = String(repeating: "a", count: 64) + private let date = Date(timeIntervalSince1970: 1_700_000_000) + + @Test func deterministicRecordNamesContainNoUserContent() { + let book = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: bookIdentity.uppercased(), + title: "A Child's Book", + author: "Private Author", + originalExtension: "epub", + hasCover: true, + modifiedAt: date + )) + let reading = LibraryRecord.readingState(SyncedReadingState( + profileID: profileID, + bookIdentity: bookIdentity, + progression: 0.5, + locatorJSON: nil, + modifiedAt: date + )) + + #expect(book.reference.recordName == bookIdentity) + #expect(reading.reference.recordName == "reading-\(profileID.uuidString.lowercased())-\(bookIdentity)") + #expect(!book.reference.recordName.contains("Child")) + } + + @Test func allMetadataRecordsRoundTrip() throws { + let records: [LibraryRecord] = [ + .book(SyncedBook( + id: UUID(), + contentIdentity: bookIdentity, + title: "The Book", + author: "An Author", + originalExtension: "epub", + hasCover: true, + modifiedAt: date + )), + .readerProfile(SyncedReaderProfile( + id: profileID, + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: date, + modifiedAt: date + )), + .readerPreferences(SyncedReaderPreferences( + profileID: profileID, + voiceIdentifier: "voice", + speechRate: 0.45, + fontSize: 22, + readerTheme: "piperly", + hasCompletedVoiceSetup: true, + modifiedAt: date + )), + .readingState(SyncedReadingState( + profileID: profileID, + bookIdentity: bookIdentity, + progression: 0.75, + locatorJSON: "{\"href\":\"chapter-2\"}", + modifiedAt: date + )), + .bookmark(SyncedBookmark( + id: UUID(), + profileID: profileID, + bookIdentity: bookIdentity, + locatorJSON: "{}", + title: "Chapter 2", + progression: 0.4, + sticker: "star", + createdAt: date, + modifiedAt: date + )), + .savedWord(SyncedSavedWord( + id: UUID(), + profileID: profileID, + bookIdentity: bookIdentity, + canonicalWord: "wonder", + displayWord: "Wonder", + bookTitle: "The Book", + tapCount: 3, + savedAt: date, + lastTappedAt: date, + modifiedAt: date + )), + ] + + for value in records { + let cloudRecord = try LibraryRecordCodec.encode(value) + #expect(try LibraryRecordCodec.decode(cloudRecord) == value) + #expect(cloudRecord.recordID.zoneID == LibraryRecordCodec.zoneID) + } + } + + @Test func systemFieldsPreserveRecordIdentity() throws { + let value = LibraryRecord.readerProfile(SyncedReaderProfile( + id: profileID, + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: date, + modifiedAt: date + )) + let first = try LibraryRecordCodec.encode(value) + let data = LibraryRecordCodec.systemFieldsData(for: first) + let second = try LibraryRecordCodec.encode(value, systemFields: data) + #expect(second.recordID == first.recordID) + #expect(second.recordType == first.recordType) + } +} + +@Suite("CloudKit conflict resolution") +struct CloudKitConflictTests { + @Test func savedWordCombinesCountersAndDates() { + let id = UUID() + let profileID = UUID() + let early = Date(timeIntervalSince1970: 100) + let late = Date(timeIntervalSince1970: 200) + let local = SyncedSavedWord( + id: id, + profileID: profileID, + bookIdentity: "hash", + canonicalWord: "word", + displayWord: "WORD", + bookTitle: "Old", + tapCount: 8, + savedAt: late, + lastTappedAt: early, + modifiedAt: early + ) + let remote = SyncedSavedWord( + id: id, + profileID: profileID, + bookIdentity: "hash", + canonicalWord: "word", + displayWord: "Word", + bookTitle: "New", + tapCount: 3, + savedAt: early, + lastTappedAt: late, + modifiedAt: late + ) + + guard case .savedWord(let merged) = LibraryConflictResolver.merge( + local: .savedWord(local), + remote: .savedWord(remote) + ) else { + Issue.record("Expected a saved-word merge") + return + } + #expect(merged.tapCount == 8) + #expect(merged.savedAt == early) + #expect(merged.lastTappedAt == late) + #expect(merged.displayWord == "Word") + } + + @Test func readingStateKeepsLocatorAndProgressionTogether() { + let local = SyncedReadingState( + profileID: UUID(), + bookIdentity: "hash", + progression: 0.2, + locatorJSON: "local", + modifiedAt: Date(timeIntervalSince1970: 100) + ) + let remote = SyncedReadingState( + profileID: local.profileID, + bookIdentity: "hash", + progression: 0.8, + locatorJSON: "remote", + modifiedAt: Date(timeIntervalSince1970: 200) + ) + guard case .readingState(let merged) = LibraryConflictResolver.merge( + local: .readingState(local), + remote: .readingState(remote) + ) else { + Issue.record("Expected a reading-state merge") + return + } + #expect(merged.progression == 0.8) + #expect(merged.locatorJSON == "remote") + } +} + +@Suite("CloudKit durable queue") +struct CloudKitStateStoreTests { + @Test func pendingWorkSurvivesReload() throws { + let fileURL = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-sync-\(UUID().uuidString).json") + defer { try? FileManager.default.removeItem(at: fileURL) } + let store = SyncStateStore(fileURL: fileURL) + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + let deletion = LibraryRecordReference( + recordType: "Bookmark", + recordName: "bookmark-\(UUID().uuidString.lowercased())" + ) + var snapshot = SyncStateSnapshot.empty + snapshot.pendingSaves[record.reference.recordName] = record + snapshot.pendingDeletes = [deletion] + snapshot.deferredRemoteRecords[record.reference.recordName] = record + try store.save(snapshot) + + let loaded = try store.load() + #expect(loaded.pendingSaves[record.reference.recordName] == record) + #expect(loaded.pendingDeletes == [deletion]) + #expect(loaded.deferredRemoteRecords[record.reference.recordName] == record) + } +} + +@Suite("CloudKit error classification") +struct CloudKitErrorClassificationTests { + @Test func networkFailuresRemainRetryable() { + let error = CKError(_nsError: NSError( + domain: CKErrorDomain, + code: CKError.Code.networkUnavailable.rawValue + )) + guard case .retryable = CloudKitErrorClassifier.classify(error) else { + Issue.record("Expected a retryable failure") + return + } + } + + @Test func quotaAndPermissionFailuresBlockSync() { + let quota = CKError(_nsError: NSError( + domain: CKErrorDomain, + code: CKError.Code.quotaExceeded.rawValue + )) + let permission = CKError(_nsError: NSError( + domain: CKErrorDomain, + code: CKError.Code.permissionFailure.rawValue + )) + #expect(CloudKitErrorClassifier.classify(quota) == .quotaExceeded) + #expect(CloudKitErrorClassifier.classify(permission) == .permissionDenied) + } +} + +@Suite("BookStore sync boundary") +struct BookStoreSyncBoundaryTests { + @Test @MainActor func applyingRemoteChangesDoesNotRequeueThem() async throws { + let root = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-remote-\(UUID().uuidString)", isDirectory: true) + defer { try? FileManager.default.removeItem(at: root) } + let suiteName = "PiperlyTests.Sync.\(UUID().uuidString)" + let defaults = try #require(UserDefaults(suiteName: suiteName)) + defer { defaults.removePersistentDomain(forName: suiteName) } + let sync = FakeLibrarySync() + let store = BookStore( + documentsURL: root.appendingPathComponent("Books", isDirectory: true), + coversURL: root.appendingPathComponent("Covers", isDirectory: true), + userDefaults: defaults, + librarySync: sync + ) + let record = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: String(repeating: "b", count: 64), + title: "Remote Book", + author: "Remote Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: .now + )) + + _ = store.applyRemoteChanges([.save(record)]) + await Task.yield() + let queued = sync.snapshot() + #expect(queued.saved.isEmpty) + #expect(queued.deleted.isEmpty) + #expect(store.books.count == 1) + } +} + +@Suite("CloudKit sync correctness regressions") +struct CloudKitSyncCorrectnessTests { + @Test func corruptOutboxBlocksWithoutOverwritingQueueFile() throws { + let fileURL = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-corrupt-outbox-\(UUID().uuidString).json") + let corruptData = Data("not valid json".utf8) + try corruptData.write(to: fileURL) + defer { try? FileManager.default.removeItem(at: fileURL) } + let router = LibrarySyncRouter(fileURL: fileURL) + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + + #expect(router.outboxStatus() == .blocked) + #expect(throws: LibraryOutboxError.self) { + try router.enqueueSave(record) + } + #expect(try Data(contentsOf: fileURL) == corruptData) + } + + @Test func localOutboxPersistsTheLastIntentSynchronously() throws { + let fileURL = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-outbox-\(UUID().uuidString).json") + defer { try? FileManager.default.removeItem(at: fileURL) } + let router = LibrarySyncRouter(fileURL: fileURL) + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + + try router.enqueueSave(record) + try router.enqueueDelete(record.reference) + try router.flush() + + let persisted = try LibraryOutboxStore(fileURL: fileURL).load() + #expect(persisted == [.delete(record.reference)]) + let relaunched = LibrarySyncRouter(fileURL: fileURL) + #expect(relaunched.pendingOperations() == persisted) + } + + @Test func fetchedSaveCannotBeatPendingTombstone() { + let reference = LibraryRecordReference( + recordType: "Bookmark", + recordName: "bookmark-\(UUID().uuidString.lowercased())" + ) + #expect(FetchedRecordReconciler.isTombstoned( + reference, + pendingDeletes: [reference], + quarantinedDeletes: [] + )) + #expect(FetchedRecordReconciler.isTombstoned( + reference, + pendingDeletes: [], + quarantinedDeletes: [reference] + )) + } + + @Test @MainActor func sameHashBookMergeKeepsLocalIdentityAndChildren() throws { + let fixture = try storeFixture() + defer { fixture.cleanUp() } + let store = fixture.store + let localID = UUID() + let remoteID = UUID() + let identity = String(repeating: "c", count: 64) + store.books = [Book( + id: localID, + contentIdentity: identity, + title: "Local", + author: "Author", + fileName: "\(identity).epub", + modifiedAt: Date(timeIntervalSince1970: 100) + )] + store.readingStates = [ReadingState(profileID: store.activeProfile.id, bookID: localID)] + _ = store.applyRemoteChanges([.save(.book(SyncedBook( + id: remoteID, + contentIdentity: identity, + title: "Remote", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: Date(timeIntervalSince1970: 200) + )))]) + + #expect(store.books.first?.id == localID) + #expect(store.readingStates.first?.bookID == localID) + #expect(store.books.first?.title == "Remote") + } + + @Test func accountChangeQuarantinesWorkUntilExplicitPolicy() { + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + var snapshot = SyncStateSnapshot.empty + snapshot.pendingSaves[record.reference.recordName] = record + SyncAccountTransition.quarantine(snapshot: &snapshot) + #expect(snapshot.pendingSaves.isEmpty) + #expect(snapshot.quarantinedSaves[record.reference.recordName] == record) + + var discard = snapshot + SyncAccountTransition.resolve(policy: .discardPendingChanges, snapshot: &discard) + #expect(discard.pendingSaves.isEmpty) + #expect(discard.quarantinedSaves.isEmpty) + + SyncAccountTransition.resolve(policy: .keepLocalAndUploadAfterFetch, snapshot: &snapshot) + #expect(snapshot.pendingSaves[record.reference.recordName] == record) + #expect(snapshot.quarantinedSaves.isEmpty) + } + + @Test func confirmationRejectsAnAccountThatChangedDuringFetch() { + #expect(throws: SyncAccountTransitionError.accountChangedDuringConfirmation) { + try SyncAccountTransitionValidator.validate( + initialRecordName: "first-account", + verifiedRecordName: "second-account" + ) + } + #expect(throws: SyncAccountTransitionError.accountChangedDuringConfirmation) { + try SyncAccountTransitionValidator.validateGeneration( + expected: 7, + current: 8, + isTransitionActive: true + ) + } + #expect(throws: SyncAccountTransitionError.accountChangedDuringConfirmation) { + try SyncAccountTransitionValidator.validateGeneration( + expected: 7, + current: 7, + isTransitionActive: false + ) + } + } + + @Test func initialLibrarySeedsExactlyOnceAcrossRelaunch() throws { + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + var snapshot = SyncStateSnapshot.empty + SyncInitialLibrarySeeder.seedIfNeeded( + records: [record], + policy: .keepLocalAndUploadAfterFetch, + snapshot: &snapshot + ) + #expect(snapshot.pendingSaves[record.reference.recordName] == record) + snapshot.pendingSaves = [:] + + let relaunched = try JSONDecoder().decode( + SyncStateSnapshot.self, + from: JSONEncoder().encode(snapshot) + ) + var afterRelaunch = relaunched + SyncInitialLibrarySeeder.seedIfNeeded( + records: [record], + policy: .keepLocalAndUploadAfterFetch, + snapshot: &afterRelaunch + ) + #expect(afterRelaunch.didSeedExistingLibrary) + #expect(afterRelaunch.pendingSaves.isEmpty) + } + + @Test func fetchedDeletionDoesNotMutateQuarantinedChoice() { + let record = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + var snapshot = SyncStateSnapshot.empty + snapshot.quarantinedSaves[record.reference.recordName] = record + let originalSaves = snapshot.quarantinedSaves + let originalDeletes = snapshot.quarantinedDeletes + + FetchedRecordReconciler.applyRemoteDeletion(record.reference, snapshot: &snapshot) + + #expect(snapshot.quarantinedSaves == originalSaves) + #expect(snapshot.quarantinedDeletes == originalDeletes) + } + + @Test func keepLocalSuppressesFetchedDeletionBeforeInitialSeed() { + let book = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: String(repeating: "e", count: 64), + title: "Local Book", + author: "Author", + originalExtension: "epub", + hasCover: true, + modifiedAt: .now + )) + let keepChanges = AccountTransitionRemoteReconciler.changes( + records: [], + deletions: [book.reference], + policy: .keepLocalAndUploadAfterFetch, + initialLocalRecords: [book], + quarantinedSaves: [], + quarantinedDeletes: [] + ) + let discardChanges = AccountTransitionRemoteReconciler.changes( + records: [], + deletions: [book.reference], + policy: .discardPendingChanges, + initialLocalRecords: [book], + quarantinedSaves: [], + quarantinedDeletes: [] + ) + + #expect(keepChanges.isEmpty) + #expect(discardChanges == [.delete(book.reference)]) + } + + @Test func keepLocalSuppressesFetchedDeletionForQuarantinedSave() { + let profile = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + let changes = AccountTransitionRemoteReconciler.changes( + records: [], + deletions: [profile.reference], + policy: .keepLocalAndUploadAfterFetch, + initialLocalRecords: [], + quarantinedSaves: [profile], + quarantinedDeletes: [] + ) + #expect(changes.isEmpty) + } + + @Test @MainActor func keepLocalSeedsPostMergeSnapshotInsteadOfStaleCapture() throws { + let fixture = try storeFixture() + defer { fixture.cleanUp() } + let identity = String(repeating: "f", count: 64) + let localBook = Book( + contentIdentity: identity, + title: "Older Local Title", + author: "Author", + fileName: "\(identity).epub", + modifiedAt: Date(timeIntervalSince1970: 100) + ) + fixture.store.books = [localBook] + let staleCapture = fixture.store.librarySnapshotRecords() + _ = fixture.store.applyRemoteChanges([.save(.book(SyncedBook( + id: UUID(), + contentIdentity: identity, + title: "Newer Remote Title", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: Date(timeIntervalSince1970: 200) + )))]) + let postMergeSnapshot = fixture.store.librarySnapshotRecords() + var snapshot = SyncStateSnapshot.empty + SyncInitialLibrarySeeder.seedIfNeeded( + records: postMergeSnapshot, + policy: .keepLocalAndUploadAfterFetch, + snapshot: &snapshot + ) + + let staleBook = try #require(staleCapture.first { $0.reference.recordName == identity }) + let seededBook = try #require(snapshot.pendingSaves[identity]) + guard case .book(let stale) = staleBook, case .book(let seeded) = seededBook else { + Issue.record("Expected book snapshots") + return + } + #expect(stale.title == "Older Local Title") + #expect(seeded.title == "Newer Remote Title") + } + + @Test func discardOldWorkStillCommitsCurrentAccountReplacement() { + let oldProfile = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Old", + avatarSymbol: "person.fill", + colorName: "blue", + createdAt: .now, + modifiedAt: .now + )) + let replacement = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Reader", + avatarSymbol: "person.crop.circle.fill", + colorName: "accent", + createdAt: .now, + modifiedAt: .now + )) + var snapshot = SyncStateSnapshot.empty + snapshot.quarantinedSaves[oldProfile.reference.recordName] = oldProfile + SyncCurrentAccountOperations.recordSave( + replacement, + accountRecordName: "account-a", + transitionGeneration: 4, + snapshot: &snapshot + ) + + SyncAccountTransition.resolve(policy: .discardPendingChanges, snapshot: &snapshot) + let committed = SyncCurrentAccountOperations.commitIfMatching( + accountRecordName: "account-a", + transitionGeneration: 4, + snapshot: &snapshot + ) + + #expect(committed) + #expect(snapshot.pendingSaves[oldProfile.reference.recordName] == nil) + #expect(snapshot.pendingSaves[replacement.reference.recordName] == replacement) + #expect(snapshot.currentAccountSaves.isEmpty) + } + + @Test func routerMarksStagedReplacementAsCurrentAccountWork() throws { + let fileURL = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-current-account-\(UUID().uuidString).json") + defer { try? FileManager.default.removeItem(at: fileURL) } + let router = LibrarySyncRouter(fileURL: fileURL) + let replacement = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Reader", + avatarSymbol: "person.crop.circle.fill", + colorName: "accent", + createdAt: .now, + modifiedAt: .now + )) + let scope = RemoteApplicationScope.currentAccount( + accountRecordName: "account-a", + transitionGeneration: 3 + ) + var enqueueError: Error? + _ = router.applyingCurrentAccountChanges(scope: scope) { + do { + try router.enqueueSave(replacement) + } catch { + enqueueError = error + } + return .complete + } + + #expect(enqueueError == nil) + #expect(router.pendingOperations().first?.effectiveScope == scope) + } + + @Test func accountSwitchCannotCommitReplacementFromPreviousAccount() throws { + let replacement = LibraryRecord.readerProfile(SyncedReaderProfile( + id: UUID(), + nickname: "Reader", + avatarSymbol: "person.crop.circle.fill", + colorName: "accent", + createdAt: .now, + modifiedAt: .now + )) + var snapshot = SyncStateSnapshot.empty + SyncCurrentAccountOperations.recordSave( + replacement, + accountRecordName: "account-a", + transitionGeneration: 8, + snapshot: &snapshot + ) + let restored = try JSONDecoder().decode( + SyncStateSnapshot.self, + from: JSONEncoder().encode(snapshot) + ) + snapshot = restored + #expect(snapshot.currentAccountRecordName == "account-a") + #expect(snapshot.currentAccountTransitionGeneration == 8) + + let committed = SyncCurrentAccountOperations.commitIfMatching( + accountRecordName: "account-b", + transitionGeneration: 9, + snapshot: &snapshot + ) + + #expect(!committed) + #expect(snapshot.pendingSaves[replacement.reference.recordName] == nil) + #expect(snapshot.quarantinedSaves[replacement.reference.recordName] == replacement) + #expect(snapshot.currentAccountSaves.isEmpty) + #expect(snapshot.currentAccountRecordName == nil) + #expect(snapshot.currentAccountTransitionGeneration == nil) + } + + @Test func keepLocalRefreshesEstablishedLibrarySaveAfterRemoteMerge() { + let identity = String(repeating: "e", count: 64) + let stale = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: identity, + title: "Stale Local Title", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: Date(timeIntervalSince1970: 100) + )) + let merged = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: identity, + title: "Newer Remote Title", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: Date(timeIntervalSince1970: 200) + )) + var snapshot = SyncStateSnapshot.empty + snapshot.didSeedExistingLibrary = true + snapshot.quarantinedSaves[identity] = stale + + SyncAccountTransition.refreshQuarantinedSaves(from: [merged], snapshot: &snapshot) + SyncAccountTransition.resolve(policy: .keepLocalAndUploadAfterFetch, snapshot: &snapshot) + + #expect(snapshot.pendingSaves[identity] == merged) + #expect(snapshot.pendingSaves[identity] != stale) + } + + @Test @MainActor func childRecordsDeferUntilParentsArrive() throws { + let fixture = try storeFixture() + defer { fixture.cleanUp() } + let profileID = UUID() + let bookID = UUID() + let identity = String(repeating: "d", count: 64) + let state = LibraryRecord.readingState(SyncedReadingState( + profileID: profileID, + bookIdentity: identity, + progression: 0.7, + locatorJSON: "{}", + modifiedAt: .now + )) + let first = fixture.store.applyRemoteChanges([.save(state)]) + #expect(first.unresolvedRecords == [state]) + #expect(fixture.store.readingStates.isEmpty) + + let second = fixture.store.applyRemoteChanges([ + .save(.readerProfile(SyncedReaderProfile( + id: profileID, + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + ))), + .save(.book(SyncedBook( + id: bookID, + contentIdentity: identity, + title: "Book", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: .now + ))), + .save(state), + ]) + #expect(second.unresolvedRecords.isEmpty) + #expect(fixture.store.readingStates.contains { + $0.profileID == profileID && $0.bookID == bookID + }) + } + + @Test func retryableSaveProducesAPendingSave() { + let recordID = CKRecord.ID( + recordName: "profile-\(UUID().uuidString.lowercased())", + zoneID: LibraryRecordCodec.zoneID + ) + let error = CKError(_nsError: NSError( + domain: CKErrorDomain, + code: CKError.Code.networkFailure.rawValue + )) + #expect(CloudKitRetryPolicy.pendingSave(recordID: recordID, error: error) == .saveRecord(recordID)) + } + + @Test @MainActor func deletingLastProfileCreatesAndQueuesFreshDefault() throws { + let sync = FakeLibrarySync() + let fixture = try storeFixture(sync: sync) + defer { fixture.cleanUp() } + let deletedID = fixture.store.activeProfile.id + _ = fixture.store.applyRemoteChanges([.delete(LibraryRecordReference( + recordType: "ReaderProfile", + recordName: "profile-\(deletedID.uuidString.lowercased())" + ))]) + + #expect(fixture.store.profiles.count == 1) + #expect(fixture.store.activeProfile.id != deletedID) + let queued = sync.snapshot().saved + #expect(queued.contains { + guard case .readerProfile(let profile) = $0 else { return false } + return profile.id == fixture.store.activeProfile.id + }) + } + + @Test @MainActor func profileAndPreferencesUseIndependentClocks() throws { + let fixture = try storeFixture() + defer { fixture.cleanUp() } + let profile = try ReaderProfile( + id: UUID(), + name: "Ari", + voiceIdentifier: "old", + metadataModifiedAt: Date(timeIntervalSince1970: 200), + preferencesModifiedAt: Date(timeIntervalSince1970: 100) + ) + fixture.store.profiles = [profile] + fixture.store.selectedProfileID = profile.id + + _ = fixture.store.applyRemoteChanges([.save(.readerPreferences(SyncedReaderPreferences( + profileID: profile.id, + voiceIdentifier: "new", + speechRate: 0.5, + fontSize: 24, + readerTheme: "paper", + hasCompletedVoiceSetup: true, + modifiedAt: Date(timeIntervalSince1970: 150) + )))]) + #expect(fixture.store.activeProfile.voiceIdentifier == "new") + #expect(fixture.store.activeProfile.metadataModifiedAt == Date(timeIntervalSince1970: 200)) + #expect(fixture.store.activeProfile.preferencesModifiedAt == Date(timeIntervalSince1970: 150)) + } + + @Test @MainActor func freshRemoteProfileAcceptsItsOlderPreferencesRecord() throws { + let fixture = try storeFixture() + defer { fixture.cleanUp() } + let profileID = UUID() + let result = fixture.store.applyRemoteChanges([ + .save(.readerProfile(SyncedReaderProfile( + id: profileID, + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: Date(timeIntervalSince1970: 100), + modifiedAt: Date(timeIntervalSince1970: 200) + ))), + .save(.readerPreferences(SyncedReaderPreferences( + profileID: profileID, + voiceIdentifier: "remote-voice", + speechRate: 0.5, + fontSize: 24, + readerTheme: "paper", + hasCompletedVoiceSetup: true, + modifiedAt: Date(timeIntervalSince1970: 150) + ))), + ]) + + #expect(result.unresolvedRecords.isEmpty) + let profile = try #require(fixture.store.profiles.first { $0.id == profileID }) + #expect(profile.voiceIdentifier == "remote-voice") + #expect(profile.preferencesModifiedAt == Date(timeIntervalSince1970: 150)) + } + + @Test @MainActor func failedOutboxSaveLeavesLocalProfileUnchanged() throws { + let fixture = try storeFixture(sync: FailingLibrarySync()) + defer { fixture.cleanUp() } + let originalProfiles = fixture.store.profiles + + #expect(throws: BookStoreError.self) { + _ = try fixture.store.addProfile(name: "Ari", avatarSymbol: "star.fill", colorName: "yellow") + } + #expect(fixture.store.profiles == originalProfiles) + #expect(fixture.store.syncOutboxStatus == .blocked) + } + + @Test @MainActor func failedOutboxDeleteLeavesLocalProfileAndChildren() throws { + let fixture = try storeFixture(sync: FailingLibrarySync()) + defer { fixture.cleanUp() } + let first = fixture.store.activeProfile + let second = try ReaderProfile(name: "Ari") + fixture.store.profiles.append(second) + let state = ReadingState(profileID: second.id, bookID: UUID()) + fixture.store.readingStates = [state] + + fixture.store.deleteProfile(second.id) + + #expect(fixture.store.profiles.contains { $0.id == first.id }) + #expect(fixture.store.profiles.contains { $0.id == second.id }) + #expect(fixture.store.readingStates == [state]) + #expect(fixture.store.syncOutboxStatus == .blocked) + } + + @Test @MainActor func failedReplacementQueueKeepsLastDeletedProfileRecoverable() throws { + let fixture = try storeFixture(sync: FailingLibrarySync()) + defer { fixture.cleanUp() } + let original = fixture.store.activeProfile + let deletion = LibraryRecordReference( + recordType: "ReaderProfile", + recordName: "profile-\(original.id.uuidString.lowercased())" + ) + + let result = fixture.store.applyRemoteChanges([.delete(deletion)]) + + #expect(fixture.store.profiles == [original]) + #expect(result.unresolvedDeletions == [deletion]) + #expect(fixture.store.syncOutboxStatus == .blocked) + } + + @Test func UUIDBackedRecordsUseOnePrefixedNamespace() { + let sharedID = UUID() + let profile = LibraryRecord.readerProfile(SyncedReaderProfile( + id: sharedID, + nickname: "Ari", + avatarSymbol: "star.fill", + colorName: "yellow", + createdAt: .now, + modifiedAt: .now + )) + let bookmark = LibraryRecord.bookmark(SyncedBookmark( + id: sharedID, + profileID: sharedID, + bookIdentity: "hash", + locatorJSON: "{}", + title: nil, + progression: 0, + sticker: "star", + createdAt: .now, + modifiedAt: .now + )) + let word = LibraryRecord.savedWord(SyncedSavedWord( + id: sharedID, + profileID: sharedID, + bookIdentity: "hash", + canonicalWord: "word", + displayWord: "Word", + bookTitle: "Book", + tapCount: 1, + savedAt: .now, + lastTappedAt: .now, + modifiedAt: .now + )) + let names = Set([profile.reference.recordName, bookmark.reference.recordName, word.reference.recordName]) + #expect(names.count == 3) + #expect(profile.reference.recordName.hasPrefix("profile-")) + #expect(bookmark.reference.recordName.hasPrefix("bookmark-")) + #expect(word.reference.recordName.hasPrefix("word-")) + } + + @MainActor + private func storeFixture(sync: any LibrarySyncing = DisabledLibrarySync()) throws -> StoreFixture { + let root = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-sync-fixture-\(UUID().uuidString)", isDirectory: true) + let suiteName = "PiperlyTests.SyncFixture.\(UUID().uuidString)" + let defaults = try #require(UserDefaults(suiteName: suiteName)) + return StoreFixture( + store: BookStore( + documentsURL: root.appendingPathComponent("Books", isDirectory: true), + coversURL: root.appendingPathComponent("Covers", isDirectory: true), + userDefaults: defaults, + librarySync: sync + ), + root: root, + defaults: defaults, + suiteName: suiteName + ) + } +} + +@MainActor +private struct StoreFixture { + let store: BookStore + let root: URL + let defaults: UserDefaults + let suiteName: String + + func cleanUp() { + try? FileManager.default.removeItem(at: root) + defaults.removePersistentDomain(forName: suiteName) + } +} + +private struct FailingLibrarySync: LibrarySyncing { + func enqueue(_ operations: [LibraryOutboxOperation]) throws { + throw LibraryOutboxError.unavailable + } + + func flush() throws { + throw LibraryOutboxError.unavailable + } +} diff --git a/docs/adr/0002-cloudkit-sync-implementation.md b/docs/adr/0002-cloudkit-sync-implementation.md index 3e0e593..83de516 100644 --- a/docs/adr/0002-cloudkit-sync-implementation.md +++ b/docs/adr/0002-cloudkit-sync-implementation.md @@ -43,8 +43,16 @@ currently selected does not. - The app needs the iCloud/CloudKit and remote-notification capabilities. - The engine state and pending changes are encoded in the local application support directory, separately from user-visible model data. -- Account changes invalidate engine state, stop sends, and require a fresh - fetch after the parent confirms the currently signed-in account. +- Account changes invalidate engine state and immediately quarantine pending + work so it cannot be sent to a different account. After the parent confirms + the currently signed-in account, Piperly starts a fetch-only engine and + reconciles remote data before allowing any send. The parent must explicitly + choose whether to discard the previous account's pending work or keep the + local work and upload it after that fresh fetch. Until a choice is made, sync + remains paused. Fetched changes are staged durably during this window rather + than applied to local models or files. Keeping local work suppresses fetched + tombstones for those captured or quarantined records; discarding local work + applies the staged remote state before sync resumes. The container identifier must be created for team `7CNK4YPCQX`, attached to the app identifier, tested in the development environment, and promoted to @@ -58,11 +66,11 @@ or other user content. | Record type | Record name | Important fields | | --- | --- | --- | | `Book` | lowercase EPUB SHA-256 | local UUID, title, author, original extension, cover availability, modified date, EPUB asset, optional cover asset | -| `ReaderProfile` | profile UUID | nickname, avatar symbol, color, created date, modified date | +| `ReaderProfile` | `profile-` | nickname, avatar symbol, color, created date, modified date | | `ReaderPreferences` | `preferences-` | profile UUID, voice identifier, speech rate, font size, reader theme, voice-setup completion, modified date | | `ReadingState` | `reading--` | profile UUID, book hash, progression, locator JSON, modified date | -| `Bookmark` | bookmark UUID | profile UUID, book hash, locator JSON, title, progression, sticker, created date, modified date | -| `SavedWord` | saved-word UUID | profile UUID, book hash, canonical word, display word, book title snapshot, tap count, saved date, last-tapped date, modified date | +| `Bookmark` | `bookmark-` | profile UUID, book hash, locator JSON, title, progression, sticker, created date, modified date | +| `SavedWord` | `word-` | profile UUID, book hash, canonical word, display word, book title snapshot, tap count, saved date, last-tapped date, modified date | Book-linked cloud records use the EPUB hash, not the local Book UUID. The Book record may carry the local UUID so a downloaded replica can preserve it, but @@ -70,6 +78,8 @@ the hash is the cross-device join key and deduplication key. Record fields are additive after production deployment. Renaming or deleting a record type or field requires a new field and a compatibility period. +Record names share one namespace within the custom zone, so every UUID-backed +type has a type prefix even when UUID collisions are unlikely. ### Local sync boundary @@ -92,15 +102,22 @@ Remote application must not enqueue the same records as new local changes. ### Send and fetch lifecycle -1. A local mutation is written to disk. +1. A local save or deletion is written to a durable, serialized outbox before + the local mutation returns to its caller. 2. Its deterministic record ID is added to the pending-save queue, or to the - pending-delete queue for deletion. + pending-delete queue for deletion. The outbox entry is removed only after + the sync layer has durably accepted it. + If the outbox cannot be read or written, sync enters a blocked state and + the local mutation does not commit; unreadable queue data is never replaced + with an empty queue. 3. The sync engine is told that pending work exists. 4. When the engine requests changes, the sync layer supplies current records and staged assets for those IDs. 5. Successful sends remove pending entries. Retryable failures remain queued with backoff. Permanent validation failures become a visible blocked state. 6. Fetched changes and deletions are decoded, validated, and applied locally. + Child records whose parents have not arrived are retained durably and + retried after later records and fetch batches. 7. Engine state is persisted after every state update. Partial failures are handled per record. `networkUnavailable`, `networkFailure`, @@ -203,8 +220,9 @@ Each PR is based on the branch immediately before it. pending queues, record codecs, account/error states, fakes, and tests. 5. `feat(icloud): sync book assets` — EPUB/cover asset lifecycle, verification, availability, progress, retry, eviction, deletion, conflicts, and tests. -6. `feat(settings): add iCloud controls` — parent controls and status, recovery - UI, privacy documentation, schema promotion, and two-device checklist. +6. `feat(settings): add iCloud controls` — parent controls and status, the + account-transition choice, recovery UI, privacy documentation, schema + promotion, and two-device checklist. ## Consequences diff --git a/project.yml b/project.yml index d9c314d..b44e20e 100644 --- a/project.yml +++ b/project.yml @@ -93,6 +93,16 @@ targets: INFOPLIST_KEY_CFBundleDisplayName: Piperly INFOPLIST_KEY_LSApplicationCategoryType: public.app-category.education SWIFT_STRICT_CONCURRENCY: complete + CODE_SIGN_ENTITLEMENTS: Piperly/Piperly.entitlements + entitlements: + path: Piperly/Piperly.entitlements + properties: + aps-environment: development + com.apple.developer.icloud-container-identifiers: + - iCloud.com.piperly.app + com.apple.developer.icloud-services: + - CloudKit + com.apple.developer.ubiquity-kvstore-identifier: "$(TeamIdentifierPrefix)com.piperly.app" preBuildScripts: - name: SwiftLint basedOnDependencyAnalysis: false From 84f0733c7ca9c0830f8e0f3a489af16863994433 Mon Sep 17 00:00:00 2001 From: Sarah Wolff Date: Thu, 9 Jul 2026 18:52:40 -0400 Subject: [PATCH 2/2] fix(icloud): harden sync conflict, retention, and delete correctness Address the remaining #19 sync-correctness findings from the Opus review. - Reading progress no longer regresses on an untrusted device clock: a same-locator progression decrease is treated as clock skew and the higher progression is kept (LibraryConflictResolver + applyRemoteSave route through one resolver). A genuine locator change may still lower it. - Bound the deferred/quarantine/account-transition snapshot buckets and expire delete tombstones via SyncSnapshotMaintenance, pruned on every persist. - Add bounded persistent tombstones so an older cross-device save cannot resurrect a recently deleted record after the local delete is sent/cleared. - Make remote profile-delete replacement idempotent (keyed on "no profiles exist") and stop treating a failed replacement enqueue as an unresolved deletion, preventing duplicate default profiles on retry. - Update ADR 0002 reading-state rule to match the non-regression policy. Co-Authored-By: Claude Opus 4.8 --- Piperly.xcodeproj/project.pbxproj | 4 + Piperly/Services/BookStore.swift | 33 ++-- .../Services/Sync/CloudKitLibrarySync.swift | 13 ++ .../Sync/LibraryConflictResolver.swift | 16 +- Piperly/Services/Sync/SyncStateStore.swift | 10 +- Piperly/Services/Sync/SyncStatus.swift | 74 ++++++++ PiperlyTests/CloudKitSyncTests.swift | 15 +- PiperlyTests/SyncCorrectnessFixTests.swift | 164 ++++++++++++++++++ docs/adr/0002-cloudkit-sync-implementation.md | 8 +- 9 files changed, 318 insertions(+), 19 deletions(-) create mode 100644 PiperlyTests/SyncCorrectnessFixTests.swift diff --git a/Piperly.xcodeproj/project.pbxproj b/Piperly.xcodeproj/project.pbxproj index 663484c..5afc136 100644 --- a/Piperly.xcodeproj/project.pbxproj +++ b/Piperly.xcodeproj/project.pbxproj @@ -43,6 +43,7 @@ AA8EF4C5E8B7096587E9AC6C /* CloudKitLibrarySync.swift in Sources */ = {isa = PBXBuildFile; fileRef = 90EA411DA826F78E32B4DA71 /* CloudKitLibrarySync.swift */; }; AE1CBD6D4C45DD851FA3DDC9 /* PiperlyApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0575D688D631F115AF497590 /* PiperlyApp.swift */; }; AEB761A1B95187D81344E32E /* LibraryConflictResolver.swift in Sources */ = {isa = PBXBuildFile; fileRef = 144FD302072287A2F625E295 /* LibraryConflictResolver.swift */; }; + B1228B0DE8DF29035196E3F2 /* SyncCorrectnessFixTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1D83651E39845265FB35587A /* SyncCorrectnessFixTests.swift */; }; B24843B385E539F6569F539E /* CloudKitSyncTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = B342D7030508E0F3805E6C75 /* CloudKitSyncTests.swift */; }; B523FF1F444626551DA6B19A /* LibrarySyncing.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9C922ABB693CC6E51B89A685 /* LibrarySyncing.swift */; }; C16B65EFFFBD4432864334EA /* ReaderTheme.swift in Sources */ = {isa = PBXBuildFile; fileRef = 0B48C597C42056AFD320ACB1 /* ReaderTheme.swift */; }; @@ -85,6 +86,7 @@ 15436967F2E7E08C3F4C37D4 /* TableOfContentsSheet.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = TableOfContentsSheet.swift; sourceTree = ""; }; 180FD98DD38FFD512B905060 /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = ""; }; 1D2F068169DAE06D75030A39 /* LibraryRecordCodec.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LibraryRecordCodec.swift; sourceTree = ""; }; + 1D83651E39845265FB35587A /* SyncCorrectnessFixTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SyncCorrectnessFixTests.swift; sourceTree = ""; }; 1E04B476A4331F7545247076 /* ReaderNavigator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ReaderNavigator.swift; sourceTree = ""; }; 2051654FEEB7BC3200F4830D /* SettingsView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SettingsView.swift; sourceTree = ""; }; 219B546B88E956F5EC6324D7 /* reader-theme.css */ = {isa = PBXFileReference; lastKnownFileType = text.css; path = "reader-theme.css"; sourceTree = ""; }; @@ -302,6 +304,7 @@ children = ( B342D7030508E0F3805E6C75 /* CloudKitSyncTests.swift */, CEE3796984A778CA18D6B83F /* PiperlyTests.swift */, + 1D83651E39845265FB35587A /* SyncCorrectnessFixTests.swift */, ); path = PiperlyTests; sourceTree = ""; @@ -495,6 +498,7 @@ files = ( B24843B385E539F6569F539E /* CloudKitSyncTests.swift in Sources */, 3AC16D4D89F0CBC50AC41C91 /* PiperlyTests.swift in Sources */, + B1228B0DE8DF29035196E3F2 /* SyncCorrectnessFixTests.swift in Sources */, ); runOnlyForDeploymentPostprocessing = 0; }; diff --git a/Piperly/Services/BookStore.swift b/Piperly/Services/BookStore.swift index 71fe4d6..69e1cb0 100644 --- a/Piperly/Services/BookStore.swift +++ b/Piperly/Services/BookStore.swift @@ -1134,10 +1134,18 @@ class BookStore: ObservableObject { guard profiles.contains(where: { $0.id == remote.profileID }), let bookID = books.first(where: { $0.contentIdentity == remote.bookIdentity })?.id else { return false } if let index = readingStates.firstIndex(where: { $0.profileID == remote.profileID && $0.bookID == bookID }) { - guard remote.modifiedAt >= readingStates[index].updatedAt else { return true } - readingStates[index].lastReadProgression = remote.progression - readingStates[index].lastReadLocatorJSON = remote.locatorJSON - readingStates[index].updatedAt = remote.modifiedAt + let current = readingStates[index] + let local = SyncedReadingState( + profileID: remote.profileID, + bookIdentity: remote.bookIdentity, + progression: current.lastReadProgression, + locatorJSON: current.lastReadLocatorJSON, + modifiedAt: current.updatedAt + ) + let merged = LibraryConflictResolver.merge(local: local, remote: remote) + readingStates[index].lastReadProgression = merged.progression + readingStates[index].lastReadLocatorJSON = merged.locatorJSON + readingStates[index].updatedAt = merged.modifiedAt } else { readingStates.append(ReadingState( profileID: remote.profileID, @@ -1239,16 +1247,21 @@ class BookStore: ObservableObject { return true case "ReaderProfile": guard let id = uuid(from: reference.recordName, prefix: "profile-") else { return true } - if profiles.count == 1, profiles[0].id == id { - let replacement = ReaderProfile() - guard persistSyncRecords(syncRecords(for: replacement)) else { return false } - profiles.append(replacement) - selectedProfileID = replacement.id - } profiles.removeAll { $0.id == id } readingStates.removeAll { $0.profileID == id } bookmarks.removeAll { $0.profileID == id } savedWords.removeAll { $0.profileID == id } + // Deleting the last profile leaves an empty library; recreate a default. + // Keyed on "no profiles exist," not a stale count, so a retry after a + // failed replacement-enqueue is idempotent and never spawns duplicates. + // The deletion itself is resolved regardless: a failed replacement + // enqueue must not re-run the delete, or each retry churns another profile. + if profiles.isEmpty { + let replacement = ReaderProfile() + _ = persistSyncRecords(syncRecords(for: replacement)) + profiles.append(replacement) + selectedProfileID = replacement.id + } return true case "ReadingState": readingStates.removeAll { readingStateReference(for: $0) == reference } diff --git a/Piperly/Services/Sync/CloudKitLibrarySync.swift b/Piperly/Services/Sync/CloudKitLibrarySync.swift index e793adf..57e9c5e 100644 --- a/Piperly/Services/Sync/CloudKitLibrarySync.swift +++ b/Piperly/Services/Sync/CloudKitLibrarySync.swift @@ -338,6 +338,7 @@ actor CloudKitLibrarySync: LibrarySyncSink { } private func persistSnapshot() { + SyncSnapshotMaintenance.prune(now: .now, snapshot: &snapshot) do { try stateStore.save(snapshot) } catch { @@ -346,6 +347,7 @@ actor CloudKitLibrarySync: LibrarySyncSink { } private func persistSnapshotOrThrow() throws { + SyncSnapshotMaintenance.prune(now: .now, snapshot: &snapshot) do { try stateStore.save(snapshot) } catch { @@ -427,6 +429,15 @@ extension CloudKitLibrarySync: CKSyncEngineDelegate { engine?.state.add(pendingRecordZoneChanges: [.deleteRecord(record.recordID)]) continue } + if SyncSnapshotMaintenance.isBlockedByTombstone( + reference.recordName, + incomingModifiedAt: modification.record.modificationDate ?? .distantPast, + now: .now, + snapshot: snapshot + ) { + records[reference.recordName] = nil + continue + } let value: LibraryRecord if let pending = snapshot.pendingSaves[record.recordID.recordName] { value = LibraryConflictResolver.merge(local: pending, remote: decoded) @@ -443,6 +454,7 @@ extension CloudKitLibrarySync: CKSyncEngineDelegate { recordName: deletion.recordID.recordName ) FetchedRecordReconciler.applyRemoteDeletion(reference, snapshot: &snapshot) + SyncSnapshotMaintenance.recordTombstone(reference.recordName, at: .now, snapshot: &snapshot) records[reference.recordName] = nil deletionReferences.removeAll { $0 == reference } deletionReferences.append(reference) @@ -500,6 +512,7 @@ extension CloudKitLibrarySync: CKSyncEngineDelegate { } for recordID in event.deletedRecordIDs { snapshot.pendingDeletes.removeAll { $0.recordName == recordID.recordName } + SyncSnapshotMaintenance.recordTombstone(recordID.recordName, at: .now, snapshot: &snapshot) snapshot.systemFields[recordID.recordName] = nil if let pending = snapshot.pendingSaves[recordID.recordName] { syncEngine.state.add(pendingRecordZoneChanges: [ diff --git a/Piperly/Services/Sync/LibraryConflictResolver.swift b/Piperly/Services/Sync/LibraryConflictResolver.swift index b73d930..6e48420 100644 --- a/Piperly/Services/Sync/LibraryConflictResolver.swift +++ b/Piperly/Services/Sync/LibraryConflictResolver.swift @@ -13,7 +13,7 @@ enum LibraryConflictResolver { case (.readerPreferences(let local), .readerPreferences(let remote)): return .readerPreferences(local.modifiedAt >= remote.modifiedAt ? local : remote) case (.readingState(let local), .readingState(let remote)): - return .readingState(local.modifiedAt >= remote.modifiedAt ? local : remote) + return .readingState(merge(local: local, remote: remote)) case (.bookmark(let local), .bookmark(let remote)): return .bookmark(local.modifiedAt >= remote.modifiedAt ? local : remote) case (.savedWord(let local), .savedWord(let remote)): @@ -37,6 +37,20 @@ enum LibraryConflictResolver { ) } + // Reading progress must not regress on a device-clock lie. `modifiedAt` is a + // wall clock on the writing device; a skewed-future clock would otherwise let a + // stale, lower progression win forever. Only accept a lower progression when the + // reader genuinely moved to a different position (locator changed) -- a same-locator + // decrease is treated as clock skew and the higher progression is kept. + static func merge(local: SyncedReadingState, remote: SyncedReadingState) -> SyncedReadingState { + let newest = local.modifiedAt >= remote.modifiedAt ? local : remote + let older = local.modifiedAt >= remote.modifiedAt ? remote : local + if newest.progression < older.progression, newest.locatorJSON == older.locatorJSON { + return older + } + return newest + } + private static func merge(local: SyncedSavedWord, remote: SyncedSavedWord) -> SyncedSavedWord { let newest = local.modifiedAt >= remote.modifiedAt ? local : remote return SyncedSavedWord( diff --git a/Piperly/Services/Sync/SyncStateStore.swift b/Piperly/Services/Sync/SyncStateStore.swift index a1874d7..1da637a 100644 --- a/Piperly/Services/Sync/SyncStateStore.swift +++ b/Piperly/Services/Sync/SyncStateStore.swift @@ -23,6 +23,7 @@ struct SyncStateSnapshot: Codable, Sendable { var currentAccountDeletes: [LibraryRecordReference] var currentAccountRecordName: String? var currentAccountTransitionGeneration: Int? + var tombstones: [String: Date] static let empty = SyncStateSnapshot( engineState: nil, @@ -42,7 +43,8 @@ struct SyncStateSnapshot: Codable, Sendable { currentAccountSaves: [:], currentAccountDeletes: [], currentAccountRecordName: nil, - currentAccountTransitionGeneration: nil + currentAccountTransitionGeneration: nil, + tombstones: [:] ) private enum CodingKeys: String, CodingKey { @@ -53,6 +55,7 @@ struct SyncStateSnapshot: Codable, Sendable { case accountTransitionGeneration, accountTransitionAccountRecordName case currentAccountSaves, currentAccountDeletes case currentAccountRecordName, currentAccountTransitionGeneration + case tombstones } init( @@ -73,7 +76,8 @@ struct SyncStateSnapshot: Codable, Sendable { currentAccountSaves: [String: LibraryRecord], currentAccountDeletes: [LibraryRecordReference], currentAccountRecordName: String?, - currentAccountTransitionGeneration: Int? + currentAccountTransitionGeneration: Int?, + tombstones: [String: Date] = [:] ) { self.engineState = engineState self.pendingSaves = pendingSaves @@ -93,6 +97,7 @@ struct SyncStateSnapshot: Codable, Sendable { self.currentAccountDeletes = currentAccountDeletes self.currentAccountRecordName = currentAccountRecordName self.currentAccountTransitionGeneration = currentAccountTransitionGeneration + self.tombstones = tombstones } init(from decoder: Decoder) throws { @@ -155,6 +160,7 @@ struct SyncStateSnapshot: Codable, Sendable { Int.self, forKey: .currentAccountTransitionGeneration ) + tombstones = try container.decodeIfPresent([String: Date].self, forKey: .tombstones) ?? [:] } } diff --git a/Piperly/Services/Sync/SyncStatus.swift b/Piperly/Services/Sync/SyncStatus.swift index 60518fd..0b10644 100644 --- a/Piperly/Services/Sync/SyncStatus.swift +++ b/Piperly/Services/Sync/SyncStatus.swift @@ -245,6 +245,80 @@ enum FetchedRecordReconciler { } } +// Bounded retention for the snapshot's deferred/quarantine buckets and delete +// tombstones. Without this, a child whose parent never arrives sits in the +// deferred bucket forever and a sent-then-cleared delete has no lasting record, +// so an older cross-device save can resurrect it. +enum SyncSnapshotMaintenance { + static let maxBucketEntries = 512 + static let tombstoneLifetime: TimeInterval = 30 * 24 * 60 * 60 // 30 days + + // Records a delete so a later, older incoming save for the same record name + // can be rejected. Bounded by count (drop-oldest) and age. + static func recordTombstone( + _ recordName: String, + at date: Date, + snapshot: inout SyncStateSnapshot + ) { + snapshot.tombstones[recordName] = date + pruneTombstones(now: date, snapshot: &snapshot) + } + + // True when a save for this record name is older than a live tombstone, i.e. + // it predates a delete we already applied and must not be resurrected. + static func isBlockedByTombstone( + _ recordName: String, + incomingModifiedAt: Date, + now: Date, + snapshot: SyncStateSnapshot + ) -> Bool { + guard let deletedAt = snapshot.tombstones[recordName] else { return false } + guard now.timeIntervalSince(deletedAt) < tombstoneLifetime else { return false } + return incomingModifiedAt <= deletedAt + } + + static func prune(now: Date, snapshot: inout SyncStateSnapshot) { + pruneTombstones(now: now, snapshot: &snapshot) + capOldest(&snapshot.deferredRemoteRecords) + capOldest(&snapshot.quarantinedSaves) + capOldest(&snapshot.accountTransitionRemoteRecords) + } + + private static func pruneTombstones(now: Date, snapshot: inout SyncStateSnapshot) { + snapshot.tombstones = snapshot.tombstones.filter { + now.timeIntervalSince($0.value) < tombstoneLifetime + } + if snapshot.tombstones.count > maxBucketEntries { + let keep = snapshot.tombstones.sorted { $0.value > $1.value }.prefix(maxBucketEntries) + snapshot.tombstones = Dictionary(uniqueKeysWithValues: keep.map { ($0.key, $0.value) }) + } + } + + // Keeps the newest-by-record entries; ties broken by record name for + // determinism (no wall clock available in this pure layer). + private static func capOldest(_ bucket: inout [String: LibraryRecord]) { + guard bucket.count > maxBucketEntries else { return } + let keep = bucket.sorted { + let lhs = $0.value.modifiedAt, rhs = $1.value.modifiedAt + return lhs == rhs ? $0.key > $1.key : lhs > rhs + }.prefix(maxBucketEntries) + bucket = Dictionary(uniqueKeysWithValues: keep.map { ($0.key, $0.value) }) + } +} + +private extension LibraryRecord { + var modifiedAt: Date { + switch self { + case .book(let value): value.modifiedAt + case .readerProfile(let value): value.modifiedAt + case .readerPreferences(let value): value.modifiedAt + case .readingState(let value): value.modifiedAt + case .bookmark(let value): value.modifiedAt + case .savedWord(let value): value.modifiedAt + } + } +} + enum SyncAccountTransitionValidator { static func validate(initialRecordName: String, verifiedRecordName: String) throws { guard initialRecordName == verifiedRecordName else { diff --git a/PiperlyTests/CloudKitSyncTests.swift b/PiperlyTests/CloudKitSyncTests.swift index abf1092..1c7cbcb 100644 --- a/PiperlyTests/CloudKitSyncTests.swift +++ b/PiperlyTests/CloudKitSyncTests.swift @@ -869,7 +869,7 @@ struct CloudKitSyncCorrectnessTests { #expect(fixture.store.syncOutboxStatus == .blocked) } - @Test @MainActor func failedReplacementQueueKeepsLastDeletedProfileRecoverable() throws { + @Test @MainActor func failedReplacementQueueStillResolvesDeletionIdempotently() throws { let fixture = try storeFixture(sync: FailingLibrarySync()) defer { fixture.cleanUp() } let original = fixture.store.activeProfile @@ -878,11 +878,18 @@ struct CloudKitSyncCorrectnessTests { recordName: "profile-\(original.id.uuidString.lowercased())" ) + // A failed replacement enqueue must not leave the deletion unresolved: + // retrying the deletion would spawn a fresh default profile every time. let result = fixture.store.applyRemoteChanges([.delete(deletion)]) + #expect(result.unresolvedDeletions.isEmpty) + #expect(fixture.store.profiles.count == 1) + #expect(!fixture.store.profiles.contains { $0.id == original.id }) - #expect(fixture.store.profiles == [original]) - #expect(result.unresolvedDeletions == [deletion]) - #expect(fixture.store.syncOutboxStatus == .blocked) + // Re-applying the same delete is idempotent: still exactly one profile. + let replacementID = fixture.store.profiles[0].id + _ = fixture.store.applyRemoteChanges([.delete(deletion)]) + #expect(fixture.store.profiles == [fixture.store.profiles[0]]) + #expect(fixture.store.profiles[0].id == replacementID) } @Test func UUIDBackedRecordsUseOnePrefixedNamespace() { diff --git a/PiperlyTests/SyncCorrectnessFixTests.swift b/PiperlyTests/SyncCorrectnessFixTests.swift new file mode 100644 index 0000000..0184162 --- /dev/null +++ b/PiperlyTests/SyncCorrectnessFixTests.swift @@ -0,0 +1,164 @@ +// Piperly - iPad ebook reader for kids +// Copyright (C) 2026 Interactive Buffoonery + +import Foundation +import Testing +@testable import Piperly + +@Suite("CloudKit sync correctness fixes") +struct SyncCorrectnessFixTests { + @Test func skewedFutureTimestampCannotRegressReadingProgress() { + let profileID = UUID() + let identity = String(repeating: "a", count: 64) + // Local: newer real progress at an earlier honest clock time. + let local = SyncedReadingState( + profileID: profileID, + bookIdentity: identity, + progression: 0.8, + locatorJSON: "{\"pos\":80}", + modifiedAt: Date(timeIntervalSince1970: 1000) + ) + // Remote from a device whose clock runs a day fast, but less progress. + let skewedRemote = SyncedReadingState( + profileID: profileID, + bookIdentity: identity, + progression: 0.2, + locatorJSON: "{\"pos\":80}", + modifiedAt: Date(timeIntervalSince1970: 1000 + 86_400) + ) + + let merged = LibraryConflictResolver.merge(local: local, remote: skewedRemote) + #expect(merged.progression == 0.8) + + // A genuine move to a different locator may still lower progression. + var movedRemote = skewedRemote + movedRemote.locatorJSON = "{\"pos\":15}" + let movedMerge = LibraryConflictResolver.merge(local: local, remote: movedRemote) + #expect(movedMerge.progression == 0.2) + } + + @Test @MainActor func remoteReadingStateDoesNotRegressLocalProgress() throws { + let fixture = try Self.storeFixture() + defer { fixture.cleanUp() } + let store = fixture.store + let identity = String(repeating: "d", count: 64) + let bookID = UUID() + store.books = [Book( + id: bookID, + contentIdentity: identity, + title: "Book", + author: "Author", + fileName: "\(identity).epub", + modifiedAt: Date(timeIntervalSince1970: 100) + )] + store.readingStates = [ReadingState( + profileID: store.activeProfile.id, + bookID: bookID, + lastReadProgression: 0.9, + lastReadLocatorJSON: "{\"pos\":90}", + updatedAt: Date(timeIntervalSince1970: 1000) + )] + + _ = store.applyRemoteChanges([.save(.readingState(SyncedReadingState( + profileID: store.activeProfile.id, + bookIdentity: identity, + progression: 0.1, + locatorJSON: "{\"pos\":90}", + modifiedAt: Date(timeIntervalSince1970: 1000 + 86_400) + )))]) + + #expect(store.readingStates.first?.lastReadProgression == 0.9) + } + + @Test func deferredRecordsAreCappedAndTombstonesExpire() { + var snapshot = SyncStateSnapshot.empty + let cap = SyncSnapshotMaintenance.maxBucketEntries + // Over-fill the deferred bucket; newest-by-modifiedAt survive. + for index in 0..<(cap + 50) { + let record = LibraryRecord.book(SyncedBook( + id: UUID(), + contentIdentity: String(format: "%064x", index), + title: "Book \(index)", + author: "Author", + originalExtension: "epub", + hasCover: false, + modifiedAt: Date(timeIntervalSince1970: Double(index)) + )) + snapshot.deferredRemoteRecords[record.reference.recordName] = record + } + // Old + fresh tombstones. + let now = Date(timeIntervalSince1970: 10_000_000) + SyncSnapshotMaintenance.recordTombstone( + "stale", + at: now.addingTimeInterval(-SyncSnapshotMaintenance.tombstoneLifetime - 1), + snapshot: &snapshot + ) + SyncSnapshotMaintenance.recordTombstone("fresh", at: now, snapshot: &snapshot) + + SyncSnapshotMaintenance.prune(now: now, snapshot: &snapshot) + + #expect(snapshot.deferredRemoteRecords.count == cap) + #expect(snapshot.tombstones["stale"] == nil) + #expect(snapshot.tombstones["fresh"] != nil) + } + + @Test func tombstoneBlocksOlderSaveButNotNewer() { + var snapshot = SyncStateSnapshot.empty + let now = Date(timeIntervalSince1970: 1_000_000) + SyncSnapshotMaintenance.recordTombstone("book-x", at: now, snapshot: &snapshot) + + // An incoming save that predates the delete must not resurrect the record. + #expect(SyncSnapshotMaintenance.isBlockedByTombstone( + "book-x", + incomingModifiedAt: now.addingTimeInterval(-10), + now: now, + snapshot: snapshot + )) + // A genuinely newer save (a real re-import after the delete) is allowed. + #expect(!SyncSnapshotMaintenance.isBlockedByTombstone( + "book-x", + incomingModifiedAt: now.addingTimeInterval(10), + now: now, + snapshot: snapshot + )) + // After the retention window the tombstone no longer blocks anything. + #expect(!SyncSnapshotMaintenance.isBlockedByTombstone( + "book-x", + incomingModifiedAt: now.addingTimeInterval(-10), + now: now.addingTimeInterval(SyncSnapshotMaintenance.tombstoneLifetime + 1), + snapshot: snapshot + )) + } + + @MainActor + private static func storeFixture() throws -> Fixture { + let root = FileManager.default.temporaryDirectory + .appendingPathComponent("piperly-syncfix-\(UUID().uuidString)", isDirectory: true) + let suiteName = "PiperlyTests.SyncFix.\(UUID().uuidString)" + let defaults = try #require(UserDefaults(suiteName: suiteName)) + return Fixture( + store: BookStore( + documentsURL: root.appendingPathComponent("Books", isDirectory: true), + coversURL: root.appendingPathComponent("Covers", isDirectory: true), + userDefaults: defaults, + librarySync: DisabledLibrarySync() + ), + root: root, + defaults: defaults, + suiteName: suiteName + ) + } + + @MainActor + private struct Fixture { + let store: BookStore + let root: URL + let defaults: UserDefaults + let suiteName: String + + func cleanUp() { + try? FileManager.default.removeItem(at: root) + defaults.removePersistentDomain(forName: suiteName) + } + } +} diff --git a/docs/adr/0002-cloudkit-sync-implementation.md b/docs/adr/0002-cloudkit-sync-implementation.md index 83de516..6c0b1e7 100644 --- a/docs/adr/0002-cloudkit-sync-implementation.md +++ b/docs/adr/0002-cloudkit-sync-implementation.md @@ -133,8 +133,12 @@ schema/permission errors are surfaced distinctly. - **Reader Profile:** newest modified date wins for nickname, avatar, and color. Deletion wins over an older edit. - **Reader Preferences:** field set from the newest modified date wins. -- **Reading State:** highest `modifiedAt` wins. A locator and progression are - written together so they cannot come from different versions. +- **Reading State:** highest `modifiedAt` wins, except that progression never + regresses at the same locator. Because `modifiedAt` is an untrusted device wall + clock, a same-locator decrease is treated as clock skew and the higher + progression is kept; a genuine move to a different locator may lower it. A + locator and progression are written together so they cannot come from different + versions. - **Bookmark:** records are independent. Same UUID uses newest modified date. - **Saved Word:** same UUID uses newest display metadata, maximum tap count, the earliest saved date, and the latest last-tapped date.