Arsitektur Sinkronisasi CloudKit
Mekanisme sinkronisasi CloudKit pada Maktabah menggunakan pendekatan asinkron yang thread-safe berbasis Swift 6 Concurrency (actor, Sendable, dan Synchronization.Mutex). Modul ini mengelola upload, fetch, debounce, dan pending sync secara terpusat untuk seluruh entitas (Anotasi, Riwayat, dan Hasil Pencarian Tersimpan).
Alur Arsitektur (Architecture Pipeline)
Diagram berikut menggambarkan interaksi komponen antara lapisan repositori domain, penyimpanan basis data, dan mesin inti CloudKit:
flowchart TD
REPOS["Domain Repositories (Annotations / History / Bookmarks)"]
REPOS -->|"Save / Delete"| DEBOUNCE["CloudKitUploadDebouncer"]
REPOS -->|"Offline Queue"| PENDING[("SyncPendingStore (SQLite)")]
DEBOUNCE ~~~ COORD
PENDING ~~~ COORD
COORD["PendingSyncCoordinator"]
CORE["CloudKitCoreManager"]
DEBOUNCE -->|"Flush Batch"| CORE
PENDING -->|"Coordinate"| COORD
COORD -->|"Prepare Batch"| CORE
CORE ~~~ ICLOUD
ICLOUD[("iCloud Private Database (AnnotationsZone)")]
CORE -->|"CKModifyRecordsOperation"| ICLOUD
ICLOUD -->|"CKFetchRecordZoneChangesOperation"| CORE
HANDLERS["Sync Handlers (Annotation / History / Result)"]
CORE -->|"Parse CKRecord"| HANDLERS
HANDLERS -->|"Update Local Storage"| REPOS
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class DEBOUNCE,COORD,CORE,HANDLERS store;
class REPOS,PENDING,ICLOUD db;
Penjelasan metode dan prinsip arsitektur:
-
Prinsip Pemisahan Tanggung Jawab (Separation of Concerns):
CloudKitCoreManager: Bertanggung jawab secara eksklusif untuk interaksi dengan CloudKit API, manajemen token, dan eksekusi antrean jaringan, tanpa perlu mengetahui detail entitas domain.PendingSyncCoordinator: Mengoordinasikan antrean data yang belum tersinkronisasi (pending sync) dari berbagai repositori domain.CloudKitUploadDebouncer: Menangani pembatasan laju (rate limiting) dengan mengelompokkan permintaan sinkronisasi yang berdekatan waktunya.SyncPendingStore: Menyediakan lapisan persistensi SQLite lokal untuk menyimpan status sinkronisasi yang tertunda.Sync Handlers: Menerjemahkan data antaraCKRecord(CloudKit) dan model domain aplikasi.
-
Pending Sync & Debounce:
- Debounce: Setiap permintaan unggah akan ditahan sementara oleh
CloudKitUploadDebouncerselama 2 detik (dapat dikonfigurasi). Jika ada permintaan baru sebelum batas waktu berakhir, timer direset. Mekanisme ini menjaga agar aplikasi tidak membebani server Apple secara berlebihan. - Pending Sync: Jika operasi CloudKit gagal saat
flush(), operasi tersebut (uploadataudelete) dimasukkan ke tabel SQLite lokal melaluiSyncPendingStore.
- Debounce: Setiap permintaan unggah akan ditahan sementara oleh
-
Metode Fetch dan Upload:
- Fetch (Unduh): Menggunakan
CKFetchRecordZoneChangesOperationyang memanfaatkan token perubahan (CKServerChangeToken). Proses ini dijalankan dalam antrean operasi dengan konkurensi maksimal 2. - Upload (Unggah): Menggunakan
CKModifyRecordsOperationuntuk menambah, mengubah, atau menghapus data di dalam custom zoneAnnotationsZone.
- Fetch (Unduh): Menggunakan
Komponen Inti (Core Components)
Seluruh implementasi class dan struct dirancang untuk memenuhi batasan memori dan thread-safety pada Swift 6.
CloudKitSyncManager (Class) & Inisialisasi
CloudKitSyncManager adalah class orkestrator tingkat atas yang mengoordinasikan seluruh alur sinkronisasi saat siklus hidup aplikasi dimulai. Titik inisialisasi utamanya berada pada fungsi initializeOnLaunch():
func initializeOnLaunch() {
guard AppConfig.useICloud else { return }
checkUserIdentityChange()
core.setSyncing(false)
// ... inisialisasi zona kustom ...
}
Ketergantungan Pengaturan (AppConfig)
Aplikasi hanya akan memicu koneksi, pengunduhan, maupun pengunggahan CloudKit apabila pengaturan useICloud di dalam AppConfig (Source/Core/Configuration/AppConfig.swift) bernilai true. Jika pengguna menonaktifkan sinkronisasi iCloud, fungsi ini langsung kembali (return).
Jika pengaturan aktif, initializeOnLaunch() akan menjalankan tahapan berikut secara berurutan:
- Memeriksa Identitas Pengguna (User Identity): Fungsi
checkUserIdentityChange()memastikan apakah akun iCloud pengguna di perangkat telah berganti. Jika berubah, sistem otomatis mereset token perubahan agar data tidak tercampur. - Pembuatan Zona Kustom (Custom Zone): Memverifikasi dan membuat
CKRecordZonekhusus di dalam Private Database. - Pemicu Aksi Asinkron: Jika pembuatan/verifikasi zona berhasil, manajer ini memicu 4 aksi secara asinkron:
fetchChanges(): Menarik seluruh pembaruan dari server CloudKit.subscribeToChanges(): Mendaftarkan aplikasi untuk menerima notifikasi (silent push) saat ada data baru di server.performInitialUploadCheck(): Melakukan pemeriksaan unggahan awal untuk data lokal.retryAllPendingOperations(): Mengunggah kembali seluruh data yang berada di antrean luring (SyncPendingStore).
CloudKitCoreManager (Class)
Class utama (singleton) yang berinteraksi langsung dengan API CloudKit. Menyediakan fungsi untuk mengunggah (upload), menghapus (delete), dan menarik pembaruan (fetchChanges).
final class CloudKitCoreManager: Sendable {
private struct ManagerState { // (1)!
var isSyncing: Bool = false
var notifyTask: Task<Void, Never>?
}
static let shared = CloudKitCoreManager()
let container: CKContainer
let privateDatabase: CKDatabase
let zoneId: CKRecordZone.ID
func tryBeginSyncing() -> Bool { // (2)!
state.withLock { state in
guard !state.isSyncing else { return false }
state.isSyncing = true
return true
}
}
}
structini membungkus state yang bersifat mutable, kemudian diamankan menggunakanSynchronization.Mutexuntuk mencegah data race saat diakses secara konkuren.- Inisiasi sinkronisasi dilakukan secara atomik melalui
tryBeginSyncing(). Hal ini mengeliminasi kunci ganda (isSyncingLock) padaCloudKitSyncManager, mencegah kondisi race condition antara peresetan token dan awal penarikan data (fetch).
Mengeksekusi antrean di latar belakang secara native pada AppKit.
Berjalan selaras dengan background task bawaan sistem iOS/UIKit.
PendingSyncCoordinator (Actor)
actor yang bertugas mengoordinasikan antrean operasi sinkronisasi tertunda (offline queue) lintas repositori domain (Anotasi, Hasil Pencarian, dan Riwayat Baca).
flowchart TD
OFFLINE["Operasi Domain Saat Offline / Error"] -->|"addPendingUploads /<br/>addPendingDeletes"| COORD["PendingSyncCoordinator<br/>(Actor)"]
subgraph LocalPersistence ["SQLite Persistent Queue (sync_pending)"]
AR["AnnotationRepository"]
RH["ResultsHandler"]
HM["HistoryDatabaseManager"]
AR ~~~ RH ~~~ HM
end
COORD -->|"SQL INSERT/REPLACE"| AR
COORD -->|"SQL INSERT/REPLACE"| RH
COORD -->|"SQL INSERT/REPLACE"| HM
HM ~~~ NET
NET["NetworkMonitor:<br/>onRestored"] -->|"Trigger Retry"| CSM["CloudKitSyncManager"]
CSM -->|"preparePendingUploads()"| COORD
subgraph BatchCleaning ["Pembersihan Orphan Records & Batching"]
RET["Valid Domain Records"]
CLEAN["Auto-Purge Orphan IDs"]
end
HM ~~~ RET
COORD -->|"Fetch Local Records"| RET
COORD -->|"Deteksi Orphan Records"| CLEAN
RET -->|"PendingUploadBatch"| CSM
CSM -->|"CKModifyRecordsOperation"| CK[("iCloud Private Database")]
CK -->|"On Success Callback"| REM["removePendingSync()"]
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class COORD,CSM store;
class AR,RH,HM,CK,RET db;
class OFFLINE,NET,CLEAN,REM event;
actor PendingSyncCoordinator {
static let shared = PendingSyncCoordinator()
enum SyncTarget: Sendable {
case annotation
case result
case history
}
struct PendingUploadBatch: Sendable {
let annotations: [Annotation]
let folders: [SyncFolder]
let results: [SyncResult]
let history: [ReadingEntry]
var isEmpty: Bool {
annotations.isEmpty && folders.isEmpty && results.isEmpty && history.isEmpty
}
}
struct PendingDeleteBatch: Sendable {
let annotationIds: [String]
let resultIds: [String]
let historyIds: [String]
var isEmpty: Bool {
annotationIds.isEmpty && resultIds.isEmpty && historyIds.isEmpty
}
}
}
1. Persistensi Antrean Lokal (SQLite)
Ketika operasi unggah atau hapus gagal dilakukan saat perangkat luring (offline), ID entitas langsung dicatat ke dalam tabel lokal sync_pending melalui metode:
- addPendingUploads(_:target:)
- addPendingDeletes(_:target:)
Operasi ini didelegasikan langsung ke repositori domain masing-masing (AnnotationRepository.shared, ResultsHandler.shared, HistoryDatabaseManager.shared) sehingga antrean tetap bertahan (durable) meskipun aplikasi dihentikan paksa atau perangkat dimatikan.
2. Pembersihan Orphan Records & Perakitan Batch (preparePendingUploads)
Sebelum melakukan pengunggahan ulang, fungsi preparePendingUploads() menjalankan sanitasi data otomatis:
1. Membaca daftar ID bertanda upload dari tabel sync_pending.
2. Mengambil entitas data aslinya dari tabel domain utama.
3. Deteksi Orphan Records: Apabila terdapat ID di dalam antrean sync_pending yang datanya sudah tidak ditemukan di basis data lokal (misalnya karena telah dihapus oleh pengguna saat luring), koordinator secara otomatis menghapus ID tersebut dari antrean lokal (removePendingSync).
4. Merangkai seluruh entitas yang valid ke dalam PendingUploadBatch untuk dikirimkan secara serentak.
3. Pemulihan Koneksi Otomatis (NetworkMonitor)
CloudKitSyncManager mendaftarkan callback ke NetworkMonitor.shared:
await NetworkMonitor.shared.registerConnectivityCallbacks(
onRestored: { [weak self] in
self?.retryAllPendingOperations()
}
)
runRetryCoalescingLoop dilindungi oleh Mutex (retryState) guna mencegah pemicuan ganda jika koneksi berfluktuasi dengan cepat.
- Batch Upload & Delete Paralel: Eksekusi batch dijalankan serentak menggunakan withTaskGroup.
- Atomic Cleanup & Timestamp Fencing: Penghapusan dari antrean lokal melalui removePendingSync() menyertakan filter parameter operation dan batas waktu maxQueuedAt guna mencegah race condition terhapusnya mutasi lokal baru yang masuk saat proses upload atau resolusi konflik sedang berlangsung.
CloudKitUploadDebouncer (Actor)
actor generik untuk membatasi laju unggahan (rate limiter).
actor CloudKitUploadDebouncer<Item: Sendable> {
private var buffer: [String: Item] = [:]
private var debounceTask: Task<Void, Never>?
private var pendingCompletions: [@Sendable (Result<Void, Error>) -> Void] = []
private let debounceInterval: Duration
}
Logika Debounce
Semua entitas yang masuk akan ditampung di buffer. Metode add akan membatalkan debounceTask sebelumnya dan memulai interval penundaan baru (debounceInterval). Jika tidak ada permintaan baru hingga batas waktu terlewati, data akan diteruskan ke CloudKit.
SyncPendingStore (Struct)
Lapisan penyimpanan tingkat rendah yang mengeksekusi instruksi SQL ke basis data SQLite lokal.
struct SyncPendingStore {
static let tableName = "sync_pending"
static let createTableSQL = """
CREATE TABLE IF NOT EXISTS sync_pending (
ck_record_id TEXT PRIMARY KEY,
operation TEXT NOT NULL CHECK(operation IN ('upload', 'delete')),
queued_at INTEGER NOT NULL
);
"""
// ...
}
ck_record_id: Kunci primer (Primary Key) sebagai rujukan mutlak keCKRecord.operation: Menyatakan jenis perintah tunda (uploadataudelete).queued_at: Pencatat waktu dalam format integer (UNIX timestamp).
Pembersihan antrean menggunakan klausa WHERE ck_record_id IN (...) yang dapat difilter secara selektif dengan operation serta queued_at <= maxQueuedAt agar operasi asinkron konkuren tidak menghapus entri yang baru diantrekan saat proses sinkronisasi berlangsung.
Penyelesaian Konflik Status
Bila status 'upload' ditambahkan, tetapi tabel sync_pending telah memiliki entri 'delete' untuk ID terkait, status 'delete' tetap dipertahankan. Sebaliknya, instruksi 'delete' yang baru akan menimpa catatan 'upload' lama.
Protocol & Handler
Digunakan sebagai antarmuka standar bagi semua domain untuk dikonversi menjadi CKRecord.
protocol CloudKitSyncable {
var ckRecordId: String? { get }
func toCKRecord(zoneID: CKRecordZone.ID) -> CKRecord?
}
protocol CloudKitRecordParser {
associatedtype Model
static var recordType: String { get }
static func parse(from record: CKRecord) -> Model?
}
Berikut rincian masing-masing pengelola (handler):
-
AnnotationSyncHandler
- Tipe Rekaman:
Annotation - Fungsi: Mentranslasikan format
CKRecordmenjadi objekAnnotationyang utuh (termasuk referensi ke buku, lokasi rentang teks, ID konten, warna heksadesimal, indeks, serta daftar label (tags)).
- Tipe Rekaman:
-
HistorySyncHandler
- Tipe Rekaman:
ReadingEntry - Fungsi: Mengekstrak informasi posisi bacaan terakhir dari CloudKit, memperbarui indikator favorit, serta mencatat waktu pembaruan rekaman.
- Tipe Rekaman:
-
ResultSyncHandler
- Tipe Rekaman:
SearchFolderdanSearchResult - Fungsi: Modul ini menopang dua jenis konversi sekaligus melalui fungsi pembantu statis
parseFoldermaupunparseResult, karena setiap pencarian yang disimpan dapat menempati lokasi folder tertentu dalam hierarki.
- Tipe Rekaman: