@hot-updater/react-native 1.1.0 → 1.1.2

package/ios/HotUpdater/Internal/HotUpdaterImpl.swift

@@ -149,6 +149,20 @@ private func hotUpdaterGetMinBundleId() -> String {
     private let recoveryManager: HotUpdaterRecoveryManager
     private let releaseCatalogCache: ReleaseCatalogCacheService
     private let keyValueStorage: KeyValueStorageService
+    /// Main only: the native update check of the first launch with UI after
+    /// a crash. None in a development build.
+    private let postCrashUpdateCheck: HotUpdaterPostCrashUpdateCheck?
+
+    /// A development build, where a crash is a RedBox during development,
+    /// never a reason to check for a fix: main records no crash after its
+    /// watch and never checks after one.
+    static let isDevelopmentBuild: Bool = {
+        #if DEBUG
+        return true
+        #else
+        return false
+        #endif
+    }()
     // Read by native update checks on other threads while React Native sets it.
     private let launchSelectionLock = NSLock()
     private var launchSelectionValue: LaunchSelection?
@@ -282,6 +296,13 @@ private func hotUpdaterGetMinBundleId() -> String {
         self.recoveryManager = recoveryManager
         self.releaseCatalogCache = releaseCatalogCache
         self.keyValueStorage = keyValueStorage
+        self.postCrashUpdateCheck = environment.isMain && !HotUpdaterImpl.isDevelopmentBuild
+            ? HotUpdaterPostCrashUpdateCheck(
+                storage: keyValueStorage,
+                whenShown: HotUpdaterImpl.whenAppIsActive,
+                check: HotUpdaterImpl.checkAfterCrash
+            )
+            : nil
         super.init()
         recoveryManager.onRollbackCharged = { [weak self] in
             self?.invalidateLaunchPreparation()
@@ -382,6 +403,11 @@ private func hotUpdaterGetMinBundleId() -> String {
             HotUpdaterMainBundle.shared.note(bundle)
         }
         let bundleURL = prepareLaunchIfNeeded(bundle: bundle).bundleURL
+        // After the launch lock is released: the check reads the launch
+        // through it, and never holds up React Native's start.
+        if environment.isMain, self === HotUpdaterNativeUpdateBridge.sharedImpl {
+            postCrashUpdateCheck?.startIfNeeded()
+        }
         if !environment.isMain, let bundleURL {
             // The runtime started with this URL finds this impl by it.
             HotUpdaterNativeUpdateBridge.router.record(launchURL: bundleURL, name: environment.name)
@@ -995,7 +1021,7 @@ private func hotUpdaterGetMinBundleId() -> String {
             // Settles what the previous process left first, so the check reads the
             // selection, launch state, and crash history this launch will use.
             // Each instance consumes only its own crash marker.
-            bundleStorage.settlePreviousLaunch(pendingRecovery: { self.recoveryManager.consumePendingCrashRecovery() })
+            bundleStorage.settlePreviousLaunch(pendingRecovery: { self.consumePendingCrashRecovery() })
             return bundleStorage.peekLaunchBundleId()
         }
     }
@@ -1054,7 +1080,7 @@ private func hotUpdaterGetMinBundleId() -> String {
         // retry replaces it.
         let (selection, generation, epoch) = launchEpoch.prepareCurrent(
             prepare: {
-                let pendingRecovery = recoveryManager.consumePendingCrashRecovery()
+                let pendingRecovery = consumePendingCrashRecovery()
                 return bundleStorage.prepareLaunch(bundle: bundle, pendingRecovery: pendingRecovery)
             },
             startMonitoring: { selection in
@@ -1084,6 +1110,61 @@ private func hotUpdaterGetMinBundleId() -> String {
         return selection
     }
 
+    /// Keeps a native check's request the server answered for main's check
+    /// after a crash, as JavaScript's checks do; an app that checks only
+    /// natively has no other. Nothing for a named instance or in a
+    /// development build, which have no such check.
+    func recordRecoveryRequest(_ request: NativeCheckRequest) {
+        guard postCrashUpdateCheck != nil, let json = HotUpdaterRecoveryCheckConfig.json(for: request) else { return }
+        keyValueStorage.setItem(HotUpdaterRecoveryCheckConfig.storageKey, value: json)
+    }
+
+    /// This instance's crash marker; for main outside a development build,
+    /// a marker that doesn't roll back also leaves the post-crash update
+    /// check pending.
+    private func consumePendingCrashRecovery() -> PendingCrashRecovery? {
+        guard let postCrashUpdateCheck else {
+            return recoveryManager.consumePendingCrashRecovery()
+        }
+        return postCrashUpdateCheck.consumeMarker { recoveryManager.consumePendingCrashRecovery() }
+    }
+
+    /// Runs `action` once the app is active: a launch without UI, such as a
+    /// silent push, leaves the post-crash check to a later foreground.
+    private static func whenAppIsActive(_ action: @escaping () -> Void) {
+        DispatchQueue.main.async {
+            if UIApplication.shared.applicationState == .active {
+                action()
+                return
+            }
+            NSLog("[HotUpdaterRecovery] Post-crash update check: skipped until the app becomes active")
+            // Boxed: the observer block may not capture a mutable variable.
+            let registration = HotUpdaterObserverRegistration()
+            registration.token = NotificationCenter.default.addObserver(
+                forName: UIApplication.didBecomeActiveNotification,
+                object: nil,
+                queue: .main
+            ) { _ in
+                guard let token = registration.token else { return }
+                NotificationCenter.default.removeObserver(token)
+                registration.token = nil
+                action()
+            }
+        }
+    }
+
+    /// Main's native check of the current channel, which stages an update it
+    /// finds for the next launch; no reload.
+    private static func checkAfterCrash(
+        _ request: NativeCheckRequest
+    ) async throws -> HotUpdaterPostCrashUpdateCheck.Outcome {
+        let checker = HotUpdaterNativeUpdateBridge.checker(impl: HotUpdaterNativeUpdateBridge.sharedImpl)
+        guard let update = try await checker.checkForUpdate(request) else {
+            return .noUpdate
+        }
+        return try await update.updateBundle() ? .staged(bundleId: update.bundleId) : .superseded
+    }
+
     // A background launch, such as a silent push, may never render. Only a
     // launch in the foreground may leave an unfinished launch for the next
     // process to roll back.
@@ -1132,6 +1213,12 @@ private func hotUpdaterGetMinBundleId() -> String {
     }
 }
 
+/// A one-shot notification observer's token, which its own block removes.
+/// Main thread only.
+private final class HotUpdaterObserverRegistration {
+    var token: NSObjectProtocol?
+}
+
 /// One instance's crash recovery: consumes its marker at launch, watches its
 /// launch until 10 seconds after its first content, and for main, reloads
 /// in-process when its JavaScript fails before first content. The state lives
@@ -1356,9 +1443,15 @@ private final class HotUpdaterSignalCrashSlots: HotUpdaterCrashSlotSink {
 final class HotUpdaterRecoveryHub: NSObject {
     static let shared = HotUpdaterRecoveryHub()
 
-    let coordinator = HotUpdaterRecoveryCoordinator(sink: HotUpdaterSignalCrashSlots())
+    let coordinator = HotUpdaterRecoveryCoordinator(
+        sink: HotUpdaterSignalCrashSlots(),
+        recordsCrashesAfterWatch: !HotUpdaterImpl.isDevelopmentBuild
+    )
     /// The launch each runtime runs, by its module.
     private let runtimeLaunches = HotUpdaterRuntimeLaunches()
+    /// Content that appeared in the background, until the foreground.
+    private let backgroundContent = HotUpdaterBackgroundContent()
+    private var backgroundContentObservers: [NSObjectProtocol] = []
 
     override init() {
         super.init()
@@ -1688,6 +1781,17 @@ final class HotUpdaterRecoveryHub: NSObject {
 
     @objc private func handleContentDidAppear(_ notification: Notification) {
         let view = notification.object as AnyObject?
+        // React Native posts content on the main thread, where UIApplication
+        // is read. Content the app shows in the background verifies nothing
+        // until the app comes to the foreground (`HotUpdaterBackgroundContent`).
+        if Thread.isMainThread, UIApplication.shared.applicationState == .background {
+            holdUntilForeground(view)
+            return
+        }
+        contentAppeared(view)
+    }
+
+    private func contentAppeared(_ view: AnyObject?) {
         let owner = owner(of: view)
         // A view no runtime claims is main's, as it always was, unless a
         // named runtime that has no module yet may have shown it.
@@ -1723,6 +1827,24 @@ final class HotUpdaterRecoveryHub: NSObject {
         }
     }
 
+    /// Main thread only.
+    private func holdUntilForeground(_ view: AnyObject?) {
+        guard backgroundContent.hold(view) else { return }
+        backgroundContentObservers = [
+            UIApplication.willEnterForegroundNotification,
+            UIApplication.didBecomeActiveNotification,
+        ].map { name in
+            NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in
+                guard let self else { return }
+                self.backgroundContentObservers.forEach { NotificationCenter.default.removeObserver($0) }
+                self.backgroundContentObservers = []
+                for view in self.backgroundContent.takeAll() {
+                    self.contentAppeared(view)
+                }
+            }
+        }
+    }
+
     /// Credits the content held for runtimes that had no module yet. Main
     /// thread only.
     private func releaseHeldContent() {

package/ios/HotUpdater/Internal/HotUpdaterLaunchRecovery.swift

@@ -83,7 +83,10 @@ protocol HotUpdaterCrashSlotSink: AnyObject {
 /// selected in the foreground, and its fatal before first content reloads it
 /// in-process. A named launch counts as started only once a view of its
 /// runtime is shown, since a runtime warmed up without UI must not be rolled
-/// back at the next start.
+/// back at the next start. After its watch ends, main still writes its marker
+/// on a crash of its own or of the process, without rollback: its next launch
+/// then checks for a fix natively, since this bundle's JavaScript may crash
+/// before it can.
 final class HotUpdaterRecoveryCoordinator {
     /// Native crash markers the signal handler can write, main's included.
     /// More instances than this still roll back an unfinished launch at their
@@ -142,6 +145,23 @@ final class HotUpdaterRecoveryCoordinator {
         fileprivate(set) var isCharged = false
         /// The directory of `markerURL` was created.
         fileprivate var hasMarkerDirectory = false
+
+        /// Main only, outside development builds: a crash after its watch
+        /// ended still writes its marker (`recordsCrashesAfterWatch`).
+        fileprivate var recordsAfterWatch = false
+
+        /// Whether a crash now writes this launch's marker: while it is
+        /// watched, and for main for the rest of the process once it
+        /// launched, so the next launch knows to check for a fix
+        /// (`HotUpdaterPostCrashUpdateCheck`).
+        fileprivate var recordsCrashes: Bool {
+            isMonitoring || (recordsAfterWatch && generation > 0)
+        }
+        /// The bundle a marker of this launch names: main's selected bundle
+        /// once its watch ended, which cleared `bundleId`.
+        fileprivate var markerBundleId: String? {
+            recordsAfterWatch && !isMonitoring ? selectedBundleId : bundleId
+        }
     }
 
     enum RecoveryRequest: Equatable {
@@ -251,9 +271,18 @@ final class HotUpdaterRecoveryCoordinator {
     /// verified and the next start would roll it back.
     static let heldContentBound: TimeInterval = 10
 
-    init(sink: HotUpdaterCrashSlotSink, now: @escaping () -> TimeInterval = { ProcessInfo.processInfo.systemUptime }) {
+    /// Main's crashes after its watch ended write its marker. A development
+    /// build turns this off: a RedBox is no reason to check for a fix.
+    private let recordsCrashesAfterWatch: Bool
+
+    init(
+        sink: HotUpdaterCrashSlotSink,
+        now: @escaping () -> TimeInterval = { ProcessInfo.processInfo.systemUptime },
+        recordsCrashesAfterWatch: Bool = true
+    ) {
         self.sink = sink
         self.now = now
+        self.recordsCrashesAfterWatch = recordsCrashesAfterWatch
     }
 
     // MARK: - Instances
@@ -267,6 +296,7 @@ final class HotUpdaterRecoveryCoordinator {
                 return launch
             }
             let launch = Launch(name: name, markerURL: markerURL, storage: storage)
+            launch.recordsAfterWatch = launch.isMain && recordsCrashesAfterWatch
             launches[name] = launch
             return launch
         }
@@ -737,7 +767,8 @@ final class HotUpdaterRecoveryCoordinator {
         !launch.isMain && launch.isMonitoring && launch.isAwaitingContent && !launch.hasResolvedRuntime
     }
 
-    /// Ends the grace period after first content.
+    /// Ends the grace period after first content. Main's crashes are still
+    /// recorded afterwards, without rollback, naming the bundle it runs.
     func finishMonitoring(name: String, generation: Int) {
         withLock {
             guard let launch = launches[name], launch.generation == generation else { return }
@@ -873,7 +904,9 @@ final class HotUpdaterRecoveryCoordinator {
                 writeMarker(launch)
             }
             let claim = attribute(to: owner)
-            if launch.isMonitoring, !markerFirst {
+            // Main's marker is written after its watch ended too, without
+            // rollback.
+            if launch.recordsCrashes, !markerFirst {
                 writeMarker(launch)
             }
             return claim
@@ -1119,7 +1152,7 @@ final class HotUpdaterRecoveryCoordinator {
         charging {
             if let attributedName, let launch = launches[attributedName] {
                 // Not a later launch of the claimed instance.
-                if launch.isMonitoring, launch.generation == attributedGeneration {
+                if launch.recordsCrashes, launch.generation == attributedGeneration {
                     writeMarker(launch)
                 }
                 return
@@ -1191,9 +1224,9 @@ final class HotUpdaterRecoveryCoordinator {
 
     private func chargeUnattributedCrash() {
         for launch in launches.values {
-            // Main writes while it watches its launch, as it always has; a
-            // marker of a verified launch carries `shouldRollback: false`.
-            if launch.isMain ? launch.isMonitoring : launch.crashCountsAgainstLaunch {
+            // Main writes for the whole process once it launched; a marker
+            // of a verified launch carries `shouldRollback: false`.
+            if launch.isMain ? launch.recordsCrashes : launch.crashCountsAgainstLaunch {
                 writeMarker(launch)
             }
         }
@@ -1204,7 +1237,7 @@ final class HotUpdaterRecoveryCoordinator {
     /// `onRollbackCharged` once the charge finishes (`charging`).
     private func writeMarker(_ launch: Launch) {
         HotUpdaterCrashMarker.write(
-            bundleId: launch.bundleId,
+            bundleId: launch.markerBundleId,
             shouldRollback: launch.shouldRollback,
             to: launch.markerURL
         )
@@ -1256,7 +1289,17 @@ final class HotUpdaterRecoveryCoordinator {
         guard let slot = launch.slot else { return }
         let flag = launch.crashCountsAgainstLaunch
         slotFlags[slot] = flag
-        sink.updateSlot(slot, markerPath: launch.markerURL.path, bundleId: launch.bundleId, shouldRollback: flag)
+        // Main's slot writes on any signal, and keeps naming its bundle
+        // after its watch ended. A development build's names no marker once
+        // the watch ended, so a signal then records nothing either: an empty
+        // path is a slot the signal handler skips.
+        let recordsNow = !launch.isMain || launch.isMonitoring || launch.recordsAfterWatch
+        sink.updateSlot(
+            slot,
+            markerPath: recordsNow ? launch.markerURL.path : "",
+            bundleId: launch.markerBundleId,
+            shouldRollback: flag
+        )
         if !launch.hasMarkerDirectory {
             try? FileManager.default.createDirectory(
                 at: launch.markerURL.deletingLastPathComponent(),
@@ -1551,3 +1594,40 @@ final class HotUpdaterRuntimeLaunches {
     }
 }
 
+/// First content that appeared while the app was in the background, such as
+/// the root view a silent push's launch creates. Nobody sees it, so it
+/// verifies no launch until the app comes to the foreground: the old
+/// architecture posts content for a root view even when the headless App
+/// renders nothing, which would otherwise verify a staged bundle no one saw.
+/// A view torn down before then verifies nothing.
+final class HotUpdaterBackgroundContent {
+    private struct Entry {
+        weak var view: AnyObject?
+        let hasView: Bool
+    }
+
+    private let lock = NSLock()
+    private var entries: [Entry] = []
+
+    /// Holds `view`'s content for the foreground. Returns true for the first
+    /// one held, when the caller starts waiting for the foreground.
+    func hold(_ view: AnyObject?) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        entries.append(Entry(view: view, hasView: view != nil))
+        return entries.count == 1
+    }
+
+    /// The content held, once: the views still alive, and nil for content
+    /// that came without a view.
+    func takeAll() -> [AnyObject?] {
+        lock.lock()
+        let taken = entries
+        entries = []
+        lock.unlock()
+        return taken.compactMap { entry -> AnyObject?? in
+            if !entry.hasView { return .some(nil) }
+            return entry.view.map { .some($0) }
+        }
+    }
+}

package/ios/HotUpdater/Internal/HotUpdaterNativeUpdates.swift

@@ -24,6 +24,8 @@ final class HotUpdaterImplUpdateHost: NativeUpdateHost {
 
     func fingerprintHash() -> String? { impl.getFingerprintHash() }
 
+    func recordRecoveryRequest(_ request: NativeCheckRequest) { impl.recordRecoveryRequest(request) }
+
     func crashHistory() -> [String] { impl.getCrashHistory() }
 
     func activeUpdateState() -> [String: Any] { impl.getActiveUpdateState() }

package/ios/HotUpdater/Internal/NativeUpdateCheck.swift

@@ -382,6 +382,13 @@ protocol NativeUpdateHost: NativeUpdateEventStorage {
     func releaseCatalogCache(_ partition: String) -> String?
     func setReleaseCatalogCache(_ partition: String, value: String) -> Bool
     func removeReleaseCatalogCache(_ partition: String)
+    /// The server answered `request`: main keeps it for its check after a
+    /// crash, as JavaScript's checks do.
+    func recordRecoveryRequest(_ request: NativeCheckRequest)
+}
+
+extension NativeUpdateHost {
+    func recordRecoveryRequest(_ request: NativeCheckRequest) {}
 }
 
 /// A promise rejection from a native method, as JavaScript receives it.
@@ -1225,13 +1232,17 @@ final class NativeUpdateChecker {
         )
         let strategyPath = strategy == .fingerprint ? "fingerprint" : "app-version"
         let catalogURL = "\(baseURL)/release-catalogs/\(strategyPath)/ios/\(channelKey)/\(Self.encodeURIComponent(strategyValue))"
-        // The server says this scope has no catalog yet: no update, not a failure.
-        guard let catalog = try await fetchReleaseCatalog(
+        let answer = try await fetchReleaseCatalog(
             baseURL: baseURL,
             url: catalogURL,
             expectedScope: expectedScope,
             options: options
-        ) else {
+        )
+        // The server answered with a valid catalog (checked as it was read),
+        // or with none yet.
+        host.recordRecoveryRequest(options)
+        // The server says this scope has no catalog yet: no update, not a failure.
+        guard let catalog = answer else {
             return nil
         }
         let catalogId = catalog.catalogId
@@ -1597,7 +1608,7 @@ final class NativeUpdateChecker {
     }
 
     /// Header names lowercased, as `new Headers(requestHeaders)` stores them.
-    private static func normalizedHeaders(_ headers: [String: String]) -> [String: String] {
+    static func normalizedHeaders(_ headers: [String: String]) -> [String: String] {
         var normalized = [String: String]()
         for (name, value) in headers {
             normalized[name.lowercased()] = value

package/ios/HotUpdater/Internal/PostCrashUpdateCheck.swift

@@ -0,0 +1,248 @@
+import Foundation
+
+/// What main's JavaScript leaves in its key-value store for the native update
+/// check after a crash: the server and request settings of its last update
+/// check. Without a valid record there is no request at all, since only an
+/// app whose JavaScript checked for updates has agreed to talk to a server.
+struct HotUpdaterRecoveryCheckConfig {
+    static let storageKey = "hot-updater/recovery-check-config"
+    static let version = 1
+    /// `NativeCheckRequest`'s default, for a record written without one.
+    static let defaultRequestTimeoutMs: Double = 5000
+
+    let baseURL: String
+    let requestHeaders: [String: String]
+    /// Seconds, as `NativeCheckRequest` takes it; JavaScript writes milliseconds.
+    let requestTimeout: TimeInterval
+    let updateStrategy: HotUpdaterUpdateStrategy
+
+    /// Nil for a missing, unparsable, or wrong-version record, or one without
+    /// an absolute HTTP(S) `baseURL`, a known `updateStrategy`, string
+    /// headers, or a timeout of at least a millisecond. A record without
+    /// headers or a timeout takes none and the default.
+    init?(json value: String?) {
+        guard let value,
+              let data = value.data(using: .utf8),
+              let object = (try? JSONSerialization.jsonObject(with: data)) as? [String: Any],
+              Self.number(object["version"]) == Double(Self.version),
+              let baseURL = object["baseURL"] as? String,
+              (try? NativeUpdateChecker.validatedBaseURL(baseURL)) != nil else {
+            return nil
+        }
+        switch object["updateStrategy"] as? String {
+        case "appVersion":
+            updateStrategy = .appVersion
+        case "fingerprint":
+            updateStrategy = .fingerprint
+        default:
+            return nil
+        }
+        switch object["requestHeaders"] {
+        case nil:
+            requestHeaders = [:]
+        case let headers as [String: Any]:
+            var strings: [String: String] = [:]
+            for (name, value) in headers {
+                guard let value = value as? String else { return nil }
+                strings[name] = value
+            }
+            requestHeaders = strings
+        default:
+            return nil
+        }
+        let timeoutMs: Double
+        switch object["requestTimeoutMs"] {
+        case nil:
+            timeoutMs = Self.defaultRequestTimeoutMs
+        case let raw:
+            guard let number = Self.number(raw), number.isFinite, number >= 1 else { return nil }
+            timeoutMs = number
+        }
+        self.baseURL = baseURL
+        requestTimeout = timeoutMs / 1000
+    }
+
+    /// The record of `request`, as JavaScript writes it, for a native check of
+    /// main the server answered: its headers as the request sent them, so two
+    /// spellings of one name keep the value that went out. Its channel is left
+    /// out, as JavaScript leaves it out: the check after a crash uses the
+    /// device's own.
+    static func json(for request: NativeCheckRequest) -> String? {
+        let object: [String: Any] = [
+            "version": version,
+            "baseURL": request.baseURL,
+            "requestHeaders": NativeUpdateChecker.normalizedHeaders(request.requestHeaders),
+            "requestTimeoutMs": request.requestTimeout * 1000,
+            "updateStrategy": request.updateStrategy.name,
+        ]
+        guard let data = try? JSONSerialization.data(withJSONObject: object, options: [.sortedKeys]) else {
+            return nil
+        }
+        return String(data: data, encoding: .utf8)
+    }
+
+    /// The check of the current channel with these settings.
+    var request: NativeCheckRequest {
+        NativeCheckRequest(
+            baseURL: baseURL,
+            updateStrategy: updateStrategy,
+            requestHeaders: requestHeaders,
+            channel: nil,
+            requestTimeout: requestTimeout
+        )
+    }
+
+    /// A JSON number; a JSON boolean, which Foundation also reads as an
+    /// NSNumber, is not one.
+    private static func number(_ value: Any?) -> Double? {
+        guard let number = value as? NSNumber, String(cString: number.objCType) != "c" else {
+            return nil
+        }
+        return number.doubleValue
+    }
+}
+
+/// Main's native update check at the first launch with UI after a crash. A
+/// bundle whose JavaScript update flow crashes after its first content is
+/// never rolled back and could never fetch its own fix; this checks for one
+/// natively, and stages what it finds for the next launch.
+///
+/// Consuming any crash marker leaves the check pending in the key-value
+/// store. Once launch preparation finished, the check runs at most once per
+/// process, when the app is shown and JavaScript left a valid config; the
+/// flag is cleared once it finishes, whatever the outcome, so a process that
+/// dies during the check, or a launch without UI, leaves it to the next one.
+final class HotUpdaterPostCrashUpdateCheck: @unchecked Sendable {
+    static let pendingKey = "hot-updater/recovery-check-pending"
+    static let pendingValue = "1"
+
+    /// How a check that ran ended, as its log line reports it.
+    enum Outcome: Equatable {
+        case staged(bundleId: String)
+        case noUpdate
+        /// The update was found, but another check or reset replaced its
+        /// selection before it was staged.
+        case superseded
+    }
+
+    private let storage: KeyValueStorageService
+    private let queue: DispatchQueue
+    private let whenShown: (@escaping () -> Void) -> Void
+    private let check: (NativeCheckRequest) async throws -> Outcome
+    private let log: (String) -> Void
+    private let lock = NSLock()
+    private var state = State.idle
+
+    private enum State {
+        case idle
+        /// Pending, until the app is shown.
+        case waiting
+        /// A check is on its way: nothing starts another in this process.
+        case started
+    }
+
+    /// - Parameters:
+    ///   - storage: main's key-value store, the one JavaScript writes to.
+    ///   - whenShown: runs its argument once the app is shown, now or later.
+    ///   - check: checks with the request, and stages an update it finds.
+    init(
+        storage: KeyValueStorageService,
+        queue: DispatchQueue = DispatchQueue.global(qos: .utility),
+        whenShown: @escaping (@escaping () -> Void) -> Void,
+        check: @escaping (NativeCheckRequest) async throws -> Outcome,
+        log: @escaping (String) -> Void = { NSLog("[HotUpdaterRecovery] Post-crash update check: \($0)") }
+    ) {
+        self.storage = storage
+        self.queue = queue
+        self.whenShown = whenShown
+        self.check = check
+        self.log = log
+    }
+
+    var isPending: Bool {
+        storage.getItem(Self.pendingKey) == Self.pendingValue
+    }
+
+    /// Consumes main's crash marker with `consume`. A marker that doesn't
+    /// ask for rollback means the previous process crashed on a bundle this
+    /// launch runs again, so the next launch with UI checks for a fix. One
+    /// that asks for rollback is settled locally: the bundle that crashed
+    /// before its first content is gone, and the one restored passed its own.
+    /// It also clears a check an earlier crash left pending, which the
+    /// rollback settled too.
+    func consumeMarker(_ consume: () -> PendingCrashRecovery?) -> PendingCrashRecovery? {
+        let recovery = consume()
+        if let recovery {
+            storage.setItem(Self.pendingKey, value: recovery.shouldRollback ? nil : Self.pendingValue)
+        }
+        return recovery
+    }
+
+    /// Call once launch preparation finished. Returns at once: the check runs
+    /// on `queue`, after the app is shown, if it is pending, configured, and
+    /// none ran in this process.
+    func startIfNeeded() {
+        queue.async { [self] in
+            guard request() != nil, transition(from: .idle, to: .waiting) else { return }
+            whenShown { [self] in
+                queue.async { [self] in
+                    // Read again: JavaScript may have refreshed the config
+                    // while the app wasn't shown.
+                    guard let request = request() else {
+                        _ = transition(from: .waiting, to: .idle)
+                        return
+                    }
+                    guard transition(from: .waiting, to: .started) else { return }
+                    log("started")
+                    Task { await run(request) }
+                }
+            }
+        }
+    }
+
+    /// The request a pending check sends, or nil when none is pending, one
+    /// already ran in this process, or JavaScript left no valid config.
+    func request() -> NativeCheckRequest? {
+        guard !started, isPending else { return nil }
+        guard let config = HotUpdaterRecoveryCheckConfig(
+            json: storage.getItem(HotUpdaterRecoveryCheckConfig.storageKey)
+        ) else {
+            log("skipped no config")
+            return nil
+        }
+        return config.request
+    }
+
+    /// Runs the check, then clears the flag, whatever the outcome.
+    func run(_ request: NativeCheckRequest) async {
+        let status: String
+        do {
+            switch try await check(request) {
+            case .staged(let bundleId):
+                status = "staged \(bundleId)"
+            case .noUpdate:
+                status = "no update"
+            case .superseded:
+                status = "skipped superseded"
+            }
+        } catch {
+            status = "failed \(error.localizedDescription)"
+        }
+        storage.setItem(Self.pendingKey, value: nil)
+        log(status)
+    }
+
+    private var started: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return state == .started
+    }
+
+    private func transition(from current: State, to next: State) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard state == current else { return false }
+        state = next
+        return true
+    }
+}