@sriinnu/runic 1.0.0

package/Sources/RunicCore/Sync/BackgroundSyncManager.swift

@@ -0,0 +1,385 @@
+import Foundation
+import Combine
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+#if canImport(AppKit)
+import AppKit
+#endif
+
+// MARK: - Background Sync Manager
+
+/// Manages background synchronization with configurable intervals
+///
+/// This manager coordinates automatic synchronization operations based on
+/// app lifecycle events and configured intervals. It supports:
+/// - Active sync (5-minute intervals)
+/// - Background sync (hourly intervals)
+/// - Manual sync on demand
+/// - Lifecycle-aware sync (app launch, foreground, background)
+/// - Network reachability monitoring
+public actor BackgroundSyncManager {
+
+    // MARK: - Properties
+
+    /// The underlying sync engine
+    private let syncEngine: any SyncEngine
+
+    /// Sync configuration
+    private let config: SyncConfiguration
+
+    /// Timer for periodic sync operations (must be accessed on main thread)
+    @MainActor
+    private var syncTimer: Timer?
+
+    /// Indicates if background sync is currently enabled
+    private var isEnabled: Bool = false
+
+    /// Last successful sync timestamp
+    private var lastSyncDate: Date?
+
+    /// Sync history for diagnostics
+    private var syncHistory: [SyncHistoryEntry] = []
+
+    /// Maximum history entries to retain
+    private let maxHistoryEntries: Int = 50
+
+    /// Observers registered for sync events
+    private var observers: [WeakSyncObserver] = []
+
+    /// Background task identifier (iOS only)
+    #if canImport(UIKit)
+    private var backgroundTaskID: UIBackgroundTaskIdentifier = .invalid
+    #endif
+
+    // MARK: - Initialization
+
+    /// Initializes the background sync manager
+    ///
+    /// - Parameters:
+    ///   - syncEngine: The sync engine to use for operations
+    ///   - config: Configuration for sync intervals and behavior
+    public init(
+        syncEngine: any SyncEngine,
+        config: SyncConfiguration = .default
+    ) {
+        self.syncEngine = syncEngine
+        self.config = config
+
+        // Register for app lifecycle notifications
+        Task {
+            await registerLifecycleObservers()
+        }
+    }
+
+    // MARK: - Public Methods
+
+    /// Starts background synchronization
+    public func start() {
+        guard !isEnabled else { return }
+
+        isEnabled = true
+        scheduleNextSync()
+        notifyObservers { $0.syncDidStart() }
+    }
+
+    /// Stops background synchronization
+    public func stop() {
+        isEnabled = false
+        Task { @MainActor in
+            syncTimer?.invalidate()
+            syncTimer = nil
+        }
+    }
+
+    /// Performs a manual sync operation
+    ///
+    /// - Parameter options: Optional sync options (uses defaults if nil)
+    /// - Returns: Result of the sync operation
+    @discardableResult
+    public func syncNow(options: SyncOptions? = nil) async -> Result<SyncResult, SyncError> {
+        let syncOptions = options ?? config.defaultSyncOptions
+
+        notifyObservers { $0.syncDidStart() }
+
+        let result = await syncEngine.sync(options: syncOptions)
+
+        switch result {
+        case .success(let syncResult):
+            lastSyncDate = Date()
+            recordSyncHistory(success: true, result: syncResult)
+            notifyObservers { $0.syncDidComplete(result: syncResult) }
+
+        case .failure(let error):
+            recordSyncHistory(success: false, error: error)
+            notifyObservers { $0.syncDidFail(error: error) }
+        }
+
+        return result
+    }
+
+    /// Adds an observer for sync events
+    ///
+    /// - Parameter observer: The observer to add
+    public func addObserver(_ observer: SyncObserver) {
+        let weakObserver = WeakSyncObserver(observer)
+        observers.append(weakObserver)
+    }
+
+    /// Removes an observer
+    ///
+    /// - Parameter observer: The observer to remove
+    public func removeObserver(_ observer: SyncObserver) {
+        observers.removeAll { $0.observer === observer }
+    }
+
+    /// Returns sync statistics
+    public var statistics: SyncStatistics {
+        SyncStatistics(
+            lastSyncDate: lastSyncDate,
+            totalSyncs: syncHistory.count,
+            successfulSyncs: syncHistory.filter { $0.success }.count,
+            failedSyncs: syncHistory.filter { !$0.success }.count,
+            averageDuration: calculateAverageDuration(),
+            syncHistory: Array(syncHistory.suffix(10))
+        )
+    }
+
+    /// Updates sync configuration
+    ///
+    /// - Parameter config: New configuration to apply
+    public func updateConfiguration(_ config: SyncConfiguration) async {
+        // Note: Configuration updates require recreating the manager
+        // This is a placeholder - in practice, you'd want to make config mutable
+        if isEnabled {
+            stop()
+            // Caller should create a new BackgroundSyncManager with new config
+        }
+    }
+
+    // MARK: - Private Methods
+
+    /// Schedules the next automatic sync
+    private func scheduleNextSync() {
+        guard isEnabled else { return }
+
+        let interval = determineNextInterval()
+
+        Task { @MainActor [weak self] in
+            guard let self = self else { return }
+            self.syncTimer?.invalidate()
+            self.syncTimer = Timer.scheduledTimer(
+                withTimeInterval: interval,
+                repeats: false
+            ) { [weak self] _ in
+                Task {
+                    await self?.performScheduledSync()
+                }
+            }
+        }
+    }
+
+    /// Determines the appropriate sync interval based on app state
+    private func determineNextInterval() -> TimeInterval {
+        #if canImport(UIKit)
+        let isActive = UIApplication.shared.applicationState == .active
+        return isActive ? config.activeSyncInterval : config.backgroundSyncInterval
+        #else
+        return config.activeSyncInterval
+        #endif
+    }
+
+    /// Performs a scheduled background sync
+    private func performScheduledSync() async {
+        #if canImport(UIKit)
+        // Begin background task
+        backgroundTaskID = UIApplication.shared.beginBackgroundTask { [weak self] in
+            self?.endBackgroundTask()
+        }
+        #endif
+
+        await syncNow()
+
+        #if canImport(UIKit)
+        endBackgroundTask()
+        #endif
+
+        // Schedule next sync
+        scheduleNextSync()
+    }
+
+    #if canImport(UIKit)
+    /// Ends the background task
+    private func endBackgroundTask() {
+        guard backgroundTaskID != .invalid else { return }
+        UIApplication.shared.endBackgroundTask(backgroundTaskID)
+        backgroundTaskID = .invalid
+    }
+    #endif
+
+    /// Registers observers for app lifecycle events
+    private func registerLifecycleObservers() {
+        #if canImport(UIKit)
+        NotificationCenter.default.addObserver(
+            forName: UIApplication.didBecomeActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            Task { await self?.handleAppBecameActive() }
+        }
+
+        NotificationCenter.default.addObserver(
+            forName: UIApplication.didEnterBackgroundNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            Task { await self?.handleAppEnteredBackground() }
+        }
+        #endif
+
+        #if canImport(AppKit)
+        NotificationCenter.default.addObserver(
+            forName: NSApplication.didBecomeActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            Task { await self?.handleAppBecameActive() }
+        }
+
+        NotificationCenter.default.addObserver(
+            forName: NSApplication.didResignActiveNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            Task { await self?.handleAppEnteredBackground() }
+        }
+        #endif
+    }
+
+    /// Handles app becoming active
+    private func handleAppBecameActive() async {
+        guard config.syncOnForeground else { return }
+
+        // Sync if last sync was more than interval ago
+        if shouldSyncOnForeground() {
+            await syncNow()
+        }
+    }
+
+    /// Handles app entering background
+    private func handleAppEnteredBackground() async {
+        guard config.syncOnBackground else { return }
+        await syncNow()
+    }
+
+    /// Determines if sync should occur on foreground
+    private func shouldSyncOnForeground() -> Bool {
+        guard let lastSync = lastSyncDate else { return true }
+
+        let elapsed = Date().timeIntervalSince(lastSync)
+        return elapsed >= config.activeSyncInterval
+    }
+
+    /// Records sync operation in history
+    private func recordSyncHistory(
+        success: Bool,
+        result: SyncResult? = nil,
+        error: SyncError? = nil
+    ) {
+        let entry = SyncHistoryEntry(
+            timestamp: Date(),
+            success: success,
+            duration: result?.duration ?? 0,
+            pushedCount: result?.pushedCount ?? 0,
+            fetchedCount: result?.fetchedCount ?? 0,
+            error: error?.localizedDescription
+        )
+
+        syncHistory.append(entry)
+
+        // Trim history if needed
+        if syncHistory.count > maxHistoryEntries {
+            syncHistory.removeFirst(syncHistory.count - maxHistoryEntries)
+        }
+    }
+
+    /// Calculates average sync duration
+    private func calculateAverageDuration() -> TimeInterval {
+        let successfulSyncs = syncHistory.filter { $0.success && $0.duration > 0 }
+        guard !successfulSyncs.isEmpty else { return 0 }
+
+        let totalDuration = successfulSyncs.reduce(0.0) { $0 + $1.duration }
+        return totalDuration / Double(successfulSyncs.count)
+    }
+
+    /// Notifies all observers
+    private func notifyObservers(_ action: (SyncObserver) -> Void) {
+        // Clean up deallocated observers
+        observers.removeAll { $0.observer == nil }
+
+        // Notify active observers
+        for weakObserver in observers {
+            if let observer = weakObserver.observer {
+                action(observer)
+            }
+        }
+    }
+}
+
+// MARK: - Supporting Types
+
+/// Configuration for background sync behavior
+public struct SyncConfiguration: Sendable {
+    public let activeSyncInterval: TimeInterval
+    public let backgroundSyncInterval: TimeInterval
+    public let syncOnForeground: Bool
+    public let syncOnBackground: Bool
+    public let defaultSyncOptions: SyncOptions
+
+    public init(
+        activeSyncInterval: TimeInterval = 300,
+        backgroundSyncInterval: TimeInterval = 3600,
+        syncOnForeground: Bool = true,
+        syncOnBackground: Bool = true,
+        defaultSyncOptions: SyncOptions = SyncOptions()
+    ) {
+        self.activeSyncInterval = activeSyncInterval
+        self.backgroundSyncInterval = backgroundSyncInterval
+        self.syncOnForeground = syncOnForeground
+        self.syncOnBackground = syncOnBackground
+        self.defaultSyncOptions = defaultSyncOptions
+    }
+
+    public static let `default` = SyncConfiguration()
+}
+
+/// Statistics about sync operations
+public struct SyncStatistics: Sendable {
+    public let lastSyncDate: Date?
+    public let totalSyncs: Int
+    public let successfulSyncs: Int
+    public let failedSyncs: Int
+    public let averageDuration: TimeInterval
+    public let syncHistory: [SyncHistoryEntry]
+
+    public var successRate: Double {
+        guard totalSyncs > 0 else { return 0 }
+        return Double(successfulSyncs) / Double(totalSyncs) * 100
+    }
+}
+
+public struct SyncHistoryEntry: Sendable, Codable {
+    public let timestamp: Date
+    public let success: Bool
+    public let duration: TimeInterval
+    public let pushedCount: Int
+    public let fetchedCount: Int
+    public let error: String?
+}
+
+private struct WeakSyncObserver {
+    weak var observer: SyncObserver?
+    init(_ observer: SyncObserver) { self.observer = observer }
+}

package/Sources/RunicCore/Sync/SyncConflictResolver.swift

@@ -0,0 +1,310 @@
+import Foundation
+
+// MARK: - Sync Conflict Resolver
+
+/// Default implementation of conflict resolution for synchronized records
+///
+/// This resolver implements multiple conflict resolution strategies:
+/// - Last-write-wins (default): Most recently modified record wins
+/// - Prefer local: Always keep local version
+/// - Prefer remote: Always keep remote version
+/// - Highest version: Keep record with highest version number
+/// - Merge: Attempt to merge both versions (custom logic required)
+public actor SyncConflictResolver: SyncConflictResolverProtocol {
+
+    // MARK: - Properties
+
+    /// Statistics about resolved conflicts
+    public private(set) var conflictStats: ConflictStatistics
+
+    /// Custom merge handlers for specific record types
+    private var mergeHandlers: [String: MergeHandler] = [:]
+
+    // MARK: - Initialization
+
+    public init() {
+        self.conflictStats = ConflictStatistics()
+    }
+
+    // MARK: - Public Methods
+
+    /// Resolves a conflict between local and remote versions
+    ///
+    /// - Parameters:
+    ///   - local: The local version of the record
+    ///   - remote: The remote version of the record
+    ///   - strategy: The resolution strategy to apply
+    /// - Returns: The resolved record that should be kept
+    public func resolve(
+        local: SyncableRecord,
+        remote: SyncableRecord,
+        strategy: ConflictResolutionStrategy
+    ) async -> SyncableRecord {
+        // Validate that records are the same type
+        guard local.recordID == remote.recordID else {
+            return local // Fallback to local if IDs don't match
+        }
+
+        let resolved: SyncableRecord
+
+        switch strategy {
+        case .lastWriteWins:
+            resolved = resolveLastWriteWins(local: local, remote: remote)
+
+        case .preferLocal:
+            resolved = local
+
+        case .preferRemote:
+            resolved = remote
+
+        case .highestVersion:
+            resolved = resolveHighestVersion(local: local, remote: remote)
+
+        case .merge:
+            resolved = resolveMerge(local: local, remote: remote)
+        }
+
+        // Update statistics
+        conflictStats.recordConflict(
+            recordType: local.recordType,
+            strategy: strategy,
+            winner: resolved.recordID == local.recordID ? .local : .remote
+        )
+
+        return resolved
+    }
+
+    /// Registers a custom merge handler for a specific record type
+    ///
+    /// - Parameters:
+    ///   - recordType: The CloudKit record type name
+    ///   - handler: Closure that merges two records of this type
+    public func registerMergeHandler(
+        for recordType: String,
+        handler: @escaping MergeHandler
+    ) {
+        mergeHandlers[recordType] = handler
+    }
+
+    /// Resets conflict statistics
+    public func resetStatistics() {
+        conflictStats = ConflictStatistics()
+    }
+
+    // MARK: - Private Resolution Methods
+
+    /// Resolves conflict by keeping the most recently modified record
+    private func resolveLastWriteWins(
+        local: SyncableRecord,
+        remote: SyncableRecord
+    ) -> SyncableRecord {
+        if local.modifiedAt > remote.modifiedAt {
+            return local
+        } else if remote.modifiedAt > local.modifiedAt {
+            return remote
+        } else {
+            // Same timestamp, use version as tiebreaker
+            return local.version >= remote.version ? local : remote
+        }
+    }
+
+    /// Resolves conflict by keeping the record with highest version number
+    private func resolveHighestVersion(
+        local: SyncableRecord,
+        remote: SyncableRecord
+    ) -> SyncableRecord {
+        if local.version > remote.version {
+            return local
+        } else if remote.version > local.version {
+            return remote
+        } else {
+            // Same version, use timestamp as tiebreaker
+            return local.modifiedAt >= remote.modifiedAt ? local : remote
+        }
+    }
+
+    /// Attempts to merge both versions using custom merge logic
+    private func resolveMerge(
+        local: SyncableRecord,
+        remote: SyncableRecord
+    ) -> SyncableRecord {
+        // Check for registered merge handler
+        if let handler = mergeHandlers[local.recordType] {
+            return handler(local, remote)
+        }
+
+        // No custom merge handler, fall back to last-write-wins
+        return resolveLastWriteWins(local: local, remote: remote)
+    }
+}
+
+// MARK: - Supporting Types
+
+/// Closure type for custom merge handlers
+public typealias MergeHandler = @Sendable (SyncableRecord, SyncableRecord) -> SyncableRecord
+
+/// Indicates which version won during conflict resolution
+public enum ConflictWinner: String, Codable, Sendable {
+    case local
+    case remote
+}
+
+/// Statistics about conflict resolution operations
+public struct ConflictStatistics: Sendable {
+    /// Total number of conflicts resolved
+    public private(set) var totalConflicts: Int = 0
+
+    /// Number of conflicts per record type
+    public private(set) var conflictsByType: [String: Int] = [:]
+
+    /// Number of conflicts per strategy
+    public private(set) var conflictsByStrategy: [String: Int] = [:]
+
+    /// Number of wins for local vs remote
+    public private(set) var localWins: Int = 0
+    public private(set) var remoteWins: Int = 0
+
+    /// Timestamp of last conflict
+    public private(set) var lastConflictAt: Date?
+
+    public init() {}
+
+    /// Records a conflict resolution event
+    mutating func recordConflict(
+        recordType: String,
+        strategy: ConflictResolutionStrategy,
+        winner: ConflictWinner
+    ) {
+        totalConflicts += 1
+        conflictsByType[recordType, default: 0] += 1
+        conflictsByStrategy[strategy.rawValue, default: 0] += 1
+
+        switch winner {
+        case .local:
+            localWins += 1
+        case .remote:
+            remoteWins += 1
+        }
+
+        lastConflictAt = Date()
+    }
+
+    /// Percentage of conflicts won by local version
+    public var localWinRate: Double {
+        guard totalConflicts > 0 else { return 0 }
+        return Double(localWins) / Double(totalConflicts)
+    }
+
+    /// Percentage of conflicts won by remote version
+    public var remoteWinRate: Double {
+        guard totalConflicts > 0 else { return 0 }
+        return Double(remoteWins) / Double(totalConflicts)
+    }
+
+    /// Human-readable summary of conflict statistics
+    public var summary: String {
+        var lines = [
+            "Conflict Resolution Statistics:",
+            "  Total conflicts: \(totalConflicts)",
+            "  Local wins: \(localWins) (\(String(format: "%.1f%%", localWinRate * 100)))",
+            "  Remote wins: \(remoteWins) (\(String(format: "%.1f%%", remoteWinRate * 100)))"
+        ]
+
+        if !conflictsByType.isEmpty {
+            lines.append("  By record type:")
+            for (type, count) in conflictsByType.sorted(by: { $0.value > $1.value }) {
+                lines.append("    \(type): \(count)")
+            }
+        }
+
+        if !conflictsByStrategy.isEmpty {
+            lines.append("  By strategy:")
+            for (strategy, count) in conflictsByStrategy.sorted(by: { $0.value > $1.value }) {
+                lines.append("    \(strategy): \(count)")
+            }
+        }
+
+        if let lastConflict = lastConflictAt {
+            let formatter = RelativeDateTimeFormatter()
+            let timeAgo = formatter.localizedString(for: lastConflict, relativeTo: Date())
+            lines.append("  Last conflict: \(timeAgo)")
+        }
+
+        return lines.joined(separator: "\n")
+    }
+}
+
+// MARK: - Default Merge Handlers
+
+extension SyncConflictResolver {
+    /// Registers default merge handlers for Runic record types
+    public func registerDefaultMergeHandlers() {
+        // Usage Snapshot merge: prefer record with most recent data
+        registerMergeHandler(for: CloudKitRecordType.usageSnapshot) { local, remote in
+            guard let localUsage = local as? UsageSnapshotSyncRecord,
+                  let remoteUsage = remote as? UsageSnapshotSyncRecord else {
+                return local
+            }
+
+            // Prefer the record with more recent usage data
+            return localUsage.updatedAt > remoteUsage.updatedAt ? local : remote
+        }
+
+        // User Preferences merge: combine enabled providers
+        registerMergeHandler(for: CloudKitRecordType.userPreferences) { local, remote in
+            guard let localPrefs = local as? UserPreferencesSyncRecord,
+                  let remotePrefs = remote as? UserPreferencesSyncRecord else {
+                return local
+            }
+
+            // Merge enabled providers (union of both sets)
+            let mergedProviders = Array(Set(localPrefs.enabledProviders + remotePrefs.enabledProviders))
+
+            // Use most recent settings for other fields
+            let source = localPrefs.modifiedAt > remotePrefs.modifiedAt ? localPrefs : remotePrefs
+
+            return UserPreferencesSyncRecord(
+                recordID: localPrefs.recordID,
+                version: max(localPrefs.version, remotePrefs.version) + 1,
+                modifiedAt: Date(),
+                lastModifiedDeviceID: source.lastModifiedDeviceID,
+                refreshInterval: source.refreshInterval,
+                enabledProviders: mergedProviders,
+                notificationsEnabled: source.notificationsEnabled,
+                autoRefreshEnabled: source.autoRefreshEnabled,
+                theme: source.theme,
+                displayFormat: source.displayFormat
+            )
+        }
+
+        // Alert Configuration merge: prefer most restrictive thresholds
+        registerMergeHandler(for: CloudKitRecordType.alertConfiguration) { local, remote in
+            guard let localAlert = local as? AlertConfigurationSyncRecord,
+                  let remoteAlert = remote as? AlertConfigurationSyncRecord else {
+                return local
+            }
+
+            // Use lower (more conservative) thresholds
+            let warningThreshold = min(localAlert.warningThreshold, remoteAlert.warningThreshold)
+            let criticalThreshold = min(localAlert.criticalThreshold, remoteAlert.criticalThreshold)
+
+            // Merge notification channels (union)
+            let mergedChannels = Array(Set(localAlert.notificationChannels + remoteAlert.notificationChannels))
+
+            // Enabled if either version has it enabled
+            let enabled = localAlert.enabled || remoteAlert.enabled
+
+            return AlertConfigurationSyncRecord(
+                recordID: localAlert.recordID,
+                version: max(localAlert.version, remoteAlert.version) + 1,
+                modifiedAt: Date(),
+                lastModifiedDeviceID: localAlert.lastModifiedDeviceID,
+                providerID: localAlert.providerID,
+                warningThreshold: warningThreshold,
+                criticalThreshold: criticalThreshold,
+                notificationChannels: mergedChannels,
+                enabled: enabled
+            )
+        }
+    }
+}