@capawesome/capacitor-live-update 8.6.0 → 8.7.1

package/ios/Plugin/LiveUpdate.swift

@@ -7,25 +7,41 @@ import CommonCrypto
 
 // swiftlint:disable type_body_length
 @objc public class LiveUpdate: NSObject {
+    private static let downloadsDirectoryUrl = FileManager.default
+        .urls(for: .cachesDirectory, in: .userDomainMask).first!
+        .appendingPathComponent("capawesome_capacitor_live_update_downloads")
+    /// Deletes the leftovers of downloads that a process kill interrupted. Runs once per process and
+    /// blocks concurrent initializers until it is done, so no other instance can have a download in flight.
+    private static let interruptedDownloadsDeleted: Void = {
+        try? FileManager.default.removeItem(at: downloadsDirectoryUrl)
+    }()
+
     private let autoUpdateIntervalMs: Int64 = 15 * 60 * 1000 // 15 minutes
     private let bundlesDirectory = "NoCloud/ionic_built_snapshots" // DO NOT CHANGE! (See https://dub.sh/BLluidt)
-    private let cachesDirectoryUrl = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first!
     private let config: LiveUpdateConfig
     private let defaultWebAssetDir = "public" // DO NOT CHANGE! (See https://dub.sh/Buvz4yj)
     private let defaultServerPathKey = "serverBasePath" // DO NOT CHANGE! (See https://dub.sh/ceDl0zT)
-    private let downloadsDirectory = "capawesome_capacitor_live_update_downloads"
     private let httpClient: LiveUpdateHttpClient
     private let libraryDirectoryUrl = FileManager.default.urls(for: .libraryDirectory, in: .userDomainMask).first!
     private let manifestFileName = "capawesome-live-update-manifest.json" // DO NOT CHANGE!
-    private let plugin: LiveUpdatePlugin
+    private let plugin: LiveUpdatePlugin?
     private let preferences: LiveUpdatePreferences
 
+    private var isAppInBackground = false
+    private var lastAutoUpdateCheckTimestamp: Int64 = 0
+    /// Milliseconds left on the rollback timer while it is paused in the background.
+    private var remainingRollbackTimeout: Int?
+    private var rollbackDeadline: DispatchTime?
     private var rollbackDispatchWorkItem: DispatchWorkItem?
     private var rollbackPerformed = false
-    private var lastAutoUpdateCheckTimestamp: Int64 = 0
+    /// Guards the rollback timer state: plugin methods run on the bridge queue, lifecycle callbacks on main.
+    private let rollbackTimerLock = NSLock()
     private var syncInProgress = false
 
-    init(config: LiveUpdateConfig, plugin: LiveUpdatePlugin) {
+    /// - Parameter plugin: The Capacitor plugin, or `nil` for a headless instance
+    ///   (e.g. for Ionic Portals hosts that construct a provider manager directly).
+    ///   In headless mode, WebView-related operations and plugin events are skipped.
+    init(config: LiveUpdateConfig, plugin: LiveUpdatePlugin? = nil) {
         self.config = config
         self.httpClient = LiveUpdateHttpClient(config: config)
         self.plugin = plugin
@@ -38,8 +54,7 @@ import CommonCrypto
         // Set the device ID on the HTTP client (after any potential config reset)
         self.httpClient.setDeviceId(getDeviceId())
 
-        // Delete the leftovers of downloads that were interrupted by a process kill
-        tryDeleteDownloadsDirectory()
+        _ = Self.interruptedDownloadsDeleted
 
         // Start the rollback timer to rollback to the default bundle
         // if the app is not ready after a certain time
@@ -166,6 +181,14 @@ import CommonCrypto
         completion(result, nil)
     }
 
+    /// - Returns: The on-disk URL of a downloaded bundle, or `nil` if the bundle does not exist.
+    public func getBundleDirectory(bundleId: String) -> URL? {
+        guard hasBundleById(bundleId) else {
+            return nil
+        }
+        return buildBundleURLFor(bundleId: bundleId)
+    }
+
     @objc public func getCustomId(completion: @escaping (Result?, Error?) -> Void) {
         let customId = preferences.getCustomId()
 
@@ -208,7 +231,18 @@ import CommonCrypto
         }
     }
 
+    @objc public func handleAppDidEnterBackground() {
+        rollbackTimerLock.lock()
+        defer { rollbackTimerLock.unlock() }
+        isAppInBackground = true
+        pauseRollbackTimer()
+    }
+
     @objc public func handleAppWillEnterForeground() {
+        rollbackTimerLock.lock()
+        defer { rollbackTimerLock.unlock() }
+        isAppInBackground = false
+        resumeRollbackTimer()
         if config.autoUpdateStrategy == "background" {
             performAutoUpdate()
         }
@@ -351,7 +385,12 @@ import CommonCrypto
 
         // Move the unzipped files to the bundles directory
         let bundlePath = self.buildBundlePathFor(bundleId: bundleId)
-        try FileManager.default.moveItem(atPath: indexHtmlFile.deletingLastPathComponent().path, toPath: bundlePath)
+        do {
+            try FileManager.default.moveItem(atPath: indexHtmlFile.deletingLastPathComponent().path, toPath: bundlePath)
+        } catch where hasBundleById(bundleId) {
+            // A concurrent download of the same bundle was installed first
+            CAPLog.print("[", LiveUpdatePlugin.tag, "] ", "Bundle already installed: \(bundleId)")
+        }
     }
 
     private func addBundleOfTypeManifest(bundleId: String, directory: URL) async throws {
@@ -385,7 +424,15 @@ import CommonCrypto
     }
 
     private func buildDownloadsDirectoryUrl() -> URL {
-        return cachesDirectoryUrl.appendingPathComponent(downloadsDirectory)
+        return Self.downloadsDirectoryUrl
+    }
+
+    /// Must be called with `rollbackTimerLock` held.
+    private func clearRollbackTimer() {
+        rollbackDispatchWorkItem?.cancel()
+        rollbackDispatchWorkItem = nil
+        rollbackDeadline = nil
+        remainingRollbackTimeout = nil
     }
 
     private func copyCurrentBundleFile(fileToCopy: ManifestItem, toDirectory: URL) throws {
@@ -455,18 +502,8 @@ import CommonCrypto
     }
 
     private func deleteUnusedBundles() {
-        let bundleIds = getDownloadedBundleIds()
-        let currentBundleId = getCurrentBundleId()
-        let nextBundleId = getNextBundleId()
-
-        for bundleId in bundleIds {
-            if bundleId != currentBundleId && bundleId != nextBundleId {
-                do {
-                    try deleteBundleById(bundleId)
-                } catch {
-                    CAPLog.print("[", LiveUpdatePlugin.tag, "] ", "Failed to delete bundle with id: \(bundleId)")
-                }
-            }
+        for bundleId in getDownloadedBundleIds() {
+            tryDeleteUnusedBundle(bundleId: bundleId)
         }
     }
 
@@ -593,18 +630,18 @@ import CommonCrypto
     }
 
     private func fetchLatestBundle(_ options: FetchLatestBundleOptions) async throws -> GetLatestBundleResponse? {
+        let appId = try requireAppId(options.getAppId())
         let channel = options.getChannel() ?? getChannel()
         var parameters = [String: String]()
         parameters["appVersionCode"] = getVersionCode()
         parameters["appVersionName"] = getVersionName()
-        parameters["bundleId"] = getCurrentBundleId()
+        parameters["bundleId"] = options.getBundleId() ?? getCurrentBundleId()
         parameters["channelName"] = channel
         parameters["customId"] = preferences.getCustomId()
         parameters["deviceId"] = getDeviceId()
         parameters["osVersion"] = await UIDevice.current.systemVersion
         parameters["platform"] = "1"
         parameters["pluginVersion"] = LiveUpdatePlugin.version
-        let appId = try requireAppId()
         var urlComponents = URLComponents(string: "https://\(config.serverDomain)/v1/apps/\(appId)/bundles/latest")!
         urlComponents.queryItems = parameters.map { URLQueryItem(name: $0.key, value: $0.value) }
         let url = try urlComponents.asURL()
@@ -614,12 +651,12 @@ import CommonCrypto
             CAPLog.print("[", LiveUpdatePlugin.tag, "] Latest bundle response: ", String(decoding: data, as: UTF8.self))
         }
         if let error = response.error {
-            if let urlError = error.underlyingError as? URLError {
-                if urlError.code == .timedOut {
-                    throw urlError
-                }
+            // The server answered with an error status, so no update is available
+            if let statusCode = response.response?.statusCode, !(200..<300).contains(statusCode) {
+                return nil
             }
-            return nil
+            // The server could not be reached (e.g. offline or timed out) or sent an invalid body
+            throw error.underlyingError ?? error
         }
         if let value = response.value {
             return value
@@ -642,14 +679,14 @@ import CommonCrypto
         }
     }
 
-    private func getAppId() -> String? {
+    func getAppId() -> String? {
         if let appId = preferences.getAppId() {
             return appId
         }
         return config.appId
     }
 
-    private func getChannel() -> String? {
+    func getChannel() -> String? {
         var channel: String?
         if let _ = config.defaultChannel {
             channel = config.defaultChannel
@@ -695,7 +732,7 @@ import CommonCrypto
 
     /// - Returns: The path to the current bundle directory or `nil` if no view controller was found.
     private func getCurrentCapacitorServerPath() -> String? {
-        guard let viewController = self.plugin.bridge?.viewController as? CAPBridgeViewController else {
+        guard let viewController = self.plugin?.bridge?.viewController as? CAPBridgeViewController else {
             return nil
         }
         return viewController.getServerBasePath()
@@ -730,7 +767,7 @@ import CommonCrypto
         return preferences.getPreviousBundleId()
     }
 
-    private func getVersionCode() -> String {
+    func getVersionCode() -> String {
         guard let appVersionCode = Bundle.main.infoDictionary?["CFBundleVersion"] as? String else {
             return ""
         }
@@ -777,7 +814,7 @@ import CommonCrypto
     }
 
     private func notifyDownloadBundleProgressListeners(_ event: DownloadBundleProgressEvent) {
-        plugin.notifyDownloadBundleProgressListeners(event)
+        plugin?.notifyDownloadBundleProgressListeners(event)
     }
 
     private func performAutoUpdate() {
@@ -804,8 +841,29 @@ import CommonCrypto
         }
     }
 
-    private func requireAppId() throws -> String {
-        guard let appId = getAppId(), !appId.isEmpty else {
+    /// Must be called with `rollbackTimerLock` held.
+    private func pauseRollbackTimer() {
+        guard let deadline = rollbackDeadline else {
+            return
+        }
+        rollbackDispatchWorkItem?.cancel()
+        rollbackDispatchWorkItem = nil
+        rollbackDeadline = nil
+        let now = DispatchTime.now()
+        remainingRollbackTimeout = deadline > now ? Int((deadline.uptimeNanoseconds - now.uptimeNanoseconds) / 1_000_000) : 0
+    }
+
+    /// Must be called with `rollbackTimerLock` held.
+    private func resumeRollbackTimer() {
+        guard let remainingRollbackTimeout = remainingRollbackTimeout else {
+            return
+        }
+        self.remainingRollbackTimeout = nil
+        scheduleRollback(afterMilliseconds: remainingRollbackTimeout)
+    }
+
+    private func requireAppId(_ appIdOverride: String? = nil) throws -> String {
+        guard let appId = appIdOverride ?? getAppId(), !appId.isEmpty else {
             throw CustomError.appIdMissing
         }
         return appId
@@ -861,7 +919,7 @@ import CommonCrypto
     }
 
     private func setCurrentCapacitorServerPath(path: String) {
-        guard let viewController = self.plugin.bridge?.viewController as? CAPBridgeViewController else {
+        guard let viewController = self.plugin?.bridge?.viewController as? CAPBridgeViewController else {
             return
         }
         viewController.setServerBasePath(path: path)
@@ -880,11 +938,11 @@ import CommonCrypto
 
     private func notifyNextBundleSetListeners(_ bundleId: String?) {
         let event = NextBundleSetEvent(bundleId: bundleId)
-        plugin.notifyNextBundleSetListeners(event)
+        plugin?.notifyNextBundleSetListeners(event)
     }
 
     private func notifyReloadedListeners() {
-        plugin.notifyReloadedListeners()
+        plugin?.notifyReloadedListeners()
     }
 
     private func addBlockedBundleId(_ bundleId: String) {
@@ -956,19 +1014,41 @@ import CommonCrypto
         preferences.setPreviousBundleId(bundleId)
     }
 
+    private func scheduleRollback(afterMilliseconds milliseconds: Int) {
+        let deadline = DispatchTime.now() + DispatchTimeInterval.milliseconds(milliseconds)
+        let workItem = DispatchWorkItem { [weak self] in
+            guard let self = self else {
+                return
+            }
+            self.rollbackTimerLock.lock()
+            self.rollbackDeadline = nil
+            self.rollbackTimerLock.unlock()
+            self.rollback()
+        }
+        rollbackDeadline = deadline
+        rollbackDispatchWorkItem = workItem
+        DispatchQueue.main.asyncAfter(deadline: deadline, execute: workItem)
+    }
+
+    /// The timer only counts time in the foreground, because a suspended app cannot call `ready()`.
     private func startRollbackTimer() {
         guard config.readyTimeout > 0 else {
             return
         }
-        stopRollbackTimer()
-        rollbackDispatchWorkItem = DispatchWorkItem { [weak self] in
-            self?.rollback()
+        rollbackTimerLock.lock()
+        defer { rollbackTimerLock.unlock() }
+        clearRollbackTimer()
+        if isAppInBackground {
+            remainingRollbackTimeout = config.readyTimeout
+        } else {
+            scheduleRollback(afterMilliseconds: config.readyTimeout)
         }
-        DispatchQueue.main.asyncAfter(deadline: .now() + DispatchTimeInterval.milliseconds(config.readyTimeout), execute: rollbackDispatchWorkItem!)
     }
 
     private func stopRollbackTimer() {
-        rollbackDispatchWorkItem?.cancel()
+        rollbackTimerLock.lock()
+        defer { rollbackTimerLock.unlock() }
+        clearRollbackTimer()
     }
 
     private func tryCopyCurrentBundleFile(
@@ -994,8 +1074,23 @@ import CommonCrypto
         }
     }
 
-    private func tryDeleteDownloadsDirectory() {
-        tryDeleteDirectory(buildDownloadsDirectoryUrl())
+    /// Deletes the bundle unless it is the current or next bundle.
+    /// - Returns: `true` if the bundle does not exist anymore.
+    @discardableResult
+    func tryDeleteUnusedBundle(bundleId: String) -> Bool {
+        guard hasBundleById(bundleId) else {
+            return true
+        }
+        guard bundleId != getCurrentBundleId() && bundleId != getNextBundleId() else {
+            return false
+        }
+        do {
+            try deleteBundleById(bundleId)
+            return true
+        } catch {
+            CAPLog.print("[", LiveUpdatePlugin.tag, "] ", "Failed to delete bundle with id: \(bundleId)")
+            return false
+        }
     }
 
     private func unzipDownloadedBundle(zipFile: URL) throws -> URL {

package/ios/Plugin/LiveUpdatePlugin.swift

@@ -8,7 +8,7 @@ import Capacitor
 @objc(LiveUpdatePlugin)
 public class LiveUpdatePlugin: CAPPlugin, CAPBridgedPlugin {
     public static let tag = "LiveUpdate"
-    public static let version = "8.6.0"
+    public static let version = "8.7.1"
     public static let userDefaultsPrefix = "CapawesomeLiveUpdate" // DO NOT CHANGE
 
     public let identifier = "LiveUpdatePlugin"
@@ -46,7 +46,7 @@ public class LiveUpdatePlugin: CAPPlugin, CAPBridgedPlugin {
     private let eventNextBundleSet = "nextBundleSet"
     private let eventReloaded = "reloaded"
 
-    private var implementation: LiveUpdate?
+    var implementation: LiveUpdate?
 
     override public func load() {
         self.implementation = LiveUpdate(config: liveUpdateConfig(), plugin: self)
@@ -54,13 +54,22 @@ public class LiveUpdatePlugin: CAPPlugin, CAPBridgedPlugin {
         // Notify implementation about load
         implementation?.handleLoad()
 
-        // Register for app resume notifications
+        // Register for app lifecycle notifications
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleAppDidEnterBackground),
+            name: UIApplication.didEnterBackgroundNotification,
+            object: nil
+        )
         NotificationCenter.default.addObserver(
             self,
             selector: #selector(handleAppWillEnterForeground),
             name: UIApplication.willEnterForegroundNotification,
             object: nil
         )
+        if UIApplication.shared.applicationState == .background {
+            implementation?.handleAppDidEnterBackground()
+        }
     }
 
     @objc func clearBlockedBundles(_ call: CAPPluginCall) {
@@ -387,6 +396,10 @@ public class LiveUpdatePlugin: CAPPlugin, CAPBridgedPlugin {
         notifyListeners(eventReloaded, data: event, retainUntilConsumed: true)
     }
 
+    @objc private func handleAppDidEnterBackground() {
+        implementation?.handleAppDidEnterBackground()
+    }
+
     @objc private func handleAppWillEnterForeground() {
         implementation?.handleAppWillEnterForeground()
     }

package/ios/Plugin/Providers/Ionic/LiveUpdateIonicManager.swift

@@ -0,0 +1,187 @@
+#if CAPAWESOME_INCLUDE_IONIC_PROVIDER
+import Foundation
+import Capacitor
+import LiveUpdateProvider
+
+/// Ionic Live Update Provider manager backed by the Capawesome live update plugin.
+///
+/// Each manager instance is scoped by its resolved app ID and channel so that multiple shells
+/// (Portals or Federated Capacitor apps) can persist their own active bundle without colliding
+/// with each other or with the standalone plugin's `currentBundleId` / `nextBundleId` state.
+///
+/// Provider configuration keys (V1):
+/// - `appId` (optional) — Capawesome Cloud app UUID; falls back to plugin config, required in either
+/// - `channel` (optional) — channel to sync; falls back to plugin config
+/// - `publicKey`, `serverDomain`, `httpTimeout` (optional) — same as the plugin config;
+///   only applied to the headless instance created by `init(configuration:)`
+public final class LiveUpdateIonicManager: ProviderManager {
+    public private(set) var latestAppDirectory: URL?
+
+    private let appId: String
+    private let channel: String?
+    private let liveUpdate: LiveUpdate
+    private let preferences: LiveUpdateIonicPreferences
+    private var syncedBundleId: String?
+
+    /// Creates a manager without a running Capacitor plugin, e.g. for Ionic Portals hosts
+    /// that construct the manager directly and attach it to a Portal via
+    /// `liveUpdateSource: .provider(manager:)`. Uses a headless `LiveUpdate` instance with
+    /// the default configuration, overridden by the configuration dictionary.
+    public convenience init(configuration: [String: Any]) throws {
+        let config = try LiveUpdateIonicManager.buildConfig(configuration: configuration)
+        try self.init(configuration: configuration, liveUpdate: LiveUpdate(config: config))
+    }
+
+    init(configuration: [String: Any], liveUpdate: LiveUpdate) throws {
+        guard let appId = configuration["appId"] as? String ?? liveUpdate.getAppId(), !appId.isEmpty else {
+            throw ProviderError.invalidConfiguration(message: CustomError.appIdMissing.localizedDescription)
+        }
+        let channel = configuration["channel"] as? String ?? liveUpdate.getChannel()
+        self.appId = appId
+        self.channel = channel
+        self.liveUpdate = liveUpdate
+        self.preferences = LiveUpdateIonicPreferences(stateKey: Self.buildStateKey(appId: appId, channel: channel))
+        preferences.resetLastSyncedBundleIdIfVersionChanged(versionCode: liveUpdate.getVersionCode())
+        restoreSyncedBundle()
+        deleteSupersededBundles()
+    }
+
+    private static func buildStateKey(appId: String, channel: String?) -> String {
+        guard let channel = channel, !channel.isEmpty else {
+            return appId
+        }
+        return appId + "." + channel
+    }
+
+    private static func buildConfig(configuration: [String: Any]) throws -> LiveUpdateConfig {
+        var config = LiveUpdateConfig()
+        if let publicKey = try optionalValue(configuration, key: "publicKey", type: String.self) {
+            config.publicKey = publicKey
+        }
+        if let serverDomain = try optionalValue(configuration, key: "serverDomain", type: String.self) {
+            config.serverDomain = serverDomain
+        }
+        if let httpTimeout = try optionalValue(configuration, key: "httpTimeout", type: NSNumber.self) {
+            config.httpTimeout = httpTimeout.intValue
+        }
+        return config
+    }
+
+    private static func optionalValue<T>(_ configuration: [String: Any], key: String, type: T.Type) throws -> T? {
+        guard let value = configuration[key] else {
+            return nil
+        }
+        guard let typedValue = value as? T else {
+            let message = CustomError.configurationValueInvalid(key: key).localizedDescription
+            throw ProviderError.invalidConfiguration(message: message)
+        }
+        return typedValue
+    }
+
+    public func sync() async throws -> (any ProviderSyncResult)? {
+        do {
+            let result = try await liveUpdate.fetchLatestBundle(FetchLatestBundleOptions(appId: appId, bundleId: syncedBundleId, channel: channel))
+
+            // No update available; nothing to report.
+            guard let bundleId = result.getBundleId(), bundleId != syncedBundleId else {
+                return nil
+            }
+
+            let directory: URL
+            if let existingDirectory = liveUpdate.getBundleDirectory(bundleId: bundleId) {
+                directory = existingDirectory
+            } else {
+                directory = try await downloadBundle(bundleId: bundleId, result: result)
+            }
+            applySyncedBundle(bundleId: bundleId, directory: directory)
+            return MetadataSyncResult(metadata: buildMetadata(bundleId: bundleId, customProperties: result.getCustomProperties()))
+        } catch {
+            CAPLog.print("[", LiveUpdatePlugin.tag, "] Ionic provider sync failed: ", error.localizedDescription)
+            throw error
+        }
+    }
+
+    /// Does not delete the previous bundle, because a visible portal may still serve it.
+    /// It is recorded as superseded and deleted on the next launch instead.
+    private func applySyncedBundle(bundleId: String, directory: URL) {
+        syncedBundleId = bundleId
+        latestAppDirectory = directory
+        preferences.setLastSyncedBundleId(bundleId, versionCode: liveUpdate.getVersionCode())
+    }
+
+    private func buildMetadata(bundleId: String, customProperties: [String: Any]?) -> [String: Any] {
+        var metadata: [String: Any] = ["bundleId": bundleId]
+        if let channel = channel {
+            metadata["channel"] = channel
+        }
+        if let customProperties = customProperties, !customProperties.isEmpty {
+            metadata["customProperties"] = customProperties
+        }
+        return metadata
+    }
+
+    /// Deletes the superseded bundles that no manager points to anymore. Bundles that were not
+    /// superseded by a manager are never deleted, because they may belong to the plugin's JS API.
+    private func deleteSupersededBundles() {
+        let supersededBundleIds = preferences.getSupersededBundleIds()
+        if supersededBundleIds.isEmpty {
+            return
+        }
+        let lastSyncedBundleIds = preferences.getLastSyncedBundleIdsOfAllManagers()
+        let deletedBundleIds = supersededBundleIds.filter { bundleId in
+            !lastSyncedBundleIds.contains(bundleId) && liveUpdate.tryDeleteUnusedBundle(bundleId: bundleId)
+        }
+        preferences.removeSupersededBundleIds(deletedBundleIds)
+    }
+
+    /// Downloads the bundle, or awaits a running download of the same bundle, and returns its directory.
+    private func downloadBundle(bundleId: String, result: FetchLatestBundleResult) async throws -> URL {
+        guard let downloadUrl = result.getDownloadUrl(), !downloadUrl.isEmpty else {
+            throw CustomError.downloadUrlMissing
+        }
+        let downloadOptions = DownloadBundleOptions(
+            artifactType: result.getArtifactType() ?? .zip,
+            bundleId: bundleId,
+            checksum: result.getChecksum(),
+            signature: result.getSignature(),
+            url: downloadUrl
+        )
+        try await BundleDownloads.shared.run(bundleId: bundleId) { [liveUpdate] in
+            try await liveUpdate.downloadBundle(downloadOptions)
+        }
+        guard let directory = liveUpdate.getBundleDirectory(bundleId: bundleId) else {
+            throw CustomError.bundleDirectoryNotFound
+        }
+        return directory
+    }
+
+    /// Restores the last synced bundle, if it is still on disk, so the host can load it offline
+    /// and the next sync reports it as the bundle in use.
+    private func restoreSyncedBundle() {
+        guard let bundleId = preferences.getLastSyncedBundleId(),
+              let directory = liveUpdate.getBundleDirectory(bundleId: bundleId) else {
+            return
+        }
+        syncedBundleId = bundleId
+        latestAppDirectory = directory
+    }
+}
+
+/// De-duplicates concurrent downloads of the same bundle across all managers in the process.
+/// A second caller for a bundle that is already downloading awaits the running download.
+private actor BundleDownloads {
+    static let shared = BundleDownloads()
+
+    private var tasks: [String: Task<Void, Error>] = [:]
+
+    func run(bundleId: String, operation: @escaping @Sendable () async throws -> Void) async throws {
+        if let task = tasks[bundleId] {
+            return try await task.value
+        }
+        let task = Task { try await operation() }
+        tasks[bundleId] = task
+        defer { tasks[bundleId] = nil }
+        try await task.value
+    }
+}
+#endif

package/ios/Plugin/Providers/Ionic/LiveUpdateIonicPreferences.swift

@@ -0,0 +1,81 @@
+#if CAPAWESOME_INCLUDE_IONIC_PROVIDER
+import Foundation
+
+/// Persisted state of one provider manager, scoped by its state key (`<appId>` or `<appId>.<channel>`).
+///
+/// All managers share the same `UserDefaults`, so a manager can see which bundles
+/// the other managers still point at.
+final class LiveUpdateIonicPreferences {
+    private static let keyPrefix = "CapawesomeLiveUpdateIonicProvider."
+    private static let lastSyncedBundleIdPrefix = keyPrefix + "lastSyncedBundleId."
+    private static let lastVersionCodePrefix = keyPrefix + "lastVersionCode."
+    private static let supersededBundleIdsPrefix = keyPrefix + "supersededBundleIds."
+
+    private let userDefaults: UserDefaults
+    private let lastSyncedBundleIdKey: String
+    private let lastVersionCodeKey: String
+    private let supersededBundleIdsKey: String
+
+    init(userDefaults: UserDefaults = .standard, stateKey: String) {
+        self.userDefaults = userDefaults
+        self.lastSyncedBundleIdKey = Self.lastSyncedBundleIdPrefix + stateKey
+        self.lastVersionCodeKey = Self.lastVersionCodePrefix + stateKey
+        self.supersededBundleIdsKey = Self.supersededBundleIdsPrefix + stateKey
+    }
+
+    func getLastSyncedBundleId() -> String? {
+        return userDefaults.string(forKey: lastSyncedBundleIdKey)
+    }
+
+    /// - Returns: The last synced bundle IDs of all managers.
+    func getLastSyncedBundleIdsOfAllManagers() -> Set<String> {
+        let bundleIds = userDefaults.dictionaryRepresentation()
+            .filter { $0.key.hasPrefix(Self.lastSyncedBundleIdPrefix) }
+            .compactMap { $0.value as? String }
+        return Set(bundleIds)
+    }
+
+    /// - Returns: The bundles this manager no longer points at and that may be deleted once unused.
+    func getSupersededBundleIds() -> Set<String> {
+        return Set(userDefaults.stringArray(forKey: supersededBundleIdsKey) ?? [])
+    }
+
+    func removeSupersededBundleIds(_ bundleIds: Set<String>) {
+        if bundleIds.isEmpty {
+            return
+        }
+        setSupersededBundleIds(getSupersededBundleIds().subtracting(bundleIds))
+    }
+
+    /// Forgets the last synced bundle if it was synced on another app version code,
+    /// because the bundle was built for that native version.
+    func resetLastSyncedBundleIdIfVersionChanged(versionCode: String) {
+        guard let lastSyncedBundleId = getLastSyncedBundleId(),
+              let lastVersionCode = userDefaults.string(forKey: lastVersionCodeKey),
+              lastVersionCode != versionCode else {
+            return
+        }
+        setSupersededBundleIds(getSupersededBundleIds().union([lastSyncedBundleId]))
+        userDefaults.removeObject(forKey: lastSyncedBundleIdKey)
+        userDefaults.removeObject(forKey: lastVersionCodeKey)
+    }
+
+    /// Points this manager at the given bundle, synced on the given app version code,
+    /// and records the previous bundle as superseded.
+    func setLastSyncedBundleId(_ bundleId: String, versionCode: String) {
+        if let previousBundleId = getLastSyncedBundleId(), previousBundleId != bundleId {
+            setSupersededBundleIds(getSupersededBundleIds().union([previousBundleId]))
+        }
+        userDefaults.set(bundleId, forKey: lastSyncedBundleIdKey)
+        userDefaults.set(versionCode, forKey: lastVersionCodeKey)
+    }
+
+    private func setSupersededBundleIds(_ bundleIds: Set<String>) {
+        if bundleIds.isEmpty {
+            userDefaults.removeObject(forKey: supersededBundleIdsKey)
+        } else {
+            userDefaults.set(Array(bundleIds), forKey: supersededBundleIdsKey)
+        }
+    }
+}
+#endif