@rovq/react-native 0.0.0-stage → 0.1.0

package/android/src/react/java/com/rovq/engine/react/RovqModule.kt

@@ -0,0 +1,164 @@
+package com.rovq.engine.react
+
+import android.util.Log
+import com.facebook.react.ReactApplication
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.UiThreadUtil
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.module.annotations.ReactModule
+import com.rovq.engine.CheckResult
+import com.rovq.engine.DownloadResult
+import com.rovq.engine.InstallResult
+import com.rovq.engine.RovqEngine
+import com.rovq.engine.RovqErrorCode
+import com.rovq.engine.ProgressThrottle
+import com.rovq.engine.SyncResult
+import com.rovq.engine.UpdateInfo
+import java.util.concurrent.Executors
+
+@ReactModule(name = RovqModule.NAME)
+class RovqModule(context: ReactApplicationContext) : NativeRovqSpec(context) {
+    // Network and disk work must stay off the JavaScript thread.
+    private val worker = Executors.newSingleThreadExecutor()
+
+    // A download keeps running through a reload, when this module's JavaScript has gone.
+    @Volatile
+    private var invalidated = false
+
+    override fun getName(): String = NAME
+
+    override fun checkForUpdate(promise: Promise) = run(promise) { engine ->
+        when (val result = engine.checkForUpdate()) {
+            CheckResult.UpToDate -> outcome("UP_TO_DATE")
+            CheckResult.RolledBack -> outcome("ROLLED_BACK")
+            is CheckResult.UpdateAvailable -> outcome("UPDATE_AVAILABLE").apply {
+                putMap("update", toMap(result.update))
+                putBoolean("alreadyDownloaded", result.alreadyDownloaded)
+            }
+            is CheckResult.Failed -> failure(result.code, result.message)
+        }
+    }
+
+    override fun downloadUpdate(promise: Promise) = run(promise) { engine ->
+        when (val result = engine.downloadUpdate(progressReporter())) {
+            is DownloadResult.Downloaded -> outcome("DOWNLOADED").apply { putMap("update", toMap(result.update)) }
+            is DownloadResult.Failed -> failure(result.code, result.message)
+        }
+    }
+
+    override fun installUpdate(promise: Promise) = run(promise) { engine ->
+        when (val result = engine.installUpdate()) {
+            is InstallResult.Installed -> outcome("INSTALLED").apply { putString("releaseId", result.releaseId) }
+            is InstallResult.Failed -> failure(result.code, result.message)
+        }
+    }
+
+    override fun sync(promise: Promise) = run(promise) { engine ->
+        when (val result = engine.sync(progressReporter())) {
+            SyncResult.UpToDate -> outcome("UP_TO_DATE")
+            SyncResult.RolledBack -> outcome("ROLLED_BACK")
+            is SyncResult.UpdateReady -> outcome("UPDATE_READY").apply {
+                putString("releaseId", result.releaseId)
+                putBoolean("mandatory", result.mandatory)
+            }
+            is SyncResult.Failed -> failure(result.code, result.message)
+        }
+    }
+
+    override fun notifyApplicationReady() {
+        Rovq.engineOrNull?.notifyReady()
+    }
+
+    override fun restartApp() {
+        UiThreadUtil.runOnUiThread {
+            val application = reactApplicationContext.applicationContext as ReactApplication
+            application.reactHost?.reload("ROVQ restart")
+        }
+    }
+
+    override fun rollback(promise: Promise) {
+        worker.execute {
+            try {
+                promise.resolve(Rovq.engineOrNull?.rollback() ?: false)
+            } catch (error: Exception) {
+                promise.reject("UNKNOWN", error)
+            }
+        }
+    }
+
+    override fun getStatus(promise: Promise) {
+        val status = Rovq.engineOrNull?.status()
+        promise.resolve(
+            Arguments.createMap().apply {
+                if (status != null) {
+                    putString("deviceId", status.deviceId)
+                    putString("currentReleaseId", status.currentReleaseId)
+                    putString("downloadedReleaseId", status.downloadedReleaseId)
+                    putString("pendingReleaseId", status.pendingReleaseId)
+                    putString("tryingReleaseId", status.tryingReleaseId)
+                    putDouble("highestSequence", status.highestSequence.toDouble())
+                }
+            },
+        )
+    }
+
+    private fun run(promise: Promise, work: (RovqEngine) -> WritableMap) {
+        worker.execute {
+            try {
+                val engine = Rovq.engineOrNull
+                promise.resolve(
+                    if (engine != null) {
+                        work(engine)
+                    } else {
+                        failure(RovqErrorCode.ENGINE_UNAVAILABLE, "Rovq.initialize was not called")
+                    },
+                )
+            } catch (error: Exception) {
+                promise.reject("UNKNOWN", error)
+            }
+        }
+    }
+
+    private fun progressReporter(): (Long, Long) -> Unit {
+        val throttle = ProgressThrottle { received, total ->
+            if (!invalidated) {
+                emitOnDownloadProgress(
+                    Arguments.createMap().apply {
+                        putDouble("receivedBytes", received.toDouble())
+                        putDouble("totalBytes", total.toDouble())
+                    },
+                )
+            }
+        }
+        return throttle::report
+    }
+
+    private fun outcome(name: String): WritableMap = Arguments.createMap().apply { putString("result", name) }
+
+    private fun failure(code: RovqErrorCode, message: String): WritableMap {
+        Log.w(NAME, "Failed with $code: $message")
+        return outcome("FAILED").apply {
+            putString("code", code.name)
+            putString("message", message)
+        }
+    }
+
+    private fun toMap(update: UpdateInfo): WritableMap = Arguments.createMap().apply {
+        putString("releaseId", update.releaseId)
+        putDouble("sequence", update.sequence.toDouble())
+        putBoolean("mandatory", update.mandatory)
+        putDouble("packageSize", update.packageSize.toDouble())
+    }
+
+    override fun invalidate() {
+        invalidated = true
+        worker.shutdown()
+        super.invalidate()
+    }
+
+    companion object {
+        const val NAME = "Rovq"
+    }
+}

package/android/src/react/java/com/rovq/engine/react/RovqPackage.kt

@@ -0,0 +1,26 @@
+package com.rovq.engine.react
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+/** Found by React Native autolinking. */
+class RovqPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+        if (name == RovqModule.NAME) RovqModule(reactContext) else null
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+        mapOf(
+            RovqModule.NAME to ReactModuleInfo(
+                RovqModule.NAME,
+                RovqModule::class.java.name,
+                false,
+                false,
+                false,
+                true,
+            ),
+        )
+    }
+}

package/android/src/react/java/com/rovq/engine/react/RovqReactHost.kt

@@ -0,0 +1,74 @@
+package com.rovq.engine.react
+
+import android.app.Application
+import android.util.Log
+import com.facebook.react.ReactHost
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.JSBundleLoader
+import com.facebook.react.bridge.JSBundleLoaderDelegate
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
+import com.facebook.react.common.build.ReactBuildConfig
+import com.facebook.react.defaults.DefaultComponentsRegistry
+import com.facebook.react.defaults.DefaultReactHostDelegate
+import com.facebook.react.defaults.DefaultTurboModuleManagerDelegate
+import com.facebook.react.fabric.ComponentFactory
+import com.facebook.react.runtime.ReactHostImpl
+import com.facebook.react.runtime.hermes.HermesInstance
+
+private const val TAG = "Rovq"
+private const val EMBEDDED_BUNDLE = "assets://index.android.bundle"
+
+/**
+ * Chooses the bundle each time JavaScript starts, not once when the host is created.
+ * This is what lets reload apply an update without killing the process.
+ */
+private class RovqBundleLoader(private val application: Application) : JSBundleLoader() {
+    override fun loadScript(delegate: JSBundleLoaderDelegate): String {
+        val file = try {
+            Rovq.engine.resolveBundle()
+        } catch (error: Throwable) {
+            // Whatever goes wrong in the engine, the app must still start.
+            Log.e(TAG, "Falling back to the bundle inside the app", error)
+            null
+        }
+        if (file == null) {
+            Log.i(TAG, "Loading the bundle inside the app")
+            delegate.loadScriptFromAssets(application.assets, EMBEDDED_BUNDLE, true)
+            return EMBEDDED_BUNDLE
+        }
+        Log.i(TAG, "Loading ${file.absolutePath}")
+        delegate.loadScriptFromFile(file.absolutePath, file.absolutePath, false)
+        return file.absolutePath
+    }
+}
+
+/**
+ * The only file that touches React Native's unstable host API. It does what
+ * getDefaultReactHost does, with a different loader, so check it against that function
+ * when upgrading React Native. See docs/android-bundle-loading.md.
+ */
+@OptIn(UnstableReactNativeAPI::class)
+object RovqReactHost {
+    /** Use in place of getDefaultReactHost in MainApplication. */
+    fun create(application: Application, packages: List<ReactPackage>): ReactHost {
+        val componentFactory = ComponentFactory()
+        DefaultComponentsRegistry.register(componentFactory)
+        val delegate = DefaultReactHostDelegate(
+            jsMainModulePath = "index",
+            jsBundleLoader = RovqBundleLoader(application),
+            reactPackages = packages,
+            jsRuntimeFactory = HermesInstance(),
+            turboModuleManagerDelegateBuilder = DefaultTurboModuleManagerDelegate.Builder(),
+            // Letting a fatal JavaScript error kill the process is what makes rollback work:
+            // the release stays unconfirmed, so the next start abandons it.
+            exceptionHandler = { error -> throw error },
+        )
+        return ReactHostImpl(
+            application.applicationContext,
+            delegate,
+            componentFactory,
+            true,
+            ReactBuildConfig.DEBUG,
+        )
+    }
+}

package/ios/Engine/EngineState.swift

@@ -0,0 +1,119 @@
+import Foundation
+
+/// A release on the device, identified by its folder name and its signed sequence.
+public struct ReleaseRef: Codable, Equatable {
+    public let id: String
+    public let sequence: Int64
+}
+
+/// Waiting to be sent to the server. Device events are retried, so each has its own ID.
+public struct QueuedEvent: Codable, Equatable {
+    public let clientEventId: String
+    public let type: String
+    public let releaseId: String?
+    public let errorCode: String?
+    public let occurredAt: String
+}
+
+/// A release that failed its checks after downloading, and when it may be tried again.
+struct PostponedDownload: Codable, Equatable {
+    let releaseId: String
+    let attempts: Int
+    let until: TimeInterval
+}
+
+/// Everything the engine must remember across process deaths. It holds IDs and never full
+/// paths, because iOS moves an app's container whenever the app is updated.
+///
+/// A release moves from `downloaded` to `pending` to `trying` to `current`:
+/// - `downloaded`: verified and on disk, but nothing will load it until the app installs it.
+/// - `pending`: installed, and loads on the next JavaScript start.
+/// - `trying`: being loaded right now. If the next start finds it still here, it never
+///   confirmed that it works, so it is abandoned.
+/// - `current`: confirmed to work.
+/// - `previous`: the confirmed release before `current`, kept to go back to.
+struct EngineState: Codable, Equatable {
+    var deviceId: String
+    var binaryId: String
+    var runtimeVersion: String
+    var highestSequence: Int64 = 0
+    var current: ReleaseRef?
+    var previous: ReleaseRef?
+    var downloaded: ReleaseRef?
+    var pending: ReleaseRef?
+    var trying: ReleaseRef?
+    /// True if the app went to the background while `trying`, so a person probably closed it.
+    var backgroundedWhileTrying = false
+    /// How many more starts `trying` was given because it was closed before confirming.
+    var tryingRetries = 0
+    var postponed: PostponedDownload?
+    var revokedPublicKeys: Set<String> = []
+    var events: [QueuedEvent] = []
+
+    enum CodingKeys: String, CodingKey {
+        case deviceId, binaryId, runtimeVersion, highestSequence, current, previous, downloaded
+        case pending, trying, backgroundedWhileTrying, tryingRetries, postponed, revokedPublicKeys
+        case events
+    }
+
+    init(deviceId: String, binaryId: String, runtimeVersion: String) {
+        self.deviceId = deviceId
+        self.binaryId = binaryId
+        self.runtimeVersion = runtimeVersion
+    }
+
+    /// Fields added after the first version are optional, so an older saved state still loads.
+    init(from decoder: Decoder) throws {
+        let values = try decoder.container(keyedBy: CodingKeys.self)
+        deviceId = try values.decode(String.self, forKey: .deviceId)
+        binaryId = try values.decode(String.self, forKey: .binaryId)
+        runtimeVersion = try values.decode(String.self, forKey: .runtimeVersion)
+        highestSequence = try values.decode(Int64.self, forKey: .highestSequence)
+        current = try values.decodeIfPresent(ReleaseRef.self, forKey: .current)
+        previous = try values.decodeIfPresent(ReleaseRef.self, forKey: .previous)
+        downloaded = try values.decodeIfPresent(ReleaseRef.self, forKey: .downloaded)
+        pending = try values.decodeIfPresent(ReleaseRef.self, forKey: .pending)
+        trying = try values.decodeIfPresent(ReleaseRef.self, forKey: .trying)
+        backgroundedWhileTrying =
+            try values.decodeIfPresent(Bool.self, forKey: .backgroundedWhileTrying) ?? false
+        tryingRetries = try values.decodeIfPresent(Int.self, forKey: .tryingRetries) ?? 0
+        postponed = try values.decodeIfPresent(PostponedDownload.self, forKey: .postponed)
+        revokedPublicKeys =
+            try values.decodeIfPresent(Set<String>.self, forKey: .revokedPublicKeys) ?? []
+        events = try values.decode([QueuedEvent].self, forKey: .events)
+    }
+}
+
+/// Saves the state so that a crash at any moment leaves either the old state or the new one,
+/// never a mixture. The app's first screen depends on this file being readable.
+struct EngineStateStore {
+    private let file: URL
+    private let temporary: URL
+
+    init(rootFolder: URL) {
+        file = rootFolder.appendingPathComponent("state.json")
+        temporary = rootFolder.appendingPathComponent("state.json.tmp")
+    }
+
+    /// Returns nil if there is no state, or if it is unreadable.
+    func read() -> EngineState? {
+        guard let data = try? Data(contentsOf: file) else { return nil }
+        return try? JSONDecoder().decode(EngineState.self, from: data)
+    }
+
+    func write(_ state: EngineState) throws {
+        // Writing to another file first means a crash cannot leave a half-written state.
+        let data = try JSONEncoder().encode(state)
+        guard FileManager.default.createFile(atPath: temporary.path, contents: nil) else {
+            throw RovqError(.storageFailed, "Could not save the engine state")
+        }
+        let handle = try FileHandle(forWritingTo: temporary)
+        defer { try? handle.close() }
+        try handle.write(contentsOf: data)
+        try handle.synchronize()
+        // POSIX rename replaces the old file atomically.
+        guard rename(temporary.path, file.path) == 0 else {
+            throw RovqError(.storageFailed, "Could not save the engine state")
+        }
+    }
+}

package/ios/Engine/ManifestVerifier.swift

@@ -0,0 +1,197 @@
+import CryptoKit
+import Foundation
+
+private let publicKeySize = 32
+private let signatureSize = 64
+private let manifestVersion: Int64 = 1
+private let platform = "IOS"
+private let manifestFields: Set<String> = [
+    "version", "releaseId", "deploymentKey", "platform", "runtimeVersion", "binaryVersion",
+    "sequence", "mandatory", "package",
+]
+private let packageFields: Set<String> = ["hash", "size"]
+private let uuidPattern = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+private let hashPattern = "^[0-9a-f]{64}$"
+
+/// Facts from a manifest whose signature has been verified. Nothing else should be trusted.
+public struct VerifiedManifest: Equatable {
+    public let releaseId: String
+    public let sequence: Int64
+    public let mandatory: Bool
+    public let packageHash: String
+    public let packageSize: Int64
+}
+
+/// Decodes standard Base64, accepting only one spelling of each value, as the server does.
+func decodeStrictBase64(_ value: String, expectedSize: Int) -> Data? {
+    guard let data = Data(base64Encoded: value), data.count == expectedSize,
+        data.base64EncodedString() == value
+    else { return nil }
+    return data
+}
+
+/// The device's own security check. It trusts only the public keys built into the app, so
+/// a compromised server cannot get code onto the device.
+public final class ManifestVerifier {
+    private let keys: [String: Curve25519.Signing.PublicKey]
+    private let trustedKeys: [String: String]
+    private let revokedLock = NSLock()
+    private var revoked: Set<String> = []
+    private let deploymentKey: String
+    private let runtimeVersion: String
+
+    /// - Parameter trustedKeys: key IDs and their Base64 Ed25519 public keys, built into the app.
+    /// - Throws: if a built-in key is malformed, which is a mistake in the app itself.
+    public init(trustedKeys: [String: String], deploymentKey: String, runtimeVersion: String) throws {
+        keys = try trustedKeys.mapValues { publicKey in
+            guard let bytes = decodeStrictBase64(publicKey, expectedSize: publicKeySize) else {
+                throw RovqError(.invalidManifest, "A built-in public key is not a Base64 Ed25519 key")
+            }
+            return try Curve25519.Signing.PublicKey(rawRepresentation: bytes)
+        }
+        self.trustedKeys = trustedKeys
+        self.deploymentKey = deploymentKey
+        self.runtimeVersion = runtimeVersion
+    }
+
+    /// Public keys, not IDs, so a later version of the app can reuse an ID with a new key.
+    public var revokedPublicKeys: Set<String> {
+        get {
+            revokedLock.lock()
+            defer { revokedLock.unlock() }
+            return revoked
+        }
+        set {
+            revokedLock.lock()
+            defer { revokedLock.unlock() }
+            revoked = newValue
+        }
+    }
+
+    /// Checks a key's statement that it must no longer be trusted, and returns its public key.
+    /// Only the key's own signature counts, so a stolen key can revoke only itself. Comparing the
+    /// exact text means nothing unsigned reaches a parser.
+    ///
+    /// - Returns: nil if the statement is not valid, in which case it must be ignored.
+    public func verifyRevocation(keyId: String, statement: String, signature: String) -> String? {
+        guard let publicKey = trustedKeys[keyId],
+            statement == "{\"version\":1,\"type\":\"key-revocation\",\"publicKey\":\"\(publicKey)\"}",
+            (try? verifySignature(manifest: statement, signature: signature, keyId: keyId)) != nil
+        else { return nil }
+        return publicKey
+    }
+
+    /// - Parameter highestSequence: the highest sequence this device has accepted in this stream.
+    /// - Throws: `RovqError` if anything fails. The device must then ignore the update.
+    public func verify(
+        manifest: String,
+        signature: String,
+        keyId: String,
+        highestSequence: Int64
+    ) throws -> VerifiedManifest {
+        if let publicKey = trustedKeys[keyId], revokedPublicKeys.contains(publicKey) {
+            throw RovqError(.revokedSigningKey, "Signing key \(keyId) was revoked")
+        }
+        try verifySignature(manifest: manifest, signature: signature, keyId: keyId)
+        // Only signed text reaches the JSON parser.
+        let verified = try parseAndCheck(manifest)
+        if verified.sequence <= highestSequence {
+            throw RovqError(.staleSequence, "Sequence \(verified.sequence) is not above \(highestSequence)")
+        }
+        return verified
+    }
+
+    private func verifySignature(manifest: String, signature: String, keyId: String) throws {
+        guard let key = keys[keyId] else {
+            throw RovqError(.unknownSigningKey, "Unknown signing key \(keyId)")
+        }
+        guard let bytes = decodeStrictBase64(signature, expectedSize: signatureSize) else {
+            throw RovqError(.invalidSignature, "Malformed signature")
+        }
+        guard key.isValidSignature(bytes, for: Data(manifest.utf8)) else {
+            throw RovqError(.invalidSignature, "Signature does not match")
+        }
+    }
+
+    private func parseAndCheck(_ manifest: String) throws -> VerifiedManifest {
+        let parsed = try? JSONSerialization.jsonObject(with: Data(manifest.utf8))
+        guard let root = parsed as? [String: Any] else {
+            throw invalid("Manifest is not a JSON object")
+        }
+        try requireOnlyFields(root, allowed: manifestFields)
+        guard try integerField(root, "version") == manifestVersion else {
+            throw invalid("Unknown manifest version")
+        }
+
+        let releaseId = try stringField(root, "releaseId")
+        // Later used as a folder name, so it must be exactly a UUID.
+        guard matches(releaseId, uuidPattern) else { throw invalid("releaseId is not a UUID") }
+
+        let sequence = try integerField(root, "sequence")
+        guard sequence > 0 else { throw invalid("sequence must be positive") }
+
+        guard let mandatoryNumber = root["mandatory"] as? NSNumber, isBoolean(mandatoryNumber) else {
+            throw invalid("mandatory must be a boolean")
+        }
+        _ = try stringField(root, "binaryVersion")
+
+        guard let package = root["package"] as? [String: Any] else {
+            throw invalid("package must be an object")
+        }
+        try requireOnlyFields(package, allowed: packageFields)
+        let hash = try stringField(package, "hash")
+        guard matches(hash, hashPattern) else { throw invalid("package hash is malformed") }
+        let size = try integerField(package, "size")
+        guard size > 0 else { throw invalid("package size must be positive") }
+
+        // A valid signature for another deployment, platform or runtime must not install here.
+        try requireMatch("deploymentKey", try stringField(root, "deploymentKey"), deploymentKey)
+        try requireMatch("platform", try stringField(root, "platform"), platform)
+        try requireMatch("runtimeVersion", try stringField(root, "runtimeVersion"), runtimeVersion)
+
+        return VerifiedManifest(
+            releaseId: releaseId,
+            sequence: sequence,
+            mandatory: mandatoryNumber.boolValue,
+            packageHash: hash,
+            packageSize: size
+        )
+    }
+
+    private func matches(_ value: String, _ pattern: String) -> Bool {
+        value.range(of: pattern, options: .regularExpression) != nil
+    }
+
+    private func requireOnlyFields(_ value: [String: Any], allowed: Set<String>) throws {
+        if let unknown = value.keys.first(where: { !allowed.contains($0) }) {
+            throw invalid("Unknown field \(unknown)")
+        }
+    }
+
+    private func stringField(_ value: [String: Any], _ name: String) throws -> String {
+        guard let text = value[name] as? String else { throw invalid("\(name) must be a string") }
+        return text
+    }
+
+    // JSON numbers and booleans both arrive as NSNumber, so they must be told apart.
+    private func integerField(_ value: [String: Any], _ name: String) throws -> Int64 {
+        guard let number = value[name] as? NSNumber, !isBoolean(number),
+            number.doubleValue == Double(number.int64Value)
+        else { throw invalid("\(name) must be a whole number") }
+        return number.int64Value
+    }
+
+    private func isBoolean(_ number: NSNumber) -> Bool {
+        CFGetTypeID(number) == CFBooleanGetTypeID()
+    }
+
+    private func requireMatch(_ name: String, _ actual: String, _ expected: String) throws {
+        if actual != expected {
+            throw RovqError(.manifestMismatch, "\(name) does not match this app")
+        }
+    }
+
+    private func invalid(_ message: String) -> RovqError {
+        RovqError(.invalidManifest, message)
+    }
+}