@sriinnu/runic 1.2.0 → 2.11.1

package/Sources/RunicCore/Sync/BackgroundSyncManager.swift

@@ -1,385 +0,0 @@
-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

@@ -1,310 +0,0 @@
-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
-            )
-        }
-    }
-}