@rovq/react-native 0.0.0-stage → 0.1.0

package/ios/Engine/RovqEngine.swift

@@ -0,0 +1,633 @@
+import Foundation
+
+private let maxQueuedEvents = 200
+private let eventBatchSize = 50
+private let bundleFileName = PackageRules.bundleFileName
+
+// A release closed before confirming gets this many more starts. A crash gets none.
+private let maxTryingRetries = 2
+
+private let firstPostpone: TimeInterval = 60 * 60
+private let maxPostpone: TimeInterval = 24 * 60 * 60
+
+// 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 let postponedCodes: Set<RovqErrorCode> = [.sizeMismatch, .hashMismatch, .invalidPackage]
+
+/// What the engine needs to know about the app.
+public struct EngineConfig {
+    public let apiURL: String
+    public let deploymentKey: String
+    public let runtimeVersion: String
+    public let binaryVersion: String
+    /// Changes whenever the app itself is installed or updated from a store.
+    public let binaryId: String
+    /// Key IDs and their Base64 public keys, built into the app.
+    public let trustedKeys: [String: String]
+    public let allowInsecureURLs: Bool
+
+    public init(
+        apiURL: String,
+        deploymentKey: String,
+        runtimeVersion: String,
+        binaryVersion: String,
+        binaryId: String,
+        trustedKeys: [String: String],
+        allowInsecureURLs: Bool = false
+    ) {
+        self.apiURL = apiURL
+        self.deploymentKey = deploymentKey
+        self.runtimeVersion = runtimeVersion
+        self.binaryVersion = binaryVersion
+        self.binaryId = binaryId
+        self.trustedKeys = trustedKeys
+        self.allowInsecureURLs = allowInsecureURLs
+    }
+}
+
+/// Facts about an update, all from a manifest whose signature has been verified.
+public struct UpdateInfo: Equatable {
+    public let releaseId: String
+    public let sequence: Int64
+    public let mandatory: Bool
+    public let packageSize: Int64
+}
+
+public enum CheckResult: Equatable {
+    case upToDate
+    /// `alreadyDownloaded` says whether `downloadUpdate` has nothing left to fetch.
+    case updateAvailable(UpdateInfo, alreadyDownloaded: Bool)
+    /// The server asked to leave the current release. Restart to apply.
+    case rolledBack
+    case failed(code: RovqErrorCode, message: String)
+}
+
+public enum DownloadResult: Equatable {
+    /// Verified and on disk. It loads only after `installUpdate`.
+    case downloaded(UpdateInfo)
+    case failed(code: RovqErrorCode, message: String)
+}
+
+public enum InstallResult: Equatable {
+    /// Loads on the next JavaScript start.
+    case installed(releaseId: String)
+    case failed(code: RovqErrorCode, message: String)
+}
+
+public enum SyncResult: Equatable {
+    case upToDate
+    /// Installed, and loads on the next JavaScript start.
+    case updateReady(releaseId: String, mandatory: Bool)
+    /// The server asked to leave the current release. Restart to apply.
+    case rolledBack
+    case failed(code: RovqErrorCode, message: String)
+}
+
+public struct EngineStatus: Equatable {
+    public let deviceId: String
+    public let currentReleaseId: String?
+    public let downloadedReleaseId: String?
+    public let pendingReleaseId: String?
+    public let tryingReleaseId: String?
+    public let highestSequence: Int64
+}
+
+/// 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.
+public final class RovqEngine {
+    private let rootFolder: URL
+    private let updatesFolder: URL
+    private let config: EngineConfig
+    private let service: UpdateService
+    private let clock: () -> TimeInterval
+    private let store: EngineStateStore
+    private let verifier: ManifestVerifier
+    private let installer: UpdateInstaller
+    private let lock = NSRecursiveLock()
+    // Held for a whole check, download or install, because each depends on the one before.
+    private let syncLock = NSLock()
+    // Kept in memory only, because its download URL expires. Guarded by syncLock.
+    private var offer: OfferedUpdate?
+    private var offerManifest: VerifiedManifest?
+    private var state: EngineState
+
+    /// - Throws: if a built-in public key is malformed, which is a mistake in the app itself.
+    public init(
+        rootFolder: URL,
+        config: EngineConfig,
+        service: UpdateService? = nil,
+        clock: @escaping () -> TimeInterval = { Date().timeIntervalSince1970 }
+    ) throws {
+        self.clock = clock
+        self.rootFolder = rootFolder
+        self.config = config
+        self.service = service ?? HTTPUpdateService(apiURL: config.apiURL, allowInsecureURLs: config.allowInsecureURLs)
+        updatesFolder = rootFolder.appendingPathComponent("updates", isDirectory: true)
+        store = EngineStateStore(rootFolder: rootFolder)
+        verifier = try ManifestVerifier(
+            trustedKeys: config.trustedKeys,
+            deploymentKey: config.deploymentKey,
+            runtimeVersion: config.runtimeVersion
+        )
+        installer = UpdateInstaller(
+            rootFolder: rootFolder,
+            verifier: verifier,
+            downloader: PackageDownloader(allowInsecureURLs: config.allowInsecureURLs)
+        )
+        try? FileManager.default.createDirectory(at: rootFolder, withIntermediateDirectories: true)
+        RovqEngine.excludeFromBackup(rootFolder)
+        state = RovqEngine.loadState(store: store, updatesFolder: updatesFolder, config: config)
+        verifier.revokedPublicKeys = state.revokedPublicKeys
+    }
+
+    /// Called each time JavaScript starts, before it loads. Returns the bundle to run, or nil
+    /// for the one inside the app. It never throws, or the app could not start.
+    public func resolveBundle() -> URL? {
+        lock.lock()
+        defer { lock.unlock() }
+
+        // Still marked as trying means the last start never confirmed that it works.
+        if let failed = state.trying {
+            // 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 < maxTryingRetries && bundleExists(failed) {
+                var retry = state
+                retry.backgroundedWhileTrying = false
+                retry.tryingRetries += 1
+                if save(retry) { return bundleFile(failed) }
+            }
+            var next = state
+            next.trying = nil
+            next.backgroundedWhileTrying = false
+            next.tryingRetries = 0
+            save(queue(next, type: "ROLLED_BACK", releaseId: failed.id, errorCode: "NOT_CONFIRMED"))
+        }
+
+        if let next = state.pending {
+            if !bundleExists(next) {
+                var updated = state
+                updated.pending = nil
+                save(updated)
+            } else {
+                var updated = state
+                updated.pending = nil
+                updated.trying = next
+                if save(updated) {
+                    // Saved first, so that if this bundle kills the process the next start knows.
+                    removeUnusedReleases()
+                    return bundleFile(next)
+                }
+                // 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.pending = next
+                state.trying = nil
+                return state.current.flatMap { bundleExists($0) ? bundleFile($0) : nil }
+            }
+        }
+
+        // A confirmed release can only disappear through outside interference.
+        if let current = state.current, !bundleExists(current) {
+            var updated = state
+            updated.current = state.previous
+            updated.previous = nil
+            save(updated)
+        }
+        if let current = state.current, !bundleExists(current) {
+            var updated = state
+            updated.current = nil
+            updated.previous = nil
+            save(updated)
+        }
+        removeUnusedReleases()
+        return state.current.map(bundleFile)
+    }
+
+    /// Called when the app goes to the background. See `resolveBundle`.
+    public func noteBackgrounded() {
+        lock.lock()
+        defer { lock.unlock() }
+        guard state.trying != nil, !state.backgroundedWhileTrying else { return }
+        var next = state
+        next.backgroundedWhileTrying = true
+        save(next)
+    }
+
+    /// Called when the app is crashing, so nothing that follows can look like closing the app.
+    public func noteCrashed() {
+        lock.lock()
+        defer { lock.unlock() }
+        guard state.trying != nil else { return }
+        var next = state
+        next.backgroundedWhileTrying = false
+        next.tryingRetries = maxTryingRetries
+        save(next)
+    }
+
+    /// Called by the app once it has started properly. It keeps the running release.
+    public func notifyReady() {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let confirmed = state.trying else { return }
+        var next = state
+        next.trying = nil
+        next.backgroundedWhileTrying = false
+        next.tryingRetries = 0
+        next.previous = state.current
+        next.current = confirmed
+        save(queue(next, type: "CONFIRMED", releaseId: confirmed.id, errorCode: nil))
+    }
+
+    /// 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.
+    ///
+    /// - Returns: whether there was anything to leave.
+    @discardableResult
+    public func rollback(reason: String = "REQUESTED") -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let leaving = state.trying ?? state.current else { return false }
+        var next = state
+        next.backgroundedWhileTrying = false
+        next.tryingRetries = 0
+        if state.trying != nil {
+            next.trying = nil
+        } else {
+            next.current = state.previous
+            next.previous = nil
+        }
+        save(queue(next, type: "ROLLED_BACK", releaseId: leaving.id, errorCode: 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. Blocks until finished,
+    /// so call it away from the main thread.
+    public func checkForUpdate() -> CheckResult {
+        syncLock.lock()
+        defer { syncLock.unlock() }
+        let result = checkOnce()
+        flushEvents()
+        return result
+    }
+
+    /// Fetches the update found by the last `checkForUpdate`, without activating it. Blocks
+    /// until finished, so call it away from the main thread.
+    public func downloadUpdate(onProgress: @escaping (Int64, Int64) -> Void = { _, _ in }) -> DownloadResult {
+        syncLock.lock()
+        defer { syncLock.unlock() }
+        let result = downloadOnce(onProgress: onProgress)
+        flushEvents()
+        return 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.
+    public func installUpdate() -> InstallResult {
+        syncLock.lock()
+        defer { syncLock.unlock() }
+        return installOnce()
+    }
+
+    /// The three steps together, for an app that does not need to ask the user in between.
+    /// Blocks until finished, so call it away from the main thread.
+    public func sync(onProgress: @escaping (Int64, Int64) -> Void = { _, _ in }) -> SyncResult {
+        syncLock.lock()
+        defer { syncLock.unlock() }
+        let result = syncOnce(onProgress: onProgress)
+        flushEvents()
+        return result
+    }
+
+    public func status() -> EngineStatus {
+        lock.lock()
+        defer { lock.unlock() }
+        return 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 func syncOnce(onProgress: @escaping (Int64, Int64) -> Void) -> SyncResult {
+        let update: UpdateInfo
+        switch checkOnce() {
+        case .upToDate:
+            return .upToDate
+        case .rolledBack:
+            return .rolledBack
+        case .failed(let code, let message):
+            return .failed(code: code, message: message)
+        case .updateAvailable(let info, _):
+            update = info
+        }
+        if case .failed(let code, let message) = downloadOnce(onProgress: onProgress) {
+            return .failed(code: code, message: message)
+        }
+        switch installOnce() {
+        case .installed:
+            return .updateReady(releaseId: update.releaseId, mandatory: update.mandatory)
+        case .failed(let code, let message):
+            return .failed(code: code, message: message)
+        }
+    }
+
+    private func checkOnce() -> CheckResult {
+        offer = nil
+        offerManifest = nil
+        let request: CheckRequest = {
+            lock.lock()
+            defer { lock.unlock() }
+            return CheckRequest(
+                deploymentKey: config.deploymentKey,
+                deviceId: state.deviceId,
+                runtimeVersion: config.runtimeVersion,
+                binaryVersion: config.binaryVersion,
+                currentReleaseId: (state.trying ?? state.current)?.id,
+                highestSequence: state.highestSequence
+            )
+        }()
+
+        let answer: CheckAnswer
+        do {
+            answer = try service.check(request)
+        } catch {
+            return .failed(code: .downloadFailed, message: error.localizedDescription)
+        }
+
+        // First, so that an offer signed by a key revoked in this same answer is refused.
+        applyRevocations(answer.revocations)
+        switch answer.response {
+        case .none:
+            keepDownloadedOnlyIf(offered: nil)
+            return .upToDate
+        case .rollback:
+            keepDownloadedOnlyIf(offered: nil)
+            return rollback(reason: "DISABLED_ON_SERVER") ? .rolledBack : .upToDate
+        case .update(let offered):
+            return verifyOffer(offered, highestSequence: request.highestSequence)
+        }
+    }
+
+    /// Permanent, so a server compromised later cannot make this device trust the key again.
+    private func applyRevocations(_ revocations: [KeyRevocation]) {
+        let valid = revocations.compactMap {
+            verifier.verifyRevocation(keyId: $0.keyId, statement: $0.statement, signature: $0.signature)
+        }
+        if valid.isEmpty { return }
+        lock.lock()
+        defer { lock.unlock() }
+        let all = state.revokedPublicKeys.union(valid)
+        if all == state.revokedPublicKeys { return }
+        var next = state
+        next.revokedPublicKeys = all
+        // A downloaded release may have been signed with that key, and nothing checks it again.
+        next.downloaded = nil
+        save(next)
+        verifier.revokedPublicKeys = all
+    }
+
+    private func verifyOffer(_ offered: OfferedUpdate, highestSequence: Int64) -> CheckResult {
+        do {
+            let manifest = try verifier.verify(
+                manifest: offered.manifest,
+                signature: offered.signature,
+                keyId: offered.keyId,
+                highestSequence: highestSequence
+            )
+            offer = offered
+            offerManifest = manifest
+            keepDownloadedOnlyIf(offered: manifest.releaseId)
+            lock.lock()
+            defer { lock.unlock() }
+            return .updateAvailable(updateInfo(manifest), alreadyDownloaded: state.downloaded != nil)
+        } catch {
+            let rovqError = recordFailure(error)
+            return .failed(code: rovqError.code, message: rovqError.message)
+        }
+    }
+
+    /// 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 func keepDownloadedOnlyIf(offered releaseId: String?) {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let downloaded = state.downloaded, downloaded.id != releaseId else { return }
+        var next = state
+        next.downloaded = nil
+        save(next)
+    }
+
+    private func downloadOnce(onProgress: @escaping (Int64, Int64) -> Void) -> DownloadResult {
+        guard let offered = offer else {
+            return .failed(code: .noUpdateAvailable, message: "No update to download. Check for updates first")
+        }
+        let releaseId = offerManifest?.releaseId
+        lock.lock()
+        let highestSequence = state.highestSequence
+        let postponed = state.postponed
+        lock.unlock()
+        // A clock moved back must not make the wait longer than the longest one allowed.
+        if let postponed, postponed.releaseId == releaseId {
+            let remaining = postponed.until - clock()
+            if remaining > 0 && remaining <= maxPostpone {
+                return .failed(
+                    code: .downloadPostponed,
+                    message: "This update failed its checks, so it will not be downloaded again yet")
+            }
+        }
+        do {
+            let installed = try installer.install(
+                offer: offered, highestSequence: highestSequence, onProgress: onProgress)
+            let manifest = installed.manifest
+            lock.lock()
+            defer { lock.unlock() }
+            var next = state
+            next.downloaded = ReleaseRef(id: manifest.releaseId, sequence: manifest.sequence)
+            next.postponed = nil
+            save(next)
+            return .downloaded(updateInfo(manifest))
+        } catch {
+            let rovqError = recordFailure(error)
+            if postponedCodes.contains(rovqError.code), let releaseId { postpone(releaseId) }
+            return .failed(code: rovqError.code, message: rovqError.message)
+        }
+    }
+
+    private func postpone(_ releaseId: String) {
+        lock.lock()
+        defer { lock.unlock() }
+        let attempts = state.postponed?.releaseId == releaseId ? (state.postponed?.attempts ?? 0) + 1 : 1
+        let wait = min(firstPostpone * pow(2, Double(attempts - 1)), maxPostpone)
+        var next = state
+        next.postponed = PostponedDownload(releaseId: releaseId, attempts: attempts, until: clock() + wait)
+        save(next)
+    }
+
+    private func installOnce() -> InstallResult {
+        lock.lock()
+        defer { lock.unlock() }
+        guard let downloaded = state.downloaded, bundleExists(downloaded) else {
+            if state.downloaded != nil {
+                var next = state
+                next.downloaded = nil
+                save(next)
+            }
+            return .failed(code: .noUpdateDownloaded, message: "No update has been downloaded")
+        }
+        offer = nil
+        offerManifest = nil
+        var next = state
+        next.downloaded = nil
+        next.pending = downloaded
+        // Recorded now, so a release that later fails is never accepted again.
+        next.highestSequence = max(state.highestSequence, downloaded.sequence)
+        save(queue(next, type: "INSTALLED", releaseId: downloaded.id, errorCode: nil))
+        return .installed(releaseId: downloaded.id)
+    }
+
+    @discardableResult
+    private func recordFailure(_ error: Error) -> RovqError {
+        let rovqError = error as? RovqError ?? RovqError(.storageFailed, error.localizedDescription)
+        let type = rovqError.code == .downloadFailed ? "DOWNLOAD_FAILED" : "VERIFICATION_FAILED"
+        lock.lock()
+        defer { lock.unlock() }
+        save(queue(state, type: type, releaseId: nil, errorCode: rovqError.code.rawValue))
+        return rovqError
+    }
+
+    private func updateInfo(_ manifest: VerifiedManifest) -> UpdateInfo {
+        UpdateInfo(
+            releaseId: manifest.releaseId,
+            sequence: manifest.sequence,
+            mandatory: manifest.mandatory,
+            packageSize: manifest.packageSize
+        )
+    }
+
+    /// Best effort. Events stay queued and go with a later sync if this fails.
+    private func flushEvents() {
+        lock.lock()
+        let batch = Array(state.events.prefix(eventBatchSize))
+        let deviceId = state.deviceId
+        lock.unlock()
+        if batch.isEmpty { return }
+
+        guard (try? service.report(deploymentKey: config.deploymentKey, deviceId: deviceId, events: batch)) != nil
+        else { return }
+
+        let sent = Set(batch.map(\.clientEventId))
+        lock.lock()
+        defer { lock.unlock() }
+        var next = state
+        next.events.removeAll { sent.contains($0.clientEventId) }
+        save(next)
+    }
+
+    private static func loadState(
+        store: EngineStateStore,
+        updatesFolder: URL,
+        config: EngineConfig
+    ) -> EngineState {
+        let saved = store.read()
+        var fresh = EngineState(
+            deviceId: saved?.deviceId ?? UUID().uuidString.lowercased(),
+            binaryId: config.binaryId,
+            runtimeVersion: config.runtimeVersion
+        )
+        guard let saved else {
+            // Without a readable state nothing on disk can be trusted, so start clean.
+            try? FileManager.default.removeItem(at: updatesFolder)
+            try? store.write(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.
+        try? FileManager.default.removeItem(at: updatesFolder)
+        fresh.highestSequence = saved.runtimeVersion == config.runtimeVersion ? saved.highestSequence : 0
+        fresh.events = saved.events
+        // Revocation is permanent, whatever the version of the app.
+        fresh.revokedPublicKeys = saved.revokedPublicKeys
+        try? store.write(fresh)
+        return fresh
+    }
+
+    /// Updates can be downloaded again, so they should not use the user's iCloud backup.
+    private static func excludeFromBackup(_ folder: URL) {
+        var url = folder
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        try? url.setResourceValues(values)
+    }
+
+    private func bundleFile(_ release: ReleaseRef) -> URL {
+        updatesFolder
+            .appendingPathComponent(release.id, isDirectory: true)
+            .appendingPathComponent(bundleFileName)
+    }
+
+    private func bundleExists(_ release: ReleaseRef) -> Bool {
+        FileManager.default.fileExists(atPath: bundleFile(release).path)
+    }
+
+    private func removeUnusedReleases() {
+        let inUse = Set([state.current, state.previous, state.downloaded, state.pending, state.trying].compactMap { $0?.id })
+        let folders = (try? FileManager.default.contentsOfDirectory(at: updatesFolder, includingPropertiesForKeys: nil)) ?? []
+        for folder in folders where !inUse.contains(folder.lastPathComponent) {
+            try? FileManager.default.removeItem(at: folder)
+        }
+    }
+
+    private func queue(
+        _ base: EngineState,
+        type: String,
+        releaseId: String?,
+        errorCode: String?
+    ) -> EngineState {
+        var next = base
+        next.events.append(
+            QueuedEvent(
+                clientEventId: UUID().uuidString.lowercased(),
+                type: type,
+                releaseId: releaseId,
+                errorCode: errorCode,
+                occurredAt: RovqEngine.now()
+            ))
+        next.events = Array(next.events.suffix(maxQueuedEvents))
+        return 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.
+    ///
+    /// - Returns: whether the change will survive a process death.
+    @discardableResult
+    private func save(_ next: EngineState) -> Bool {
+        state = next
+        do {
+            try store.write(next)
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    private static func now() -> String {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter.string(from: Date())
+    }
+}

package/ios/Engine/RovqError.swift

@@ -0,0 +1,35 @@
+import Foundation
+
+/// Why an update failed. The names match Android and are 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.
+public enum RovqErrorCode: String {
+    case unknownSigningKey = "UNKNOWN_SIGNING_KEY"
+    case revokedSigningKey = "REVOKED_SIGNING_KEY"
+    case invalidSignature = "INVALID_SIGNATURE"
+    case invalidManifest = "INVALID_MANIFEST"
+    case manifestMismatch = "MANIFEST_MISMATCH"
+    case staleSequence = "STALE_SEQUENCE"
+    case insecureURL = "INSECURE_URL"
+    case downloadFailed = "DOWNLOAD_FAILED"
+    case sizeMismatch = "SIZE_MISMATCH"
+    case hashMismatch = "HASH_MISMATCH"
+    case invalidPackage = "INVALID_PACKAGE"
+    case storageFailed = "STORAGE_FAILED"
+    case noUpdateAvailable = "NO_UPDATE_AVAILABLE"
+    case noUpdateDownloaded = "NO_UPDATE_DOWNLOADED"
+    case engineUnavailable = "ENGINE_UNAVAILABLE"
+    case downloadPostponed = "DOWNLOAD_POSTPONED"
+}
+
+public struct RovqError: Error, LocalizedError {
+    public let code: RovqErrorCode
+    public let message: String
+
+    public init(_ code: RovqErrorCode, _ message: String) {
+        self.code = code
+        self.message = message
+    }
+
+    public var errorDescription: String? { message }
+}