@hot-updater/react-native 1.0.0-rc.4 → 1.0.0-rc.41

package/android/src/main/java/com/hotupdater/HotUpdaterImpl.kt

@@ -1,6 +1,7 @@
 package com.hotupdater
 
 import android.app.ActivityOptions
+import android.app.Application
 import android.content.Context
 import android.content.Intent
 import android.os.Process
@@ -18,6 +19,9 @@ class HotUpdaterImpl {
     private val preferences: PreferencesService
     private val recoveryManager: HotUpdaterRecoveryManager
     private val releaseCatalogCache: ReleaseCatalogCacheService
+    private val installIdentity: InstallIdentityService
+    private val keyValueStorage: KeyValueStorageService
+    private val activityStartGate: ActivityStartGate
     private var currentLaunchSelection: LaunchSelection? = null
 
     /**
@@ -31,11 +35,14 @@ class HotUpdaterImpl {
         this.context = context.applicationContext
         this.bundleStorage = bundleStorage
         this.preferences = preferences
+        this.activityStartGate = ActivityStartGate(this.context as? Application)
         this.recoveryManager = HotUpdaterRecoveryManager(this.context)
         this.releaseCatalogCache =
             ReleaseCatalogCacheService(
                 File(this.context.noBackupFilesDir, "hot-updater-release-catalog-cache"),
             )
+        this.installIdentity = InstallIdentityService.create(this.context)
+        this.keyValueStorage = KeyValueStorageService.create(this.context)
     }
 
     /**
@@ -83,14 +90,12 @@ class HotUpdaterImpl {
             val fileSystem = FileManagerService(appContext)
             val preferences = createPreferences(appContext)
             val downloadService = OkHttpDownloadService()
-            val decompressService = DecompressService()
             val isolationKey = getIsolationKey(appContext)
 
             return BundleFileStorageService(
                 appContext,
                 fileSystem,
                 downloadService,
-                decompressService,
                 preferences,
                 isolationKey,
             )
@@ -268,36 +273,37 @@ class HotUpdaterImpl {
     fun getJSBundleFile(): String = prepareLaunchIfNeeded().bundleUrl
 
     /**
-     * Updates the bundle from the specified URL
+     * Updates the bundle from its manifest and complete asset descriptors.
      * @param bundleId ID of the bundle to update
-     * @param fileUrl URL of the bundle file to download (or null to reset)
-     * @param fileHash Combined hash string for verification (sig:<signature> or <hex_hash>)
+     * @param manifestUrl URL of the target manifest
+     * @param manifestFileHash Hash or signature used to verify the target manifest
+     * @param assets Complete target asset descriptor map
      * @param progressCallback Callback for download progress updates
+     * @return how the staged bundle arrived
      * @throws HotUpdaterException if the update fails
      */
     suspend fun updateBundle(
         bundleId: String,
-        fileUrl: String?,
-        fileHash: String?,
-        manifestUrl: String?,
-        manifestFileHash: String?,
-        changedAssets: Map<String, ChangedAssetDescriptor>?,
+        manifestUrl: String,
+        manifestFileHash: String,
+        assets: Map<String, ChangedAssetDescriptor>,
         channel: String?,
         selection: PersistedSelection? = null,
+        archiveUrl: String? = null,
         progressCallback: (UpdateProgressPayload) -> Unit,
-    ) {
+    ): UpdateBundleResult {
         if (selection != null && !bundleStorage.stageReleaseSelection(selection)) {
-            throw IllegalStateException("Release catalog selection is stale")
+            throw StaleReleaseSelectionException()
         }
-        bundleStorage.updateBundle(
-            bundleId,
-            fileUrl,
-            fileHash,
-            manifestUrl,
-            manifestFileHash,
-            changedAssets,
-            progressCallback,
-        )
+        val result =
+            bundleStorage.updateBundle(
+                bundleId,
+                manifestUrl,
+                manifestFileHash,
+                assets,
+                archiveUrl,
+                progressCallback,
+            )
 
         if (!channel.isNullOrEmpty()) {
             if (channel == getDefaultChannel()) {
@@ -306,6 +312,7 @@ class HotUpdaterImpl {
                 preferences.setItem(CHANNEL_STORAGE_KEY, channel)
             }
         }
+        return result
     }
 
     /**
@@ -423,17 +430,17 @@ class HotUpdaterImpl {
 
     suspend fun commitReleaseSelection(selection: PersistedSelection): Boolean = bundleStorage.commitReleaseSelection(selection)
 
-    fun getInstallId(): String = bundleStorage.getInstallId()
-
-    fun getUserId(): String? = bundleStorage.getUserId()
+    fun getInstallId(): String = installIdentity.getInstallId()
 
-    fun getUsername(): String? = bundleStorage.getUsername()
+    /** Reads a value from the client plugins' key-value store. */
+    fun getStorageItem(key: String): String? = keyValueStorage.getItem(key)
 
-    fun setUser(
-        userId: String?,
-        username: String?,
+    /** Writes a value to the client plugins' key-value store; null removes the key. */
+    fun setStorageItem(
+        key: String,
+        value: String?,
     ) {
-        bundleStorage.setUser(userId, username)
+        keyValueStorage.setItem(key, value)
     }
 
     /**
@@ -467,7 +474,6 @@ class HotUpdaterImpl {
 
     /**
      * Gets the current launched bundle ID.
-     * Reads manifest.json first and falls back to the legacy BUNDLE_ID file.
      * Built-in bundle fallback is handled in JS.
      */
     fun getBundleId(): String? {
@@ -505,6 +511,16 @@ class HotUpdaterImpl {
 
         val pendingRecovery = recoveryManager.consumePendingCrashRecovery()
         val selection = bundleStorage.prepareLaunch(pendingRecovery)
+        // A headless JS task, such as a background push, loads the bundle without
+        // an activity and never renders. Only a launch with an activity may leave
+        // an unfinished launch for the next process to roll back.
+        activityStartGate.runWhenActivityStarted(
+            if (selection.shouldRollbackOnCrash) {
+                { bundleStorage.markLaunchStarted(selection.launchedBundleId) }
+            } else {
+                null
+            },
+        )
         recoveryManager.startMonitoring(
             bundleId = selection.launchedBundleId,
             shouldRollback = selection.shouldRollbackOnCrash,

package/android/src/main/java/com/hotupdater/HotUpdaterRecoveryManager.kt

@@ -9,6 +9,7 @@ import android.os.Looper
 import android.os.Process
 import android.os.SystemClock
 import android.util.Log
+import androidx.core.util.AtomicFile
 import com.facebook.react.ReactApplication
 import com.facebook.react.bridge.JSExceptionHandler
 import com.facebook.react.bridge.ReactContext
@@ -16,6 +17,7 @@ import com.facebook.react.bridge.ReactMarker
 import com.facebook.react.bridge.ReactMarkerConstants
 import org.json.JSONObject
 import java.io.File
+import java.io.FileOutputStream
 import java.lang.reflect.Field
 import kotlin.system.exitProcess
 
@@ -28,10 +30,7 @@ internal class HotUpdaterRecoveryManager(
     private val crashMarkerFile = File(bundleStoreDir, CRASH_MARKER_FILENAME)
     private val watchdogStateFile = File(bundleStoreDir, WATCHDOG_STATE_FILENAME)
 
-    private var currentBundleId: String? = null
-    private var shouldRollbackOnCrash = false
-    private var isMonitoring = false
-    private var recoveryRequested = false
+    private val launchState = HotUpdaterRecoveryState()
     private var contentAppearedCallback: ((String?) -> Unit)? = null
     private var recoveryRestartCallback: (() -> Boolean)? = null
 
@@ -39,10 +38,7 @@ internal class HotUpdaterRecoveryManager(
         Runnable {
             cancelRecoveryWatchdog()
             Log.d(TAG, "Stopping crash monitoring for current launch")
-            isMonitoring = false
-            recoveryRequested = false
-            shouldRollbackOnCrash = false
-            currentBundleId = null
+            launchState.stop()
             contentAppearedCallback = null
             recoveryRestartCallback = null
             activeManager = null
@@ -52,7 +48,7 @@ internal class HotUpdaterRecoveryManager(
     private val installJsExceptionHooksRunnable =
         object : Runnable {
             override fun run() {
-                if (!isMonitoring) {
+                if (launchState.snapshot() == null) {
                     return
                 }
 
@@ -74,7 +70,7 @@ internal class HotUpdaterRecoveryManager(
         }
 
         return try {
-            val recovery = PendingCrashRecovery.fromJson(JSONObject(crashMarkerFile.readText()))
+            val recovery = PendingCrashRecovery.loadFromFile(crashMarkerFile) ?: return null
             Log.d(
                 TAG,
                 "Consumed pending crash marker bundleId=${recovery.launchedBundleId} shouldRollback=${recovery.shouldRollback}",
@@ -96,11 +92,8 @@ internal class HotUpdaterRecoveryManager(
     ) {
         crashMarkerFile.parentFile?.mkdirs()
         contentAppearedCallback = onContentAppeared
-        currentBundleId = bundleId
-        shouldRollbackOnCrash = shouldRollback
-        isMonitoring = true
-        recoveryRequested = false
         recoveryRestartCallback = onRecoveryRestartRequested
+        launchState.start(bundleId, shouldRollback)
         activeManager = this
 
         ensureExceptionHandlerInstalled()
@@ -122,17 +115,13 @@ internal class HotUpdaterRecoveryManager(
     }
 
     private fun handleContentAppeared() {
-        if (!isMonitoring) {
-            return
-        }
-
-        Log.d(TAG, "First content appeared for bundleId=$currentBundleId")
+        val launch = launchState.completeLaunch() ?: return
+        Log.d(TAG, "First content appeared for bundleId=${launch.bundleId}")
         ReactMarker.removeListener(contentAppearedListener)
         mainHandler.removeCallbacks(installJsExceptionHooksRunnable)
         mainHandler.removeCallbacks(stopMonitoringRunnable)
-        contentAppearedCallback?.invoke(currentBundleId)
-        shouldRollbackOnCrash = false
-        updateNativeLaunchState(currentBundleId, false)
+        contentAppearedCallback?.invoke(launch.bundleId)
+        updateNativeLaunchState(launch.bundleId, false)
         cancelRecoveryWatchdog()
         mainHandler.postDelayed(stopMonitoringRunnable, MONITORING_GRACE_PERIOD_MS)
     }
@@ -145,11 +134,10 @@ internal class HotUpdaterRecoveryManager(
         previousExceptionHandler = Thread.getDefaultUncaughtExceptionHandler()
         Thread.setDefaultUncaughtExceptionHandler { thread, throwable ->
             val manager = activeManager
-            manager?.writeCrashMarker()
-
             if (manager?.requestAutomaticRecovery() == true) {
-                Process.killProcess(Process.myPid())
-                exitProcess(10)
+                // The separate restart activity kills this process after it starts.
+                // A second fatal error must not kill it while that request is in flight.
+                return@setDefaultUncaughtExceptionHandler
             }
 
             previousExceptionHandler?.uncaughtException(thread, throwable)
@@ -161,20 +149,21 @@ internal class HotUpdaterRecoveryManager(
         exceptionHandlerInstalled = true
     }
 
-    private fun writeCrashMarker() {
-        if (!isMonitoring) {
-            return
-        }
-
+    private fun writeCrashMarker(launch: HotUpdaterRecoveryState.Launch) {
+        val atomicFile = AtomicFile(crashMarkerFile)
+        var output: FileOutputStream? = null
         try {
             val payload =
                 JSONObject().apply {
-                    put("bundleId", currentBundleId ?: JSONObject.NULL)
-                    put("shouldRollback", shouldRollbackOnCrash)
+                    put("bundleId", launch.bundleId ?: JSONObject.NULL)
+                    put("shouldRollback", launch.shouldRollback)
                 }
             crashMarkerFile.parentFile?.mkdirs()
-            crashMarkerFile.writeText(payload.toString())
+            output = atomicFile.startWrite()
+            output.write(payload.toString().toByteArray(Charsets.UTF_8))
+            atomicFile.finishWrite(output)
         } catch (e: Exception) {
+            output?.let(atomicFile::failWrite)
             Log.e(TAG, "Failed to write crash marker", e)
         }
     }
@@ -194,35 +183,28 @@ internal class HotUpdaterRecoveryManager(
         cancelRecoveryWatchdogAlarm(appContext)
     }
 
-    private fun requestAutomaticRecovery(): Boolean {
-        if (!isMonitoring || !shouldRollbackOnCrash) {
-            return false
+    private fun requestAutomaticRecovery(exception: Exception? = null): Boolean {
+        val request = launchState.requestRecovery()
+        if (exception != null) {
+            Log.e(TAG, "Caught React startup exception for bundleId=${launchState.snapshot()?.bundleId}", exception)
         }
-
-        synchronized(this) {
-            if (recoveryRequested) {
-                return true
-            }
-            recoveryRequested = true
+        if (request == null) {
+            launchState.snapshot()?.let(::writeCrashMarker)
+            return false
         }
-
+        if (!request.shouldRestart) return true
+        writeCrashMarker(request.launch)
         val started = recoveryRestartCallback?.invoke() == true
+        launchState.finishRecoveryRequest(request, started)
         if (!started) {
-            synchronized(this) {
-                recoveryRequested = false
-            }
             Log.w(TAG, "Failed to schedule automatic recovery restart")
         } else {
-            Log.i(TAG, "Scheduled automatic recovery restart for bundleId=$currentBundleId")
+            Log.i(TAG, "Scheduled automatic recovery restart for bundleId=${request.launch.bundleId}")
         }
         return started
     }
 
-    private fun handleJavaScriptException(exception: Exception): Boolean {
-        Log.e(TAG, "Caught React startup exception for bundleId=$currentBundleId", exception)
-        writeCrashMarker()
-        return requestAutomaticRecovery()
-    }
+    private fun handleJavaScriptException(exception: Exception): Boolean = requestAutomaticRecovery(exception)
 
     private fun ensureNativeSignalHandlerInstalled() {
         if (signalHandlerInstalled || !loadNativeLibrary()) {
@@ -252,141 +234,11 @@ internal class HotUpdaterRecoveryManager(
         }
     }
 
+    // Each architecture's source set reaches its own React instance, so the old
+    // architecture's ReactNativeHost is compiled only into old architecture builds.
     private fun installJavaScriptExceptionHooks() {
         val application = appContext as? ReactApplication ?: return
-
-        if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
-            installReactHostExceptionHook(application)
-        } else {
-            installLegacyExceptionHook(application)
-        }
-    }
-
-    private fun installReactHostExceptionHook(application: ReactApplication) {
-        val reactHost = getReactHost(application) ?: return
-        val reactHostDelegate =
-            findField(reactHost.javaClass, "mReactHostDelegate")?.let { field ->
-                field.isAccessible = true
-                field.get(reactHost)
-            }
-                ?: findField(reactHost.javaClass, "reactHostDelegate")?.let { field ->
-                    field.isAccessible = true
-                    field.get(reactHost)
-                }
-                ?: return
-
-        val delegateIdentity = System.identityHashCode(reactHostDelegate)
-        if (patchedReactHostDelegateIds.add(delegateIdentity)) {
-            val exceptionHandlerField = findField(reactHostDelegate.javaClass, "exceptionHandler")
-            if (exceptionHandlerField == null) {
-                patchedReactHostDelegateIds.remove(delegateIdentity)
-                return
-            }
-
-            exceptionHandlerField.isAccessible = true
-            @Suppress("UNCHECKED_CAST")
-            val previousHandler =
-                exceptionHandlerField.get(reactHostDelegate) as? (Exception) -> Unit
-
-            exceptionHandlerField.set(reactHostDelegate) { exception: Exception ->
-                if (activeManager?.handleJavaScriptException(exception) != true) {
-                    previousHandler?.invoke(exception) ?: throw exception
-                }
-            }
-        }
-
-        val reactContext =
-            findMethod(reactHost.javaClass, "getCurrentReactContext")?.invoke(reactHost) as? ReactContext
-        reactContext?.let { patchReactContextExceptionHandler(it) }
-    }
-
-    private fun installLegacyExceptionHook(application: ReactApplication) {
-        val instanceManager = application.reactNativeHost.reactInstanceManager
-        val managerIdentity = System.identityHashCode(instanceManager)
-        if (patchedInstanceManagerIds.add(managerIdentity)) {
-            val exceptionHandlerField = findField(instanceManager.javaClass, "mJSExceptionHandler")
-            if (exceptionHandlerField == null) {
-                patchedInstanceManagerIds.remove(managerIdentity)
-                return
-            }
-
-            exceptionHandlerField.isAccessible = true
-            val previousHandler = exceptionHandlerField.get(instanceManager) as? JSExceptionHandler
-            exceptionHandlerField.set(instanceManager, RecoveryJSExceptionHandler(previousHandler))
-        }
-
-        instanceManager.currentReactContext?.let { reactContext ->
-            patchReactContextExceptionHandler(reactContext)
-            patchCatalystInstanceExceptionHandler(reactContext)
-        }
-    }
-
-    private fun patchReactContextExceptionHandler(reactContext: ReactContext) {
-        val contextIdentity = System.identityHashCode(reactContext)
-        if (!patchedReactContextIds.add(contextIdentity)) {
-            return
-        }
-
-        val previousHandler = reactContext.jsExceptionHandler
-        if (previousHandler is RecoveryJSExceptionHandler) {
-            return
-        }
-
-        reactContext.setJSExceptionHandler(RecoveryJSExceptionHandler(previousHandler))
-    }
-
-    private fun patchCatalystInstanceExceptionHandler(reactContext: ReactContext) {
-        val catalystInstance =
-            try {
-                reactContext.catalystInstance
-            } catch (_: Exception) {
-                null
-            } ?: return
-
-        val catalystIdentity = System.identityHashCode(catalystInstance)
-        if (!patchedCatalystInstanceIds.add(catalystIdentity)) {
-            return
-        }
-
-        val exceptionHandlerField = findField(catalystInstance.javaClass, "mJSExceptionHandler")
-        if (exceptionHandlerField == null) {
-            patchedCatalystInstanceIds.remove(catalystIdentity)
-            return
-        }
-
-        exceptionHandlerField.isAccessible = true
-        val previousHandler = exceptionHandlerField.get(catalystInstance) as? JSExceptionHandler
-        if (previousHandler is RecoveryJSExceptionHandler) {
-            return
-        }
-        exceptionHandlerField.set(catalystInstance, RecoveryJSExceptionHandler(previousHandler))
-    }
-
-    private fun getReactHost(application: ReactApplication): Any? =
-        try {
-            findMethod(application.javaClass, "getReactHost")?.invoke(application)
-        } catch (_: Exception) {
-            null
-        }
-
-    private fun findMethod(
-        clazz: Class<*>,
-        name: String,
-    ) = runCatching { clazz.getMethod(name) }.getOrNull()
-
-    private fun findField(
-        clazz: Class<*>,
-        name: String,
-    ): Field? {
-        var current: Class<*>? = clazz
-        while (true) {
-            val currentClass = current ?: break
-            runCatching { currentClass.getDeclaredField(name) }
-                .getOrNull()
-                ?.let { return it }
-            current = currentClass.superclass
-        }
-        return null
+        JavaScriptExceptionHooks.install(application)
     }
 
     private fun loadNativeLibrary(): Boolean {
@@ -413,11 +265,11 @@ internal class HotUpdaterRecoveryManager(
         shouldRollback: Boolean,
     )
 
-    private class RecoveryJSExceptionHandler(
+    internal class RecoveryJSExceptionHandler(
         private val previousHandler: JSExceptionHandler?,
     ) : JSExceptionHandler {
         override fun handleException(e: Exception) {
-            if (activeManager?.handleJavaScriptException(e) != true) {
+            if (!handleJavaScriptExceptionForRecovery(e)) {
                 previousHandler?.handleException(e) ?: throw e
             }
         }
@@ -450,10 +302,40 @@ internal class HotUpdaterRecoveryManager(
         @Volatile
         private var activeManager: HotUpdaterRecoveryManager? = null
 
-        private val patchedInstanceManagerIds = mutableSetOf<Int>()
-        private val patchedCatalystInstanceIds = mutableSetOf<Int>()
         private val patchedReactContextIds = mutableSetOf<Int>()
-        private val patchedReactHostDelegateIds = mutableSetOf<Int>()
+
+        /** Hands a JavaScript error to the monitored launch; false when it does not recover it. */
+        internal fun handleJavaScriptExceptionForRecovery(exception: Exception): Boolean =
+            activeManager?.handleJavaScriptException(exception) == true
+
+        internal fun patchReactContextExceptionHandler(reactContext: ReactContext) {
+            val contextIdentity = System.identityHashCode(reactContext)
+            if (!patchedReactContextIds.add(contextIdentity)) {
+                return
+            }
+
+            val previousHandler = reactContext.jsExceptionHandler
+            if (previousHandler is RecoveryJSExceptionHandler) {
+                return
+            }
+
+            reactContext.setJSExceptionHandler(RecoveryJSExceptionHandler(previousHandler))
+        }
+
+        internal fun findField(
+            clazz: Class<*>,
+            name: String,
+        ): Field? {
+            var current: Class<*>? = clazz
+            while (true) {
+                val currentClass = current ?: break
+                runCatching { currentClass.getDeclaredField(name) }
+                    .getOrNull()
+                    ?.let { return it }
+                current = currentClass.superclass
+            }
+            return null
+        }
 
         @JvmStatic
         fun handleRecoveryWatchdog(context: Context) {
@@ -467,7 +349,8 @@ internal class HotUpdaterRecoveryManager(
             }
 
             val crashMarkerFile = File(getBundleStoreDir(appContext), CRASH_MARKER_FILENAME)
-            if (crashMarkerFile.exists()) {
+            val recovery = PendingCrashRecovery.loadFromFile(crashMarkerFile)
+            if (recovery?.shouldRollback == true && recovery.launchedBundleId != null) {
                 Log.i(TAG, "Recovery watchdog detected crash marker, relaunching app")
                 watchdogStateFile.delete()
                 cancelRecoveryWatchdogAlarm(appContext)

package/android/src/main/java/com/hotupdater/HotUpdaterRecoveryState.kt

@@ -0,0 +1,64 @@
+package com.hotupdater
+
+internal class HotUpdaterRecoveryState {
+    data class Launch(
+        val bundleId: String?,
+        val shouldRollback: Boolean,
+    )
+
+    data class RecoveryRequest(
+        val launch: Launch,
+        val shouldRestart: Boolean,
+    )
+
+    private enum class RestartState { NONE, REQUESTED, SCHEDULED, FAILED }
+
+    private var launch: Launch? = null
+    private var restartState = RestartState.NONE
+    private var contentAppeared = false
+
+    @Synchronized
+    fun start(
+        bundleId: String?,
+        shouldRollback: Boolean,
+    ) {
+        launch = Launch(bundleId, shouldRollback)
+        restartState = RestartState.NONE
+        contentAppeared = false
+    }
+
+    @Synchronized
+    fun snapshot(): Launch? = launch
+
+    @Synchronized
+    fun stop() {
+        launch = null
+        restartState = RestartState.NONE
+    }
+
+    @Synchronized
+    fun completeLaunch(): Launch? {
+        val current = launch ?: return null
+        if (contentAppeared || restartState != RestartState.NONE) return null
+        contentAppeared = true
+        launch = current.copy(shouldRollback = false)
+        return current
+    }
+
+    @Synchronized
+    fun requestRecovery(): RecoveryRequest? {
+        val current = launch?.takeIf { it.shouldRollback } ?: return null
+        val shouldRestart = restartState == RestartState.NONE || restartState == RestartState.FAILED
+        if (shouldRestart) restartState = RestartState.REQUESTED
+        return RecoveryRequest(current, shouldRestart)
+    }
+
+    @Synchronized
+    fun finishRecoveryRequest(
+        request: RecoveryRequest,
+        started: Boolean,
+    ) {
+        if (launch !== request.launch) return
+        restartState = if (started) RestartState.SCHEDULED else RestartState.FAILED
+    }
+}

package/android/src/main/java/com/hotupdater/InstallIdentityService.kt

@@ -0,0 +1,37 @@
+package com.hotupdater
+
+import android.content.Context
+import java.io.File
+import java.util.UUID
+
+/**
+ * Owns the install id, a random id created once per app installation.
+ *
+ * The id lives outside the bundle store and outside device backups, so a
+ * device restored from a backup gets an id of its own.
+ */
+class InstallIdentityService(
+    private val identityFile: File,
+) {
+    companion object {
+        /** The install id kept in `noBackupFilesDir/hot-updater/install-identity.json`. */
+        fun create(context: Context): InstallIdentityService =
+            InstallIdentityService(NoBackupStorage.file(context, InstallationIdentity.IDENTITY_FILENAME))
+    }
+
+    private var identity: InstallationIdentity? = null
+
+    /**
+     * Returns the install id, creating and persisting a random one when none
+     * is stored. The id stays stable for this process even if persisting fails.
+     */
+    @Synchronized
+    fun getInstallId(): String {
+        identity?.let { return it.installId }
+        val current =
+            InstallationIdentity.loadFromFile(identityFile)
+                ?: InstallationIdentity(installId = UUID.randomUUID().toString()).also { it.saveToFile(identityFile) }
+        identity = current
+        return current.installId
+    }
+}