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

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

@@ -21,6 +21,7 @@ data class BundleMetadata(
     val pendingUpdateStrategy: String? = null,
     val pendingTransition: PendingSelectionTransition? = null,
     val verificationPending: Boolean = false,
+    val launchInProgress: Boolean = false,
     val highestSeenCatalogs: Map<String, CatalogHighWater> = emptyMap(),
     val currentSelectionContexts: Map<String, String> = emptyMap(),
     val updatedAt: Long = System.currentTimeMillis(),
@@ -71,6 +72,7 @@ data class BundleMetadata(
                 pendingTransition =
                     json.optJSONObject("pendingTransition")?.let(PendingSelectionTransition::fromJson),
                 verificationPending = json.optBoolean("verificationPending", false),
+                launchInProgress = json.optBoolean("launchInProgress", false),
                 highestSeenCatalogs = highestSeenCatalogs,
                 currentSelectionContexts = currentSelectionContexts,
                 updatedAt = json.optLong("updatedAt", System.currentTimeMillis()),
@@ -121,6 +123,7 @@ data class BundleMetadata(
             put("pendingUpdateStrategy", pendingUpdateStrategy ?: JSONObject.NULL)
             put("pendingTransition", pendingTransition?.toJson() ?: JSONObject.NULL)
             put("verificationPending", verificationPending)
+            put("launchInProgress", launchInProgress)
             put(
                 "highestSeenCatalogs",
                 JSONObject().apply {
@@ -293,12 +296,44 @@ data class CrashedBundleEntry(
         }
 }
 
+/**
+ * A bundle whose launch ended before first content without a crash, waiting
+ * for its one retry. Such a launch cannot tell a hang from a user leaving
+ * early, so the bundle is offered again instead of entering crash history.
+ * A second unfinished launch of it adds it there.
+ *
+ * [retryReady] turns true once a later launch shows content. The retry
+ * starts with the next process, so the session that recovered never reloads
+ * into the same bundle.
+ */
+data class InterruptedLaunch(
+    val bundleId: String,
+    val retryReady: Boolean = false,
+) {
+    companion object {
+        fun fromJson(json: JSONObject): InterruptedLaunch? =
+            json.optNullableString("bundleId")?.let { bundleId ->
+                InterruptedLaunch(
+                    bundleId = bundleId,
+                    retryReady = json.optBoolean("retryReady", false),
+                )
+            }
+    }
+
+    fun toJson(): JSONObject =
+        JSONObject().apply {
+            put("bundleId", bundleId)
+            put("retryReady", retryReady)
+        }
+}
+
 /**
  * History of crashed bundles
  */
 data class CrashedHistory(
     val bundles: MutableList<CrashedBundleEntry> = mutableListOf(),
     val maxHistorySize: Int = DEFAULT_MAX_HISTORY_SIZE,
+    var interruptedLaunch: InterruptedLaunch? = null,
 ) {
     companion object {
         private const val TAG = "CrashedHistory"
@@ -314,6 +349,7 @@ data class CrashedHistory(
             return CrashedHistory(
                 bundles = bundles,
                 maxHistorySize = json.optInt("maxHistorySize", DEFAULT_MAX_HISTORY_SIZE),
+                interruptedLaunch = json.optJSONObject("interruptedLaunch")?.let(InterruptedLaunch::fromJson),
             )
         }
 
@@ -339,6 +375,7 @@ data class CrashedHistory(
             bundles.forEach { bundlesArray.put(it.toJson()) }
             put("bundles", bundlesArray)
             put("maxHistorySize", maxHistorySize)
+            interruptedLaunch?.let { put("interruptedLaunch", it.toJson()) }
         }
 
     fun saveToFile(file: File): Boolean =
@@ -386,6 +423,7 @@ data class CrashedHistory(
 
     fun clear() {
         bundles.clear()
+        interruptedLaunch = null
     }
 }
 
@@ -394,6 +432,13 @@ data class PendingCrashRecovery(
     val shouldRollback: Boolean,
 ) {
     companion object {
+        internal fun loadFromFile(file: File): PendingCrashRecovery? =
+            try {
+                fromJson(JSONObject(file.readText()))
+            } catch (_: Exception) {
+                null
+            }
+
         fun fromJson(json: JSONObject): PendingCrashRecovery =
             PendingCrashRecovery(
                 launchedBundleId =
@@ -469,21 +514,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 {
@@ -501,8 +542,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,41 +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 invalidFileUrl() =
+        fun invalidManifestParams() =
             HotUpdaterException(
-                "INVALID_FILE_URL",
-                "Invalid 'fileUrl' provided",
+                "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,
@@ -43,19 +277,14 @@ class HotUpdaterException(
         ) = HotUpdaterException(
             "INCOMPLETE_DOWNLOAD",
             "Download incomplete: received $actualSize bytes, expected $expectedSize bytes",
+            failure = UpdateFailure.download(UpdateFailureReason.NETWORK),
         )
 
-        fun extractionFormatError(cause: Throwable? = null) =
-            HotUpdaterException(
-                "EXTRACTION_FORMAT_ERROR",
-                "The downloaded bundle file is not a valid compressed archive",
-                cause,
-            )
-
         fun invalidBundle() =
             HotUpdaterException(
                 "INVALID_BUNDLE",
                 "Bundle missing required platform files (index.ios.bundle or index.android.bundle)",
+                failure = invalidResponse,
             )
 
         fun insufficientDiskSpace(
@@ -64,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) =
@@ -90,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) =
@@ -121,6 +360,7 @@ class HotUpdaterException(
                 "SECURITY_FRAMEWORK_ERROR",
                 "Security framework error occurred",
                 cause,
+                failure = signatureFailure,
             )
 
         // Internal errors
@@ -130,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,
+        )
     }
 }