@rovq/react-native 0.0.0-stage → 0.2.0

package/android/src/main/java/com/rovq/engine/RovqEngine.kt

@@ -0,0 +1,550 @@
+package com.rovq.engine
+
+import java.io.File
+import java.io.IOException
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import java.util.UUID
+
+private const val MAX_QUEUED_EVENTS = 200
+private const val EVENT_BATCH_SIZE = 50
+
+// A release closed before confirming gets this many more starts. A crash gets none.
+private const val MAX_TRYING_RETRIES = 2
+
+private const val FIRST_POSTPONE_MILLIS = 60 * 60 * 1000L
+private const val MAX_POSTPONE_MILLIS = 24 * 60 * 60 * 1000L
+private const val MAX_DOUBLINGS = 5
+
+// The same file failed its checks, so downloading it again would likely waste data for nothing.
+// A network failure is not here, because trying again can work.
+private val POSTPONED_CODES = setOf(
+    RovqErrorCode.SIZE_MISMATCH,
+    RovqErrorCode.HASH_MISMATCH,
+    RovqErrorCode.INVALID_PACKAGE,
+)
+
+/**
+ * @param binaryId changes whenever the app itself is installed or updated from a store.
+ * @param trustedKeys key IDs and their Base64 public keys, built into the app.
+ */
+data class EngineConfig(
+    val apiUrl: String,
+    val deploymentKey: String,
+    val runtimeVersion: String,
+    val binaryVersion: String,
+    val binaryId: String,
+    val trustedKeys: Map<String, String>,
+    val allowInsecureUrls: Boolean = false,
+)
+
+/** Facts about an update, all from a manifest whose signature has been verified. */
+data class UpdateInfo(
+    val releaseId: String,
+    val sequence: Long,
+    val mandatory: Boolean,
+    val packageSize: Long,
+)
+
+sealed interface CheckResult {
+    data object UpToDate : CheckResult
+
+    /** @param alreadyDownloaded whether [RovqEngine.downloadUpdate] has nothing left to fetch. */
+    data class UpdateAvailable(val update: UpdateInfo, val alreadyDownloaded: Boolean) : CheckResult
+
+    /** The server asked to leave the current release. Restart to apply. */
+    data object RolledBack : CheckResult
+
+    data class Failed(val code: RovqErrorCode, val message: String) : CheckResult
+}
+
+sealed interface DownloadResult {
+    /** Verified and on disk. It loads only after [RovqEngine.installUpdate]. */
+    data class Downloaded(val update: UpdateInfo) : DownloadResult
+
+    data class Failed(val code: RovqErrorCode, val message: String) : DownloadResult
+}
+
+sealed interface InstallResult {
+    /** Loads on the next JavaScript start. */
+    data class Installed(val releaseId: String) : InstallResult
+
+    data class Failed(val code: RovqErrorCode, val message: String) : InstallResult
+}
+
+sealed interface SyncResult {
+    data object UpToDate : SyncResult
+
+    /** Installed, and loads on the next JavaScript start. */
+    data class UpdateReady(val releaseId: String, val mandatory: Boolean) : SyncResult
+
+    /** The server asked to leave the current release. Restart to apply. */
+    data object RolledBack : SyncResult
+
+    data class Failed(val code: RovqErrorCode, val message: String) : SyncResult
+}
+
+data class EngineStatus(
+    val deviceId: String,
+    val currentReleaseId: String?,
+    val downloadedReleaseId: String?,
+    val pendingReleaseId: String?,
+    val tryingReleaseId: String?,
+    val highestSequence: Long,
+)
+
+/**
+ * The state machine that decides which bundle runs. A wrong decision here can stop an
+ * app from starting, so every change is saved before it takes effect, and each method
+ * is written so that the process can die at any line.
+ */
+class RovqEngine(
+    private val rootDir: File,
+    private val config: EngineConfig,
+    private val service: UpdateService = HttpUpdateService(config.apiUrl, config.allowInsecureUrls),
+    /** The app's own assets, which a release made of files reuses instead of downloading. */
+    builtInFiles: BuiltInFiles? = null,
+    private val clock: () -> Long = System::currentTimeMillis,
+) {
+    private val store: EngineStateStore
+    private val updatesDir = File(rootDir, "updates")
+    private val verifier = ManifestVerifier(config.trustedKeys, config.deploymentKey, config.runtimeVersion)
+    private val installer: UpdateInstaller
+
+    // Held for a whole check, download or install, because each depends on the one before.
+    private val syncLock = Any()
+
+    // Kept in memory only, because its download URL expires. Guarded by syncLock.
+    private var offer: OfferedUpdate? = null
+    private var offerManifest: VerifiedManifest? = null
+    private var state: EngineState
+
+    init {
+        rootDir.mkdirs()
+        store = EngineStateStore(rootDir)
+        installer = UpdateInstaller(
+            rootDir,
+            verifier,
+            PackageDownloader(config.allowInsecureUrls),
+            builtInFiles,
+        )
+        state = loadState()
+        verifier.revokedPublicKeys = state.revokedPublicKeys
+    }
+
+    /**
+     * Called each time JavaScript starts, before it loads. Returns the bundle to run, or
+     * null for the one inside the app. It must never throw, or the app could not start.
+     */
+    @Synchronized
+    fun resolveBundle(): File? {
+        // Still marked as trying means the last start never confirmed that it works.
+        state.trying?.let { failed ->
+            // A crash does not pass through the background, but closing the app does, so this
+            // start was probably cut short by a person, and the release deserves another one.
+            if (state.backgroundedWhileTrying && state.tryingRetries < MAX_TRYING_RETRIES && bundleOf(failed).isFile) {
+                val retry = state.copy(backgroundedWhileTrying = false, tryingRetries = state.tryingRetries + 1)
+                if (save(retry)) return bundleOf(failed)
+            }
+            save(
+                queue(
+                    state.copy(trying = null, backgroundedWhileTrying = false, tryingRetries = 0),
+                    "ROLLED_BACK",
+                    failed.id,
+                    "NOT_CONFIRMED",
+                ),
+            )
+        }
+        state.pending?.let { next ->
+            if (!bundleOf(next).isFile) {
+                save(state.copy(pending = null))
+            } else if (save(state.copy(pending = null, trying = next))) {
+                // Saved first, so that if this bundle kills the process the next start knows.
+                removeUnusedReleases()
+                return bundleOf(next)
+            } else {
+                // Trying it unrecorded could crash on every start forever, so run what is
+                // known to work. The update stays pending for when saving works again.
+                state = state.copy(pending = next, trying = null)
+                return state.current?.let(::bundleOf)?.takeIf { it.isFile }
+            }
+        }
+
+        // A confirmed release can only disappear through outside interference.
+        state.current?.let { current ->
+            if (!bundleOf(current).isFile) save(state.copy(current = state.previous, previous = null))
+        }
+        val running = state.current?.takeIf { bundleOf(it).isFile }
+        if (running == null && state.current != null) save(state.copy(current = null, previous = null))
+        removeUnusedReleases()
+        return running?.let(::bundleOf)
+    }
+
+    /** Called when the app goes to the background. See [resolveBundle]. */
+    @Synchronized
+    fun noteBackgrounded() {
+        if (state.trying != null && !state.backgroundedWhileTrying) {
+            save(state.copy(backgroundedWhileTrying = true))
+        }
+    }
+
+    /**
+     * Called when the app is crashing. Android can stop the activity while its crash dialog shows,
+     * which looks like going to the background, so this uses up the release's other starts first.
+     */
+    @Synchronized
+    fun noteCrashed() {
+        if (state.trying != null) {
+            save(state.copy(backgroundedWhileTrying = false, tryingRetries = MAX_TRYING_RETRIES))
+        }
+    }
+
+    /** Called by the app once it has started properly. It keeps the running release. */
+    @Synchronized
+    fun notifyReady() {
+        val confirmed = state.trying ?: return
+        save(
+            queue(
+                state.copy(
+                    trying = null,
+                    current = confirmed,
+                    previous = state.current,
+                    backgroundedWhileTrying = false,
+                    tryingRetries = 0,
+                ),
+                "CONFIRMED",
+                confirmed.id,
+                null,
+            ),
+        )
+    }
+
+    /**
+     * Goes back to the previous confirmed release, or to the one inside the app. It takes
+     * effect on the next JavaScript start. The sequence stays, so the release that was
+     * left is not offered again.
+     *
+     * @return whether there was anything to leave.
+     */
+    @Synchronized
+    fun rollback(reason: String = "REQUESTED"): Boolean {
+        val leaving = state.trying ?: state.current ?: return false
+        val next = if (state.trying != null) state.current else state.previous
+        val previous = if (state.trying != null) state.previous else null
+        save(
+            queue(
+                state.copy(
+                    trying = null,
+                    current = next,
+                    previous = previous,
+                    backgroundedWhileTrying = false,
+                    tryingRetries = 0,
+                ),
+                "ROLLED_BACK",
+                leaving.id,
+                reason,
+            ),
+        )
+        return true
+    }
+
+    /**
+     * Asks the server for updates, and verifies any offer before reporting it, so an app never
+     * shows the user an update that it would refuse to download.
+     *
+     * A rollback from the server applies here, because it is how a bad release gets stopped,
+     * and that must not depend on what the app does with the answer.
+     */
+    fun checkForUpdate(): CheckResult = synchronized(syncLock) {
+        val result = checkOnce()
+        flushEvents()
+        result
+    }
+
+    /** Fetches the update found by the last [checkForUpdate], without activating it. */
+    fun downloadUpdate(onProgress: (received: Long, total: Long) -> Unit = { _, _ -> }): DownloadResult =
+        synchronized(syncLock) {
+            val result = downloadOnce(onProgress)
+            flushEvents()
+            result
+        }
+
+    /**
+     * Makes the downloaded update load on the next JavaScript start. It uses no network, so
+     * an app can restart straight after it. Its event goes with the next check.
+     */
+    fun installUpdate(): InstallResult = synchronized(syncLock) { installOnce() }
+
+    /** The three steps together, for an app that does not need to ask the user in between. */
+    fun sync(onProgress: (received: Long, total: Long) -> Unit = { _, _ -> }): SyncResult =
+        synchronized(syncLock) {
+            val result = syncOnce(onProgress)
+            flushEvents()
+            result
+        }
+
+    @Synchronized
+    fun status(): EngineStatus = EngineStatus(
+        deviceId = state.deviceId,
+        currentReleaseId = (state.trying ?: state.current)?.id,
+        downloadedReleaseId = state.downloaded?.id,
+        pendingReleaseId = state.pending?.id,
+        tryingReleaseId = state.trying?.id,
+        highestSequence = state.highestSequence,
+    )
+
+    private fun syncOnce(onProgress: (Long, Long) -> Unit): SyncResult {
+        val update = when (val checked = checkOnce()) {
+            CheckResult.UpToDate -> return SyncResult.UpToDate
+            CheckResult.RolledBack -> return SyncResult.RolledBack
+            is CheckResult.Failed -> return SyncResult.Failed(checked.code, checked.message)
+            is CheckResult.UpdateAvailable -> checked.update
+        }
+        val downloaded = downloadOnce(onProgress)
+        if (downloaded is DownloadResult.Failed) return SyncResult.Failed(downloaded.code, downloaded.message)
+        return when (val installed = installOnce()) {
+            is InstallResult.Installed -> SyncResult.UpdateReady(update.releaseId, update.mandatory)
+            is InstallResult.Failed -> SyncResult.Failed(installed.code, installed.message)
+        }
+    }
+
+    private fun checkOnce(): CheckResult {
+        offer = null
+        offerManifest = null
+        val request = synchronized(this) {
+            CheckRequest(
+                deploymentKey = config.deploymentKey,
+                deviceId = state.deviceId,
+                runtimeVersion = config.runtimeVersion,
+                binaryVersion = config.binaryVersion,
+                currentReleaseId = (state.trying ?: state.current)?.id,
+                highestSequence = state.highestSequence,
+            )
+        }
+        val answer = try {
+            service.check(request)
+        } catch (error: IOException) {
+            return CheckResult.Failed(RovqErrorCode.DOWNLOAD_FAILED, error.message ?: "Network failure")
+        }
+        // First, so that an offer signed by a key revoked in this same answer is refused.
+        applyRevocations(answer.revocations)
+        return when (val response = answer.response) {
+            CheckResponse.None -> {
+                keepDownloadedOnlyIf(null)
+                CheckResult.UpToDate
+            }
+            CheckResponse.Rollback -> {
+                keepDownloadedOnlyIf(null)
+                if (rollback("DISABLED_ON_SERVER")) CheckResult.RolledBack else CheckResult.UpToDate
+            }
+            is CheckResponse.Update -> verifyOffer(response.offer, request.highestSequence)
+        }
+    }
+
+    /** Permanent, so a server compromised later cannot make this device trust the key again. */
+    private fun applyRevocations(revocations: List<KeyRevocation>) {
+        val valid = revocations.mapNotNull { verifier.verifyRevocation(it.keyId, it.statement, it.signature) }
+        if (valid.isEmpty()) return
+        synchronized(this) {
+            val all = state.revokedPublicKeys + valid
+            if (all == state.revokedPublicKeys) return
+            // A downloaded release may have been signed with that key, and nothing checks it again.
+            save(state.copy(revokedPublicKeys = all, downloaded = null))
+            verifier.revokedPublicKeys = all
+        }
+    }
+
+    private fun verifyOffer(offered: OfferedUpdate, highestSequence: Long): CheckResult = try {
+        val manifest = verifier.verify(offered.manifest, offered.signature, offered.keyId, highestSequence)
+        offer = offered
+        offerManifest = manifest
+        keepDownloadedOnlyIf(manifest.releaseId)
+        val alreadyDownloaded = synchronized(this) { state.downloaded != null }
+        CheckResult.UpdateAvailable(manifest.toUpdateInfo(), alreadyDownloaded)
+    } catch (error: RovqException) {
+        recordFailure(error)
+        CheckResult.Failed(error.code, error.message ?: error.code.name)
+    }
+
+    /**
+     * The server offers a release until the device installs it, so an answer that does not
+     * include the downloaded release means it was disabled or replaced, and must not be
+     * installed. A failed check says nothing about it, so that does not get here.
+     */
+    private fun keepDownloadedOnlyIf(offeredReleaseId: String?) = synchronized(this) {
+        val downloaded = state.downloaded
+        if (downloaded != null && downloaded.id != offeredReleaseId) save(state.copy(downloaded = null))
+    }
+
+    private fun downloadOnce(onProgress: (Long, Long) -> Unit): DownloadResult {
+        val offered = offer ?: return DownloadResult.Failed(
+            RovqErrorCode.NO_UPDATE_AVAILABLE,
+            "No update to download. Check for updates first",
+        )
+        val releaseId = offerManifest?.releaseId
+        val highestSequence = synchronized(this) {
+            val postponed = state.postponed
+            // A clock moved back must not make the wait longer than the longest one allowed.
+            if (postponed?.releaseId == releaseId && postponed != null) {
+                val remaining = postponed.untilMillis - clock()
+                if (remaining in 1..MAX_POSTPONE_MILLIS) {
+                    return DownloadResult.Failed(
+                        RovqErrorCode.DOWNLOAD_POSTPONED,
+                        "This update failed its checks, so it will not be downloaded again yet",
+                    )
+                }
+            }
+            state.highestSequence
+        }
+        return try {
+            val deviceId = synchronized(this) { state.deviceId }
+            val links = FileLinks { releaseId, hashes ->
+                service.fileLinks(config.deploymentKey, deviceId, releaseId, hashes)
+            }
+            val manifest = installer.install(offered, highestSequence, links, onProgress).manifest
+            synchronized(this) {
+                save(
+                    state.copy(
+                        downloaded = ReleaseRef(manifest.releaseId, manifest.sequence),
+                        postponed = null,
+                    ),
+                )
+            }
+            DownloadResult.Downloaded(manifest.toUpdateInfo())
+        } catch (error: RovqException) {
+            recordFailure(error)
+            if (error.code in POSTPONED_CODES && releaseId != null) postpone(releaseId)
+            DownloadResult.Failed(error.code, error.message ?: error.code.name)
+        }
+    }
+
+    private fun postpone(releaseId: String) = synchronized(this) {
+        val attempts = if (state.postponed?.releaseId == releaseId) state.postponed!!.attempts + 1 else 1
+        val wait = (FIRST_POSTPONE_MILLIS shl (attempts - 1).coerceAtMost(MAX_DOUBLINGS))
+            .coerceAtMost(MAX_POSTPONE_MILLIS)
+        save(state.copy(postponed = PostponedDownload(releaseId, attempts, clock() + wait)))
+    }
+
+    private fun installOnce(): InstallResult = synchronized(this) {
+        val downloaded = state.downloaded?.takeIf { bundleOf(it).isFile }
+        if (downloaded == null) {
+            if (state.downloaded != null) save(state.copy(downloaded = null))
+            return InstallResult.Failed(RovqErrorCode.NO_UPDATE_DOWNLOADED, "No update has been downloaded")
+        }
+        offer = null
+        offerManifest = null
+        save(
+            queue(
+                state.copy(
+                    downloaded = null,
+                    pending = downloaded,
+                    // Recorded now, so a release that later fails is never accepted again.
+                    highestSequence = maxOf(state.highestSequence, downloaded.sequence),
+                ),
+                "INSTALLED",
+                downloaded.id,
+                null,
+            ),
+        )
+        InstallResult.Installed(downloaded.id)
+    }
+
+    private fun recordFailure(error: RovqException) {
+        val type = if (error.code == RovqErrorCode.DOWNLOAD_FAILED) "DOWNLOAD_FAILED" else "VERIFICATION_FAILED"
+        synchronized(this) { save(queue(state, type, null, error.code.name)) }
+    }
+
+    private fun VerifiedManifest.toUpdateInfo() = UpdateInfo(releaseId, sequence, mandatory, packageSize)
+
+    /** Best effort. Events stay queued and go with a later sync if this fails. */
+    private fun flushEvents() {
+        val (batch, deviceId) = synchronized(this) { state.events.take(EVENT_BATCH_SIZE) to state.deviceId }
+        if (batch.isEmpty()) return
+        try {
+            service.report(config.deploymentKey, deviceId, batch)
+        } catch (error: IOException) {
+            return
+        }
+        val sent = batch.map { it.clientEventId }.toSet()
+        synchronized(this) {
+            save(state.copy(events = state.events.filterNot { it.clientEventId in sent }))
+        }
+    }
+
+    private fun loadState(): EngineState {
+        val saved = store.read()
+        val fresh = EngineState(
+            deviceId = saved?.deviceId ?: UUID.randomUUID().toString(),
+            binaryId = config.binaryId,
+            runtimeVersion = config.runtimeVersion,
+        )
+        if (saved == null) {
+            // Without a readable state nothing on disk can be trusted, so start clean.
+            updatesDir.deleteRecursively()
+            trySave(fresh)
+            return fresh
+        }
+        if (saved.binaryId == config.binaryId && saved.runtimeVersion == config.runtimeVersion) {
+            return saved
+        }
+        // A new app from the store is newer than any update for the old one, and the old
+        // bundles may not work with its native code. Sequences belong to a runtime version,
+        // so the count only carries over if that did not change.
+        updatesDir.deleteRecursively()
+        val reset = fresh.copy(
+            highestSequence = if (saved.runtimeVersion == config.runtimeVersion) saved.highestSequence else 0,
+            events = saved.events,
+            // Revocation is permanent, whatever the version of the app.
+            revokedPublicKeys = saved.revokedPublicKeys,
+        )
+        trySave(reset)
+        return reset
+    }
+
+    private fun bundleOf(release: ReleaseRef) =
+        File(File(updatesDir, release.id), PackageRules.BUNDLE_FILE_NAME)
+
+    private fun removeUnusedReleases() {
+        val inUse = listOfNotNull(state.current, state.previous, state.downloaded, state.pending, state.trying)
+            .map { it.id }
+            .toSet()
+        updatesDir.listFiles()?.forEach { folder ->
+            if (folder.name !in inUse) folder.deleteRecursively()
+        }
+    }
+
+    private fun queue(
+        base: EngineState,
+        type: String,
+        releaseId: String?,
+        errorCode: String?,
+    ): EngineState {
+        val event = QueuedEvent(UUID.randomUUID().toString(), type, releaseId, errorCode, now())
+        return base.copy(events = (base.events + event).takeLast(MAX_QUEUED_EVENTS))
+    }
+
+    /** @return whether the change will survive a process death. */
+    private fun save(next: EngineState): Boolean {
+        state = next
+        return trySave(next)
+    }
+
+    /**
+     * A failed save must not stop the app, for example when the disk is full. In general
+     * the state from before the change applies on the next start. Callers that depend on
+     * the change surviving must check the result.
+     */
+    private fun trySave(next: EngineState): Boolean = try {
+        store.write(next)
+        true
+    } catch (error: IOException) {
+        false
+    }
+
+    private fun now(): String =
+        SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.ROOT)
+            .apply { timeZone = TimeZone.getTimeZone("UTC") }
+            .format(Date())
+}

package/android/src/main/java/com/rovq/engine/RovqException.kt

@@ -0,0 +1,31 @@
+package com.rovq.engine
+
+/**
+ * Why an update failed. The names are also sent to the server as device event error codes,
+ * except for the last four, which describe the app's use of the engine. The React Native
+ * SDK has the same list, and a test keeps them equal.
+ */
+enum class RovqErrorCode {
+    UNKNOWN_SIGNING_KEY,
+    REVOKED_SIGNING_KEY,
+    INVALID_SIGNATURE,
+    INVALID_MANIFEST,
+    MANIFEST_MISMATCH,
+    STALE_SEQUENCE,
+    INSECURE_URL,
+    DOWNLOAD_FAILED,
+    SIZE_MISMATCH,
+    HASH_MISMATCH,
+    INVALID_PACKAGE,
+    STORAGE_FAILED,
+    NO_UPDATE_AVAILABLE,
+    NO_UPDATE_DOWNLOADED,
+    ENGINE_UNAVAILABLE,
+    DOWNLOAD_POSTPONED,
+}
+
+class RovqException(
+    val code: RovqErrorCode,
+    message: String,
+    cause: Throwable? = null,
+) : Exception(message, cause)