@hot-updater/react-native 1.0.0-rc.16 → 1.0.0-rc.17

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

@@ -479,21 +479,17 @@ data class LaunchReport(
         }
 }
 
+/**
+ * The persisted install id. See [InstallIdentityService].
+ */
 data class InstallationIdentity(
     val installId: String,
-    val userId: String? = null,
-    val username: String? = null,
 ) {
     companion object {
         private const val TAG = "InstallationIdentity"
-        const val IDENTITY_FILENAME = "identity.json"
+        const val IDENTITY_FILENAME = "install-identity.json"
 
-        fun fromJson(json: JSONObject): InstallationIdentity =
-            InstallationIdentity(
-                installId = json.getString("installId"),
-                userId = json.optNullableString("userId"),
-                username = json.optNullableString("username"),
-            )
+        fun fromJson(json: JSONObject): InstallationIdentity = InstallationIdentity(installId = json.getString("installId"))
 
         fun loadFromFile(file: File): InstallationIdentity? =
             try {
@@ -511,8 +507,6 @@ data class InstallationIdentity(
     fun toJson(): JSONObject =
         JSONObject().apply {
             put("installId", installId)
-            put("userId", userId ?: JSONObject.NULL)
-            put("username", username ?: JSONObject.NULL)
         }
 
     fun saveToFile(file: File): Boolean =

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

@@ -2,6 +2,51 @@ package com.hotupdater
 
 import android.content.Context
 import java.io.File
+import java.io.FileOutputStream
+import java.io.IOException
+import java.io.OutputStream
+
+/**
+ * An I/O failure writing to local storage, as opposed to a failure reading or
+ * decoding the data being written.
+ */
+class LocalStorageException(
+    cause: IOException,
+) : IOException(cause.message, cause)
+
+/**
+ * An output stream to a local file whose I/O failures, including opening the
+ * file, surface as [LocalStorageException].
+ */
+internal class LocalStorageOutputStream private constructor(
+    private val output: OutputStream,
+) : OutputStream() {
+    companion object {
+        fun open(file: File): LocalStorageOutputStream = LocalStorageOutputStream(storageOperation { FileOutputStream(file) })
+    }
+
+    override fun write(byte: Int) = storageOperation { output.write(byte) }
+
+    override fun write(
+        buffer: ByteArray,
+        offset: Int,
+        length: Int,
+    ) = storageOperation { output.write(buffer, offset, length) }
+
+    override fun flush() = storageOperation { output.flush() }
+
+    override fun close() = storageOperation { output.close() }
+}
+
+/** Runs a local file operation, reporting its I/O failure as [LocalStorageException]. */
+internal inline fun <T> storageOperation(block: () -> T): T =
+    try {
+        block()
+    } catch (error: LocalStorageException) {
+        throw error
+    } catch (error: IOException) {
+        throw LocalStorageException(error)
+    }
 
 /**
  * Interface for file system operations

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

@@ -1,35 +1,275 @@
 package com.hotupdater
 
+import java.io.IOException
+import java.io.InterruptedIOException
+import java.net.MalformedURLException
+import java.net.SocketException
+import java.net.UnknownHostException
+import javax.net.ssl.SSLException
+
+/**
+ * Where an update failed: [DOWNLOAD] covers transferring and verifying the
+ * update's files, [INSTALL] producing the bundle on disk.
+ * Values match `UpdateErrorStage` in packages/react-native/src/clientPlugin.ts.
+ */
+enum class UpdateFailureStage(
+    val value: String,
+) {
+    DOWNLOAD("download"),
+    INSTALL("install"),
+}
+
+/**
+ * Why an update failed.
+ * Values match `UpdateErrorReason` in packages/react-native/src/clientPlugin.ts.
+ */
+enum class UpdateFailureReason(
+    val value: String,
+) {
+    NETWORK("network"),
+    HTTP("http"),
+    INVALID_RESPONSE("invalid_response"),
+    HASH_MISMATCH("hash_mismatch"),
+    SIGNATURE("signature"),
+    PATCH("patch"),
+    EXTRACT("extract"),
+    STORAGE("storage"),
+    UNKNOWN("unknown"),
+}
+
+/** What was being fetched or applied when an update failed. */
+enum class UpdateFailureResource(
+    val value: String,
+) {
+    MANIFEST("manifest"),
+    FILE("file"),
+    PATCH("patch"),
+    ARCHIVE("archive"),
+}
+
+/** Why no HTTP response arrived, for a [UpdateFailureReason.NETWORK] failure. */
+enum class UpdateFailureTransport(
+    val value: String,
+) {
+    TIMEOUT("timeout"),
+    DNS("dns"),
+    TLS("tls"),
+    CONNECTION("connection"),
+    OFFLINE("offline"),
+    CANCELLED("cancelled"),
+}
+
+/**
+ * The classification an `updateBundle` rejection carries as `userInfo`.
+ * [httpStatus] and [originCode] are reported only for
+ * [UpdateFailureReason.HTTP], and [transport] only for
+ * [UpdateFailureReason.NETWORK].
+ */
+data class UpdateFailure(
+    val stage: UpdateFailureStage,
+    val reason: UpdateFailureReason,
+    val httpStatus: Int? = null,
+    val resource: UpdateFailureResource? = null,
+    val transport: UpdateFailureTransport? = null,
+    /** The storage origin's XML error `<Code>`, such as `AccessDenied`. */
+    val originCode: String? = null,
+) {
+    /**
+     * The rejection's `userInfo`:
+     * `{ stage, reason, resource?, httpStatus?, transport?, originCode? }`.
+     */
+    fun toUserInfo(): Map<String, Any> =
+        buildMap {
+            put("stage", stage.value)
+            put("reason", reason.value)
+            resource?.let { put("resource", it.value) }
+            if (reason == UpdateFailureReason.HTTP) {
+                httpStatus?.let { put("httpStatus", it) }
+                originCode?.let { put("originCode", it) }
+            }
+            if (reason == UpdateFailureReason.NETWORK) {
+                transport?.let { put("transport", it.value) }
+            }
+        }
+
+    companion object {
+        fun download(reason: UpdateFailureReason) = UpdateFailure(UpdateFailureStage.DOWNLOAD, reason)
+
+        fun install(reason: UpdateFailureReason) = UpdateFailure(UpdateFailureStage.INSTALL, reason)
+
+        fun http(
+            status: Int,
+            originCode: String? = null,
+        ) = UpdateFailure(UpdateFailureStage.DOWNLOAD, UpdateFailureReason.HTTP, status, originCode = originCode)
+
+        /**
+         * Classifies the error a download returned. OkHttp rejects a URL it
+         * cannot request with IllegalArgumentException, an invalid response.
+         * [isOffline] is asked only after a failed host lookup.
+         */
+        fun ofDownloadError(
+            error: Throwable?,
+            isOffline: () -> Boolean = { false },
+        ): UpdateFailure =
+            when (error) {
+                is HttpStatusException -> {
+                    http(error.statusCode, error.originCode)
+                }
+
+                is LocalStorageException -> {
+                    install(UpdateFailureReason.STORAGE)
+                }
+
+                is MalformedURLException -> {
+                    download(UpdateFailureReason.INVALID_RESPONSE)
+                }
+
+                // The body ended early; the connection itself did not fail.
+                is IncompleteDownloadException -> {
+                    download(UpdateFailureReason.NETWORK)
+                }
+
+                is IOException -> {
+                    UpdateFailure(
+                        UpdateFailureStage.DOWNLOAD,
+                        UpdateFailureReason.NETWORK,
+                        transport = transportOf(error, isOffline),
+                    )
+                }
+
+                is IllegalArgumentException -> {
+                    download(UpdateFailureReason.INVALID_RESPONSE)
+                }
+
+                else -> {
+                    download(UpdateFailureReason.UNKNOWN)
+                }
+            }
+
+        /**
+         * Why a request got no response, or null when the error does not say.
+         * An [InterruptedIOException] is a socket or OkHttp call timeout, a
+         * [SocketException] a refused, unreachable, or reset connection, and
+         * OkHttp reports a canceled call as an IOException "Canceled".
+         */
+        private fun transportOf(
+            error: IOException,
+            isOffline: () -> Boolean,
+        ): UpdateFailureTransport? =
+            when {
+                error is SSLException -> UpdateFailureTransport.TLS
+                error is InterruptedIOException -> UpdateFailureTransport.TIMEOUT
+                error is UnknownHostException -> if (isOffline()) UpdateFailureTransport.OFFLINE else UpdateFailureTransport.DNS
+                error is SocketException -> UpdateFailureTransport.CONNECTION
+                error.message == "Canceled" -> UpdateFailureTransport.CANCELLED
+                else -> null
+            }
+
+        /** Classifies a failed hash or signature check of a downloaded file. */
+        fun ofVerificationError(error: Throwable?): UpdateFailure =
+            when (error) {
+                is SignatureVerificationException.FileHashMismatch -> download(UpdateFailureReason.HASH_MISMATCH)
+                is SignatureVerificationException.FileReadFailed -> install(UpdateFailureReason.STORAGE)
+                else -> download(UpdateFailureReason.SIGNATURE)
+            }
+
+        /**
+         * Classifies an error the pipeline did not anticipate: a malformed URL
+         * is an invalid response, any other I/O error a local storage failure,
+         * and anything else unknown in [stage].
+         */
+        fun ofUnexpectedError(
+            error: Throwable,
+            stage: UpdateFailureStage,
+        ): UpdateFailure =
+            when (error) {
+                is MalformedURLException -> download(UpdateFailureReason.INVALID_RESPONSE)
+                is IOException -> install(UpdateFailureReason.STORAGE)
+                else -> UpdateFailure(stage, UpdateFailureReason.UNKNOWN)
+            }
+    }
+}
+
+/**
+ * The Release catalog selection changed while its bundle was being installed.
+ * The update was superseded, so this rejection is not an update failure.
+ */
+class StaleReleaseSelectionException : IllegalStateException("Release catalog selection is stale")
+
 /**
  * Exception class for Hot Updater errors
  * Matches error codes defined in packages/react-native/src/errors.ts
+ *
+ * [failure] classifies an update failure for JS. It is null for a rejection
+ * that is not an update failure, such as a bundle in the crashed history.
  */
 class HotUpdaterException(
     val code: String,
     message: String,
     cause: Throwable? = null,
+    val failure: UpdateFailure? = null,
 ) : Exception(message, cause) {
+    /**
+     * This failure with [resource] as what was being fetched or applied,
+     * unless it already names one or is not an update failure.
+     */
+    fun withResource(resource: UpdateFailureResource?): HotUpdaterException {
+        val failure = failure
+        if (resource == null || failure == null || failure.resource != null) {
+            return this
+        }
+        return HotUpdaterException(code, message.orEmpty(), cause, failure.copy(resource = resource)).also {
+            it.stackTrace = stackTrace
+        }
+    }
+
     companion object {
+        private val invalidResponse = UpdateFailure.download(UpdateFailureReason.INVALID_RESPONSE)
+        private val signatureFailure = UpdateFailure.download(UpdateFailureReason.SIGNATURE)
+        private val storageFailure = UpdateFailure.install(UpdateFailureReason.STORAGE)
+
         // Parameter validation errors
         fun missingBundleId() =
             HotUpdaterException(
                 "MISSING_BUNDLE_ID",
                 "Missing or empty 'bundleId'",
+                failure = invalidResponse,
             )
 
+        fun invalidManifestParams() =
+            HotUpdaterException(
+                "INVALID_MANIFEST",
+                "Manifest URL, hash, and assets are required",
+                failure = invalidResponse.copy(resource = UpdateFailureResource.MANIFEST),
+            )
+
+        fun invalidFileUrl(
+            parameter: String,
+            url: String,
+            resource: UpdateFailureResource,
+        ) = HotUpdaterException(
+            "INVALID_FILE_URL",
+            "Invalid '$parameter' provided: $url",
+            failure = invalidResponse.copy(resource = resource),
+        )
+
         // Bundle storage errors
         fun directoryCreationFailed() =
             HotUpdaterException(
                 "DIRECTORY_CREATION_FAILED",
                 "Failed to create bundle directory",
+                failure = storageFailure,
             )
 
-        fun downloadFailed(cause: Throwable? = null) =
-            HotUpdaterException(
-                "DOWNLOAD_FAILED",
-                "Failed to download bundle",
-                cause,
-            )
+        fun downloadFailed(
+            cause: Throwable? = null,
+            failure: UpdateFailure = UpdateFailure.ofDownloadError(cause),
+        ) = HotUpdaterException(
+            "DOWNLOAD_FAILED",
+            "Failed to download bundle",
+            cause,
+            failure,
+        )
 
         fun incompleteDownload(
             expectedSize: Long,
@@ -37,12 +277,14 @@ class HotUpdaterException(
         ) = HotUpdaterException(
             "INCOMPLETE_DOWNLOAD",
             "Download incomplete: received $actualSize bytes, expected $expectedSize bytes",
+            failure = UpdateFailure.download(UpdateFailureReason.NETWORK),
         )
 
         fun invalidBundle() =
             HotUpdaterException(
                 "INVALID_BUNDLE",
                 "Bundle missing required platform files (index.ios.bundle or index.android.bundle)",
+                failure = invalidResponse,
             )
 
         fun insufficientDiskSpace(
@@ -51,19 +293,24 @@ class HotUpdaterException(
         ) = HotUpdaterException(
             "INSUFFICIENT_DISK_SPACE",
             "Insufficient disk space: need $required bytes, available $available bytes",
+            failure = storageFailure,
         )
 
-        fun signatureVerificationFailed(cause: Throwable? = null) =
-            HotUpdaterException(
-                "SIGNATURE_VERIFICATION_FAILED",
-                "Bundle signature verification failed",
-                cause,
-            )
+        fun signatureVerificationFailed(
+            cause: Throwable? = null,
+            failure: UpdateFailure = UpdateFailure.ofVerificationError(cause),
+        ) = HotUpdaterException(
+            "SIGNATURE_VERIFICATION_FAILED",
+            "Bundle signature verification failed",
+            cause,
+            failure,
+        )
 
         fun moveOperationFailed() =
             HotUpdaterException(
                 "MOVE_OPERATION_FAILED",
                 "Failed to move bundle files",
+                failure = storageFailure,
             )
 
         fun bundleInCrashedHistory(bundleId: String) =
@@ -77,30 +324,35 @@ class HotUpdaterException(
             HotUpdaterException(
                 "PUBLIC_KEY_NOT_CONFIGURED",
                 "Public key not configured for signature verification",
+                failure = signatureFailure,
             )
 
         fun invalidPublicKeyFormat() =
             HotUpdaterException(
                 "INVALID_PUBLIC_KEY_FORMAT",
                 "Invalid public key format",
+                failure = signatureFailure,
             )
 
         fun fileHashMismatch() =
             HotUpdaterException(
                 "FILE_HASH_MISMATCH",
                 "File hash verification failed",
+                failure = UpdateFailure.download(UpdateFailureReason.HASH_MISMATCH),
             )
 
         fun fileReadFailed() =
             HotUpdaterException(
                 "FILE_READ_FAILED",
                 "Failed to read file for verification",
+                failure = storageFailure,
             )
 
         fun unsignedNotAllowed() =
             HotUpdaterException(
                 "UNSIGNED_NOT_ALLOWED",
                 "Unsigned bundles are not allowed",
+                failure = signatureFailure,
             )
 
         fun securityFrameworkError(cause: Throwable? = null) =
@@ -108,6 +360,7 @@ class HotUpdaterException(
                 "SECURITY_FRAMEWORK_ERROR",
                 "Security framework error occurred",
                 cause,
+                failure = signatureFailure,
             )
 
         // Internal errors
@@ -117,5 +370,30 @@ class HotUpdaterException(
                 "An unknown error occurred",
                 cause,
             )
+
+        /**
+         * A local storage failure while producing the bundle. It keeps the
+         * `UNKNOWN_ERROR` code these failures have always been rejected with.
+         */
+        fun storageFailed(message: String) =
+            HotUpdaterException(
+                "UNKNOWN_ERROR",
+                message,
+                failure = storageFailure,
+            )
+
+        /**
+         * Wraps an error the update pipeline did not anticipate in the
+         * `UNKNOWN_ERROR` rejection it has always produced, adding [failure].
+         */
+        fun unexpected(
+            cause: Throwable,
+            failure: UpdateFailure,
+        ) = HotUpdaterException(
+            "UNKNOWN_ERROR",
+            cause.message ?: "An unknown error occurred",
+            cause,
+            failure,
+        )
     }
 }

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

@@ -18,6 +18,8 @@ class HotUpdaterImpl {
     private val preferences: PreferencesService
     private val recoveryManager: HotUpdaterRecoveryManager
     private val releaseCatalogCache: ReleaseCatalogCacheService
+    private val installIdentity: InstallIdentityService
+    private val keyValueStorage: KeyValueStorageService
     private var currentLaunchSelection: LaunchSelection? = null
 
     /**
@@ -36,6 +38,9 @@ class HotUpdaterImpl {
             ReleaseCatalogCacheService(
                 File(this.context.noBackupFilesDir, "hot-updater-release-catalog-cache"),
             )
+        this.installIdentity = InstallIdentityService.create(this.context)
+        this.keyValueStorage = KeyValueStorageService.create(this.context)
+        PreviousProcessExit.initialize(this.context)
     }
 
     /**
@@ -272,6 +277,7 @@ class HotUpdaterImpl {
      * @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(
@@ -283,18 +289,19 @@ class HotUpdaterImpl {
         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,
-            manifestUrl,
-            manifestFileHash,
-            assets,
-            archiveUrl,
-            progressCallback,
-        )
+        val result =
+            bundleStorage.updateBundle(
+                bundleId,
+                manifestUrl,
+                manifestFileHash,
+                assets,
+                archiveUrl,
+                progressCallback,
+            )
 
         if (!channel.isNullOrEmpty()) {
             if (channel == getDefaultChannel()) {
@@ -303,6 +310,7 @@ class HotUpdaterImpl {
                 preferences.setItem(CHANNEL_STORAGE_KEY, channel)
             }
         }
+        return result
     }
 
     /**
@@ -371,7 +379,15 @@ class HotUpdaterImpl {
         }
     }
 
-    fun notifyAppReady(): Map<String, Any?> = bundleStorage.notifyAppReady()
+    /**
+     * The launch report for this process, with `previousProcessExit` when
+     * Android reports why the previous main process exited.
+     */
+    fun notifyAppReady(): Map<String, Any?> {
+        val report = bundleStorage.notifyAppReady()
+        val previousProcessExit = PreviousProcessExit.get() ?: return report
+        return report + ("previousProcessExit" to previousProcessExit)
+    }
 
     fun acceptReleaseCatalog(
         catalogId: String,
@@ -420,17 +436,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)
     }
 
     /**

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
+    }
+}