@hot-updater/react-native 1.0.0-rc.3 → 1.0.0-rc.30

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()) {
@@ -467,7 +449,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
+    }
+}

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

@@ -0,0 +1,86 @@
+package com.hotupdater
+
+import android.content.Context
+import android.util.Log
+import androidx.core.util.AtomicFile
+import org.json.JSONObject
+import java.io.File
+import java.io.FileNotFoundException
+import java.io.FileOutputStream
+
+/**
+ * The persistent string key-value store behind `getStorageItem` and
+ * `setStorageItem`, which client plugins use through JS. Keys are opaque
+ * here; JS scopes them per plugin.
+ *
+ * Values live as one JSON object in a file outside device backups. The file
+ * is read once, on first use, and rewritten atomically on every set. A
+ * missing, unreadable, or corrupt file reads as empty and is replaced by the
+ * next set. A set that cannot be persisted still applies for this process.
+ */
+class KeyValueStorageService(
+    private val file: File,
+) {
+    companion object {
+        private const val TAG = "KeyValueStorage"
+        const val FILENAME = "storage.json"
+
+        /** The store kept in `noBackupFilesDir/hot-updater/storage.json`. */
+        fun create(context: Context): KeyValueStorageService = KeyValueStorageService(NoBackupStorage.file(context, FILENAME))
+    }
+
+    private var values: MutableMap<String, String>? = null
+
+    @Synchronized
+    fun getItem(key: String): String? = loadValues()[key]
+
+    /** Stores [value] under [key], or removes [key] when [value] is null. */
+    @Synchronized
+    fun setItem(
+        key: String,
+        value: String?,
+    ) {
+        val values = loadValues()
+        if (value == null) {
+            values.remove(key)
+        } else {
+            values[key] = value
+        }
+        write(values)
+    }
+
+    private fun loadValues(): MutableMap<String, String> = values ?: read().also { values = it }
+
+    private fun read(): MutableMap<String, String> =
+        try {
+            val json =
+                AtomicFile(file).openRead().use { input ->
+                    JSONObject(String(input.readBytes(), Charsets.UTF_8))
+                }
+            val stored = linkedMapOf<String, String>()
+            json.keys().forEach { key ->
+                (json.opt(key) as? String)?.let { stored[key] = it }
+            }
+            stored
+        } catch (_: FileNotFoundException) {
+            linkedMapOf()
+        } catch (e: Exception) {
+            // The message of a parse error can quote stored values, so it is not logged.
+            Log.w(TAG, "Ignoring unreadable storage file (${e.javaClass.simpleName})")
+            linkedMapOf()
+        }
+
+    private fun write(values: Map<String, String>) {
+        val atomicFile = AtomicFile(file)
+        var output: FileOutputStream? = null
+        try {
+            file.parentFile?.mkdirs()
+            output = atomicFile.startWrite()
+            output.write(JSONObject(values).toString().toByteArray(Charsets.UTF_8))
+            atomicFile.finishWrite(output)
+        } catch (e: Exception) {
+            output?.let(atomicFile::failWrite)
+            Log.w(TAG, "Failed to persist storage", e)
+        }
+    }
+}

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

@@ -0,0 +1,31 @@
+package com.hotupdater
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.net.ConnectivityManager
+import android.os.Build
+
+internal object NetworkState {
+    /**
+     * True when the device reports no active network. False when it has one,
+     * or when that cannot be told, as when the app lacks
+     * `ACCESS_NETWORK_STATE`.
+     */
+    fun hasNoActiveNetwork(context: Context): Boolean =
+        try {
+            val permission = context.checkCallingOrSelfPermission(Manifest.permission.ACCESS_NETWORK_STATE)
+            val connectivity = context.getSystemService(Context.CONNECTIVITY_SERVICE) as? ConnectivityManager
+            when {
+                permission != PackageManager.PERMISSION_GRANTED || connectivity == null -> false
+                Build.VERSION.SDK_INT >= Build.VERSION_CODES.M -> connectivity.activeNetwork == null
+                else -> hasNoConnectedNetworkLegacy(connectivity)
+            }
+        } catch (_: Exception) {
+            false
+        }
+
+    @Suppress("DEPRECATION")
+    private fun hasNoConnectedNetworkLegacy(connectivity: ConnectivityManager): Boolean =
+        connectivity.activeNetworkInfo?.isConnected != true
+}

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

@@ -0,0 +1,17 @@
+package com.hotupdater
+
+import android.content.Context
+import java.io.File
+
+/**
+ * SDK state that must never be restored onto another installation lives in
+ * `noBackupFilesDir/hot-updater`, which Android Auto Backup skips.
+ */
+internal object NoBackupStorage {
+    private const val DIRECTORY_NAME = "hot-updater"
+
+    fun file(
+        context: Context,
+        name: String,
+    ): File = File(File(context.noBackupFilesDir, DIRECTORY_NAME), name)
+}

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

@@ -1,6 +1,7 @@
 package com.hotupdater
 
 import android.util.Log
+import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.withContext
@@ -15,10 +16,11 @@ import okio.Source
 import okio.buffer
 import java.io.File
 import java.io.IOException
-import java.net.SocketTimeoutException
+import java.net.MalformedURLException
 import java.net.URL
-import java.net.UnknownHostException
 import java.util.concurrent.TimeUnit
+import javax.net.ssl.SSLHandshakeException
+import javax.net.ssl.SSLPeerUnverifiedException
 
 /**
  * Exception for incomplete downloads with size information
@@ -28,6 +30,47 @@ class IncompleteDownloadException(
     val actualSize: Long,
 ) : IOException("Download incomplete: received $actualSize bytes, expected $expectedSize bytes")
 
+/**
+ * The server answered with a non-2xx status. [originCode] is the storage
+ * origin's XML error `<Code>` (S3, R2, or GCS style) when the body names one.
+ */
+class HttpStatusException(
+    val statusCode: Int,
+    statusMessage: String,
+    val originCode: String? = null,
+) : Exception("HTTP error $statusCode: $statusMessage")
+
+/** How much of an error body is read to find a storage origin's error code. */
+internal const val MAX_ORIGIN_ERROR_BODY_BYTES = 4 * 1024L
+
+private val ORIGIN_ERROR_CODE = Regex("<Error(?:\\s[^>]*)?>(?:(?!</Error>).)*?<Code>([^<]*)</Code>", RegexOption.DOT_MATCHES_ALL)
+private val ORIGIN_CODE_VALUE = Regex("[A-Za-z0-9._-]{1,64}")
+
+/**
+ * Reads the `<Code>` of a storage origin's XML error, as in
+ * `<Error><Code>AccessDenied</Code>...`, from at most the first 4 KB of
+ * [body]. Only a 1 to 64 character code of letters, digits, `.`, `_`, and `-`
+ * is kept, so no key, resource, or message text is ever returned.
+ */
+internal fun readOriginErrorCode(body: ResponseBody?): String? =
+    try {
+        body?.source()?.let { source ->
+            source.request(MAX_ORIGIN_ERROR_BODY_BYTES)
+            val prefix = source.buffer.readByteArray(minOf(source.buffer.size, MAX_ORIGIN_ERROR_BODY_BYTES))
+            parseOriginErrorCode(String(prefix, Charsets.UTF_8))
+        }
+    } catch (_: Exception) {
+        null
+    }
+
+internal fun parseOriginErrorCode(body: String): String? =
+    ORIGIN_ERROR_CODE
+        .find(body)
+        ?.groupValues
+        ?.get(1)
+        ?.trim()
+        ?.takeIf { ORIGIN_CODE_VALUE.matches(it) }
+
 /**
  * Result wrapper for download operations
  */
@@ -65,6 +108,13 @@ interface DownloadService {
         fileSizeCallback: ((Long) -> Unit)? = null,
         progressCallback: (DownloadProgress) -> Unit,
     ): DownloadResult
+
+    suspend fun downloadFileOnce(
+        fileUrl: URL,
+        destination: File,
+        fileSizeCallback: ((Long) -> Unit)? = null,
+        progressCallback: (DownloadProgress) -> Unit,
+    ): DownloadResult = downloadFile(fileUrl, destination, fileSizeCallback, progressCallback)
 }
 
 /**
@@ -127,13 +177,33 @@ private class ProgressResponseBody(
         }
 }
 
+/**
+ * Whether a failed download may succeed if tried again: a network failure or
+ * timeout, a body that ended early, or a 408, 429, or 5xx answer. Another 4xx,
+ * a TLS certificate failure, a canceled call, and a local storage failure
+ * would fail the same way again.
+ */
+internal fun isRetryableDownloadError(error: Exception): Boolean =
+    when (error) {
+        is HttpStatusException -> error.statusCode == 408 || error.statusCode == 429 || error.statusCode >= 500
+        is LocalStorageException -> false
+        is SSLHandshakeException, is SSLPeerUnverifiedException -> false
+        is MalformedURLException -> false
+        is IOException -> error.message != "Canceled"
+        else -> false
+    }
+
 /**
  * OkHttp-based implementation of DownloadService with resume support
  */
-class OkHttpDownloadService : DownloadService {
+class OkHttpDownloadService internal constructor(
+    private val initialRetryDelayMs: Long,
+) : DownloadService {
+    constructor() : this(INITIAL_RETRY_DELAY_MS)
+
     companion object {
         private const val TAG = "OkHttpDownloadService"
-        private const val MAX_RETRIES = 3
+        internal const val MAX_ATTEMPTS = 3
         private const val INITIAL_RETRY_DELAY_MS = 1000L
         private const val TIMEOUT_SECONDS = 30L
     }
@@ -146,6 +216,12 @@ class OkHttpDownloadService : DownloadService {
             .writeTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
             .build()
 
+    /**
+     * Downloads [fileUrl], trying again after a retryable failure (see
+     * [isRetryableDownloadError]) up to [MAX_ATTEMPTS] attempts in all, 1 and
+     * then 2 seconds apart. The last attempt's result is returned, so a
+     * failure keeps what classified it.
+     */
     override suspend fun downloadFile(
         fileUrl: URL,
         destination: File,
@@ -153,38 +229,51 @@ class OkHttpDownloadService : DownloadService {
         progressCallback: (DownloadProgress) -> Unit,
     ): DownloadResult =
         withContext(Dispatchers.IO) {
-            var attempt = 0
-            var lastException: Exception? = null
-
-            while (attempt < MAX_RETRIES) {
-                try {
-                    return@withContext attemptDownload(
-                        fileUrl,
-                        destination,
-                        fileSizeCallback,
-                        progressCallback,
-                    )
-                } catch (e: Exception) {
-                    lastException = e
-                    attempt++
-
-                    if (attempt < MAX_RETRIES && isRetryableException(e)) {
-                        val delayMs = INITIAL_RETRY_DELAY_MS * (1 shl (attempt - 1))
-                        Log.d(
-                            TAG,
-                            "Download failed (attempt $attempt/$MAX_RETRIES): ${e.message}. Retrying in ${delayMs}ms...",
-                        )
-                        delay(delayMs)
-                    } else {
-                        Log.d(TAG, "Download failed: ${e.message}")
-                        break
-                    }
-                }
+            var attempt = 1
+            var result = attemptOrError(fileUrl, destination, fileSizeCallback, progressCallback)
+            while (
+                result is DownloadResult.Error &&
+                attempt < MAX_ATTEMPTS &&
+                isRetryableDownloadError(result.exception)
+            ) {
+                val delayMs = initialRetryDelayMs * (1 shl (attempt - 1))
+                Log.d(
+                    TAG,
+                    "Download failed (attempt $attempt/$MAX_ATTEMPTS): ${result.exception.message}. Retrying in ${delayMs}ms...",
+                )
+                delay(delayMs)
+                attempt++
+                result = attemptOrError(fileUrl, destination, fileSizeCallback, progressCallback)
             }
+            if (result is DownloadResult.Error) {
+                Log.d(TAG, "Download failed (attempt $attempt/$MAX_ATTEMPTS): ${result.exception.message}")
+            }
+            result
+        }
 
-            DownloadResult.Error(lastException ?: Exception("Download failed after $MAX_RETRIES attempts"))
+    /** One attempt; an exception a callback threw, such as the disk space check's, is its error. */
+    private suspend fun attemptOrError(
+        fileUrl: URL,
+        destination: File,
+        fileSizeCallback: ((Long) -> Unit)?,
+        progressCallback: (DownloadProgress) -> Unit,
+    ): DownloadResult =
+        try {
+            attemptDownload(fileUrl, destination, fileSizeCallback, progressCallback)
+        } catch (error: CancellationException) {
+            throw error
+        } catch (error: Exception) {
+            DownloadResult.Error(error)
         }
 
+    /** One attempt with no retry, for a download with a fallback, such as the archive's per-file downloads. */
+    override suspend fun downloadFileOnce(
+        fileUrl: URL,
+        destination: File,
+        fileSizeCallback: ((Long) -> Unit)?,
+        progressCallback: (DownloadProgress) -> Unit,
+    ): DownloadResult = attemptOrError(fileUrl, destination, fileSizeCallback, progressCallback)
+
     private suspend fun attemptDownload(
         fileUrl: URL,
         destination: File,
@@ -212,10 +301,10 @@ class OkHttpDownloadService : DownloadService {
             }
 
             if (!response.isSuccessful) {
-                val errorMsg = "HTTP error ${response.code}: ${response.message}"
-                Log.d(TAG, errorMsg)
+                val error = HttpStatusException(response.code, response.message, readOriginErrorCode(response.body))
+                Log.d(TAG, "HTTP error ${response.code}: ${response.message}")
                 response.close()
-                return@withContext DownloadResult.Error(Exception(errorMsg))
+                return@withContext DownloadResult.Error(error)
             }
 
             val body = response.body
@@ -242,9 +331,10 @@ class OkHttpDownloadService : DownloadService {
                         progressCallback.invoke(progress)
                     }
 
-                // Write to file
+                // Write to file. A local write failure surfaces as LocalStorageException,
+                // so it is not mistaken for a network failure.
                 progressBody.source().use { source ->
-                    destination.outputStream().use { output ->
+                    LocalStorageOutputStream.open(destination).use { output ->
                         val buffer = ByteArray(8 * 1024)
                         var bytesRead: Int
 
@@ -291,17 +381,4 @@ class OkHttpDownloadService : DownloadService {
                 DownloadResult.Error(e)
             }
         }
-
-    /**
-     * Check if exception is retryable
-     */
-    private fun isRetryableException(e: Exception): Boolean =
-        when (e) {
-            is SocketTimeoutException,
-            is UnknownHostException,
-            is IOException,
-            -> true
-
-            else -> false
-        }
 }