ax-cloud-storage

Cloud Storage

Quick Patterns

CloudKit vs iCloud Drive Decision

What are you syncing?
├─ Structured data (records, fields) → CloudKit
│   ├─ Using SwiftData? → SwiftData + CloudKit container
│   ├─ Using SQLiteData? → CKSyncEngine (manual sync)
│   └─ Custom data model? → CKSyncEngine or raw CloudKit APIs
│
├─ User documents/files → iCloud Drive
│   ├─ Standard document types? → UIDocument + ubiquitous container
│   ├─ Custom file formats? → NSFileCoordinator
│   └─ Small preferences (<1MB)? → NSUbiquitousKeyValueStore
│
└─ Both? → CloudKit for metadata, iCloud Drive for large files

Offline-First Pattern (Mandatory)

// ALWAYS: Write local first, sync in background
func saveTrack(_ track: Track) async throws {
    // 1. Save locally FIRST (instant, works offline)
    try database.insert(track)

    // 2. Queue for sync (background, can fail)
    syncEngine.queueChange(.save(track))

    // 3. Never block UI on sync
    // Sync happens asynchronously
}

// NEVER: Require network for local operations
// WRONG:
func saveTrack(_ track: Track) async throws {
    try await cloudKit.save(track)  // Fails offline!
}

CloudKit Three Approaches

// Approach 1: SwiftData + CloudKit (simplest)
let config = ModelConfiguration(
    cloudKitDatabase: .private("iCloud.com.myapp")
)
let container = try ModelContainer(for: Track.self, configurations: config)
// Automatic sync - no additional code needed

// Approach 2: CKSyncEngine (WWDC 2023 - recommended for custom sync)
let syncEngine = CKSyncEngine(
    configuration: CKSyncEngine.Configuration(
        database: CKContainer.default().privateCloudDatabase,
        stateSerialization: loadSavedState(),
        delegate: self
    )
)

// Approach 3: Raw CloudKit APIs (full control)
let container = CKContainer.default()
let privateDB = container.privateCloudDatabase

CKSyncEngine Delegate

class SyncDelegate: CKSyncEngineDelegate {
    func handleEvent(_ event: CKSyncEngine.Event, syncEngine: CKSyncEngine) {
        switch event {
        case .stateUpdate(let stateUpdate):
            // Save state for persistence across launches
            saveSyncState(stateUpdate.stateSerialization)

        case .accountChange(let event):
            handleAccountChange(event)

        case .fetchedDatabaseChanges(let changes):
            handleDatabaseChanges(changes)

        case .fetchedRecordZoneChanges(let changes):
            handleZoneChanges(changes)

        case .sentDatabaseChanges(let sentChanges):
            handleSentDatabaseChanges(sentChanges)

        case .sentRecordZoneChanges(let sentChanges):
            handleSentZoneChanges(sentChanges)

        default: break
        }
    }

    func nextRecordZoneChangeBatch(
        _ context: CKSyncEngine.SendChangesContext,
        syncEngine: CKSyncEngine
    ) async -> CKSyncEngine.RecordZoneChangeBatch? {
        let pendingChanges = syncEngine.state.pendingRecordZoneChanges
        return await CKSyncEngine.RecordZoneChangeBatch(
            pendingChanges: pendingChanges
        ) { recordID in
            // Convert local record to CKRecord
            self.recordForID(recordID)
        }
    }
}