@hot-updater/react-native 1.0.0-rc.16 → 1.0.0-rc.17

package/ios/HotUpdater/Internal/BundleMetadata.swift

@@ -383,6 +383,8 @@ public struct LaunchReport: Codable {
     }
 }
 
+/// The random id created once per app installation. It lives in
+/// `NoBackupStorage`, so a device backup never carries it to another device.
 public struct InstallIdentity: Codable {
     static let installIdentityFilename = "install-identity.json"
 
@@ -412,11 +414,7 @@ public struct InstallIdentity: Codable {
             let encoder = JSONEncoder()
             encoder.outputFormatting = .prettyPrinted
             let data = try encoder.encode(self)
-            let directory = file.deletingLastPathComponent()
-            if !FileManager.default.fileExists(atPath: directory.path) {
-                try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-            }
-            try data.write(to: file)
+            try NoBackupStorage.write(data, to: file)
             return true
         } catch {
             print("[InstallIdentity] Failed to save install identity: \(error)")
@@ -424,51 +422,3 @@ public struct InstallIdentity: Codable {
         }
     }
 }
-
-public struct UserIdentity: Codable {
-    static let userIdentityFilename = "user-identity.json"
-
-    let userId: String?
-    let username: String?
-
-    init(userId: String?, username: String?) {
-        self.userId = userId
-        self.username = username
-    }
-
-    var isEmpty: Bool {
-        userId == nil && username == nil
-    }
-
-    static func load(from file: URL) -> UserIdentity? {
-        guard FileManager.default.fileExists(atPath: file.path) else {
-            return nil
-        }
-
-        do {
-            let data = try Data(contentsOf: file)
-            let identity = try JSONDecoder().decode(UserIdentity.self, from: data)
-            return identity.isEmpty ? nil : identity
-        } catch {
-            print("[UserIdentity] Failed to load user identity: \(error)")
-            return nil
-        }
-    }
-
-    func save(to file: URL) -> Bool {
-        do {
-            let encoder = JSONEncoder()
-            encoder.outputFormatting = .prettyPrinted
-            let data = try encoder.encode(self)
-            let directory = file.deletingLastPathComponent()
-            if !FileManager.default.fileExists(atPath: directory.path) {
-                try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-            }
-            try data.write(to: file)
-            return true
-        } catch {
-            print("[UserIdentity] Failed to save user identity: \(error)")
-            return false
-        }
-    }
-}

package/ios/HotUpdater/Internal/FileManagerService.swift

@@ -17,6 +17,45 @@ protocol FileSystemService {
     func contentsOfDirectory(atPath path: String) throws -> [String]
     func attributesOfItem(atPath path: String) throws -> [FileAttributeKey: Any]
     func documentsPath() -> String
+    /// Base directory for data that lives as long as the installation.
+    func applicationSupportPath() -> String
+}
+
+/// `Application Support/HotUpdater`: data the SDK keeps for the life of an
+/// installation, such as the install id and plugin storage. Device backups
+/// skip it, so restoring a backup onto another device never copies it there.
+enum NoBackupStorage {
+    static let directoryName = "HotUpdater"
+
+    static func directory(in fileSystem: FileSystemService) -> URL {
+        URL(fileURLWithPath: fileSystem.applicationSupportPath(), isDirectory: true)
+            .appendingPathComponent(directoryName, isDirectory: true)
+    }
+
+    /// Atomically replaces `file` with `data`, creating its directory when
+    /// needed, and excludes the directory and the file from device backups.
+    static func write(_ data: Data, to file: URL) throws {
+        let directory = file.deletingLastPathComponent()
+        try FileManager.default.createDirectory(
+            at: directory,
+            withIntermediateDirectories: true
+        )
+        excludeFromBackup(directory)
+        try data.write(to: file, options: .atomic)
+        // An atomic write replaces the file, which drops its previous flag.
+        excludeFromBackup(file)
+    }
+
+    static func excludeFromBackup(_ url: URL) {
+        var url = url
+        var values = URLResourceValues()
+        values.isExcludedFromBackup = true
+        do {
+            try url.setResourceValues(values)
+        } catch {
+            NSLog("[NoBackupStorage] Failed to exclude \(url.path) from backups: \(error)")
+        }
+    }
 }
 
 class FileManagerService: FileSystemService {
@@ -89,4 +128,13 @@ class FileManagerService: FileSystemService {
         return NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true)[0]
         #endif
     }
+
+    func applicationSupportPath() -> String {
+        #if os(tvOS)
+        // tvOS apps can only write purgeable files, so use Caches like documentsPath().
+        return NSSearchPathForDirectoriesInDomains(.cachesDirectory, .userDomainMask, true)[0]
+        #else
+        return NSSearchPathForDirectoriesInDomains(.applicationSupportDirectory, .userDomainMask, true)[0]
+        #endif
+    }
 }

package/ios/HotUpdater/Internal/HotUpdater.mm

@@ -660,19 +660,14 @@ RCT_EXPORT_MODULE();
     return [impl getInstallId];
 }
 
-- (NSString * _Nullable)getUserId {
+- (NSString * _Nullable)getStorageItem:(NSString *)key {
     HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    return [impl getUserId];
+    return [impl getStorageItem:key];
 }
 
-- (NSString * _Nullable)getUsername {
+- (void)setStorageItem:(NSString *)key value:(NSString * _Nullable)value {
     HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    return [impl getUsername];
-}
-
-- (void)setUser:(NSString * _Nullable)userId username:(NSString * _Nullable)username {
-    HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    [impl setUser:userId username:username];
+    [impl setStorageItem:key value:value];
 }
 
 - (NSString * _Nullable)getBaseURL {
@@ -830,19 +825,14 @@ RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getInstallId) {
     return [impl getInstallId];
 }
 
-RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getUserId) {
-    HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    return [impl getUserId];
-}
-
-RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getUsername) {
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getStorageItem:(NSString *)key) {
     HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    return [impl getUsername];
+    return [impl getStorageItem:key];
 }
 
-RCT_EXPORT_METHOD(setUser:(NSString * _Nullable)userId username:(NSString * _Nullable)username) {
+RCT_EXPORT_METHOD(setStorageItem:(NSString *)key value:(NSString * _Nullable)value) {
     HotUpdaterImpl *impl = [HotUpdater sharedImpl];
-    [impl setUser:userId username:username];
+    [impl setStorageItem:key value:value];
 }
 
 RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getBaseURL) {

package/ios/HotUpdater/Internal/HotUpdaterImpl.swift

@@ -56,6 +56,7 @@ private func hotUpdaterGetMinBundleId() -> String {
     private let cohortService: CohortService
     private let recoveryManager: HotUpdaterRecoveryManager
     private let releaseCatalogCache: ReleaseCatalogCacheService
+    private let keyValueStorage: KeyValueStorageService
     private var currentLaunchSelection: LaunchSelection?
 
     private static let DEFAULT_CHANNEL = "production"
@@ -99,7 +100,10 @@ private func hotUpdaterGetMinBundleId() -> String {
             bundleStorage: bundleStorage,
             preferences: preferences,
             recoveryManager: recoveryManager,
-            releaseCatalogCache: ReleaseCatalogCacheService()
+            releaseCatalogCache: ReleaseCatalogCacheService(),
+            keyValueStorage: KeyValueStorageService(
+                directory: NoBackupStorage.directory(in: fileSystem)
+            )
         )
     }
 
@@ -107,18 +111,23 @@ private func hotUpdaterGetMinBundleId() -> String {
      * Primary initializer with dependency injection.
      * @param bundleStorage Service for bundle storage operations
      * @param preferences Service for preference storage
+     * @param keyValueStorage Persistent key-value store for client plugins
      */
     internal init(
         bundleStorage: BundleStorageService,
         preferences: PreferencesService,
         recoveryManager: HotUpdaterRecoveryManager,
-        releaseCatalogCache: ReleaseCatalogCacheService = ReleaseCatalogCacheService()
+        releaseCatalogCache: ReleaseCatalogCacheService = ReleaseCatalogCacheService(),
+        keyValueStorage: KeyValueStorageService = KeyValueStorageService(
+            directory: NoBackupStorage.directory(in: FileManagerService())
+        )
     ) {
         self.bundleStorage = bundleStorage
         self.preferences = preferences
         self.cohortService = CohortService()
         self.recoveryManager = recoveryManager
         self.releaseCatalogCache = releaseCatalogCache
+        self.keyValueStorage = keyValueStorage
         super.init()
 
         // Configure preferences with isolation key
@@ -244,8 +253,10 @@ private func hotUpdaterGetMinBundleId() -> String {
      * Updates the bundle from JavaScript bridge.
      * This method acts as the primary error boundary for all bundle operations.
      * @param params Dictionary with bundleId, manifest, and asset parameters
-     * @param resolve Promise resolve callback
-     * @param reject Promise reject callback
+     * @param resolve Promise resolve callback, called with the staged bundle's
+     *   `{ delivery, patchFallback }`
+     * @param reject Promise reject callback; download and install failures
+     *   carry `stage`, `reason`, and their details in the error's userInfo
      */
     public func updateBundle(_ params: NSDictionary?,
                                          resolver resolve: @escaping RCTPromiseResolveBlock,
@@ -260,33 +271,35 @@ private func hotUpdaterGetMinBundleId() -> String {
                 return
             }
 
+            // Invalid update parameters are an invalid update response.
             guard let bundleId = data["bundleId"] as? String, !bundleId.isEmpty else {
-                let error = NSError(domain: "HotUpdater", code: 0,
-                                   userInfo: [NSLocalizedDescriptionKey: "Missing or empty 'bundleId'"])
+                let error = UpdateFailure.invalidResponse.error(description: "Missing or empty 'bundleId'")
                 reject("MISSING_BUNDLE_ID", error.localizedDescription, error)
                 return
             }
 
             guard let manifestFileHash = data["manifestFileHash"] as? String,
                   !manifestFileHash.isEmpty else {
-                let error = NSError(domain: "HotUpdater", code: 0,
-                                   userInfo: [NSLocalizedDescriptionKey: "Missing manifest file hash"])
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest)
+                    .error(description: "Missing manifest file hash")
                 reject("INVALID_MANIFEST", error.localizedDescription, error)
                 return
             }
             let channel = data["channel"] as? String
             let manifestUrlString = data["manifestUrl"] as? String ?? ""
             guard let manifestUrl = URL(string: manifestUrlString) else {
-                let error = NSError(domain: "HotUpdater", code: 0,
-                                   userInfo: [NSLocalizedDescriptionKey: "Invalid 'manifestUrl' provided: \(manifestUrlString)"])
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest).error(
+                    description: "Invalid 'manifestUrl' provided: \(manifestUrlString)"
+                )
                 reject("INVALID_FILE_URL", error.localizedDescription, error)
                 return
             }
             let archiveUrl: URL?
             if let archiveUrlString = data["archiveUrl"] as? String {
                 guard let parsedArchiveUrl = URL(string: archiveUrlString) else {
-                    let error = NSError(domain: "HotUpdater", code: 0,
-                                       userInfo: [NSLocalizedDescriptionKey: "Invalid 'archiveUrl' provided: \(archiveUrlString)"])
+                    let error = UpdateFailure.invalidResponse.with(resource: .archive).error(
+                        description: "Invalid 'archiveUrl' provided: \(archiveUrlString)"
+                    )
                     reject("INVALID_FILE_URL", error.localizedDescription, error)
                     return
                 }
@@ -295,8 +308,8 @@ private func hotUpdaterGetMinBundleId() -> String {
                 archiveUrl = nil
             }
             guard let assetsPayload = data["assets"] as? [String: [String: Any]] else {
-                let error = NSError(domain: "HotUpdater", code: 0,
-                                   userInfo: [NSLocalizedDescriptionKey: "Missing manifest assets"])
+                let error = UpdateFailure.invalidResponse.with(resource: .manifest)
+                    .error(description: "Missing manifest assets")
                 reject("INVALID_MANIFEST", error.localizedDescription, error)
                 return
             }
@@ -344,11 +357,8 @@ private func hotUpdaterGetMinBundleId() -> String {
             }
             let selection = (data["selection"] as? [String: Any]).flatMap(Self.parseSelection)
             if let selection, !bundleStorage.stageReleaseSelection(selection) {
-                let error = NSError(
-                    domain: "HotUpdater",
-                    code: 0,
-                    userInfo: [NSLocalizedDescriptionKey: "Release catalog selection is stale"]
-                )
+                // Not an update failure, so the rejection carries no stage or reason.
+                let error = StaleReleaseSelectionError() as NSError
                 reject("UNKNOWN_ERROR", error.localizedDescription, error)
                 return
             }
@@ -383,7 +393,7 @@ private func hotUpdaterGetMinBundleId() -> String {
                 // Return results on main thread for React Native bridge
                 DispatchQueue.main.async {
                     switch result {
-                    case .success:
+                    case .success(let delivery):
                         NSLog("[HotUpdaterImpl] Update successful for \(bundleId). Resolving promise.")
                         if let channel, !channel.isEmpty {
                             do {
@@ -396,12 +406,14 @@ private func hotUpdaterGetMinBundleId() -> String {
                                 NSLog("[HotUpdaterImpl] Failed to persist channel override: \(error)")
                             }
                         }
-                        resolve(true)
+                        // { delivery: "patch" | "manifest" | "archive", patchFallback }
+                        resolve(delivery.dictionary)
                     case .failure(let error):
                         NSLog("[HotUpdaterImpl] Update failed for \(bundleId) - Error: \(error)")
 
                         let normalizedCode = HotUpdaterImpl.normalizeErrorCode(from: error)
-                        let nsError = error as NSError
+                        // A classified failure adds stage, reason, and its details to userInfo.
+                        let nsError = UpdateFailureError.rejectionError(for: error)
                         reject(normalizedCode, nsError.localizedDescription, nsError)
                     }
                 }
@@ -536,6 +548,8 @@ private func hotUpdaterGetMinBundleId() -> String {
      * Rare or platform-specific codes are collapsed to UNKNOWN_ERROR to reduce surface area.
      */
     private static func normalizeErrorCode(from error: Error) -> String {
+        // Classification wraps an error without changing its code.
+        let error = UpdateFailureError.unwrap(error)
         let baseCode: String
 
         if let storageError = error as? BundleStorageError {
@@ -601,16 +615,21 @@ private func hotUpdaterGetMinBundleId() -> String {
         return bundleStorage.getInstallId()
     }
 
-    public func getUserId() -> String? {
-        return bundleStorage.getUserId()
-    }
+    // MARK: - Client Plugin Storage
 
-    public func getUsername() -> String? {
-        return bundleStorage.getUsername()
+    /**
+     * Reads a value from the persistent key-value store for client plugins.
+     * @return The stored value or nil when the key has none
+     */
+    public func getStorageItem(_ key: String) -> String? {
+        return keyValueStorage.getItem(key)
     }
 
-    public func setUser(_ userId: String?, username: String?) {
-        bundleStorage.setUser(userId: userId, username: username)
+    /**
+     * Writes a value to the persistent key-value store; nil removes the key.
+     */
+    public func setStorageItem(_ key: String, value: String?) {
+        keyValueStorage.setItem(key, value: value)
     }
 
     /**

package/ios/HotUpdater/Internal/KeyValueStorageService.swift

@@ -0,0 +1,71 @@
+import Foundation
+
+/// Persistent string key-value store for client plugins, kept in
+/// `Application Support/HotUpdater/storage.json` outside device backups.
+///
+/// Keys are opaque; JavaScript namespaces them per plugin. The file is read
+/// into memory on first use, and every write replaces the whole file.
+final class KeyValueStorageService {
+    static let storageFilename = "storage.json"
+
+    private let fileURL: URL
+    private let lock = NSLock()
+    private var items: [String: String]?
+
+    init(directory: URL) {
+        self.fileURL = directory.appendingPathComponent(Self.storageFilename)
+    }
+
+    func getItem(_ key: String) -> String? {
+        lock.lock()
+        defer { lock.unlock() }
+        return loadedItems()[key]
+    }
+
+    /// Stores `value` under `key`, or removes the key when `value` is nil.
+    /// Returns false when the file could not be written.
+    @discardableResult
+    func setItem(_ key: String, value: String?) -> Bool {
+        lock.lock()
+        defer { lock.unlock() }
+
+        var updatedItems = loadedItems()
+        updatedItems[key] = value
+        // Memory stays the source of truth for this process, so the next
+        // successful write also persists a value whose own write failed.
+        items = updatedItems
+
+        do {
+            let data = try JSONSerialization.data(
+                withJSONObject: updatedItems,
+                options: [.sortedKeys]
+            )
+            try NoBackupStorage.write(data, to: fileURL)
+            return true
+        } catch {
+            NSLog("[KeyValueStorage] Failed to write \(fileURL.path): \(error)")
+            return false
+        }
+    }
+
+    private func loadedItems() -> [String: String] {
+        if let items {
+            return items
+        }
+        let loadedItems = Self.readItems(from: fileURL)
+        items = loadedItems
+        return loadedItems
+    }
+
+    /// A missing, unreadable, or corrupt file reads as an empty store.
+    private static func readItems(from file: URL) -> [String: String] {
+        guard let data = try? Data(contentsOf: file) else {
+            return [:]
+        }
+        guard let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            NSLog("[KeyValueStorage] Ignoring unreadable store at \(file.path)")
+            return [:]
+        }
+        return object.compactMapValues { $0 as? String }
+    }
+}

package/ios/HotUpdater/Internal/URLSessionDownloadService.swift

@@ -23,9 +23,108 @@ protocol DownloadService {
 }
 
 
-enum DownloadError: Error {
+enum DownloadError: Error, Equatable {
     case incompleteDownload(expected: Int64, actual: Int64)
     case invalidContentLength
+    /// The server answered with a status outside 200-299. `originCode` is the
+    /// `<Code>` of a storage origin's XML error body, when it has one.
+    case httpStatus(Int, originCode: String? = nil)
+
+    /// How much of an error body is searched for a storage origin's code.
+    static let maximumErrorBodyPrefixByteCount = 4 * 1024
+    private static let maximumOriginCodeLength = 64
+
+    /// The failure for an HTTP response outside 200-299, or nil for a
+    /// successful or non-HTTP response. `body` is the saved response body.
+    static func httpStatusError(for response: URLResponse?, body: URL?) -> DownloadError? {
+        guard let httpResponse = response as? HTTPURLResponse,
+              !(200..<300).contains(httpResponse.statusCode) else {
+            return nil
+        }
+        let originCode = body.flatMap { body -> String? in
+            guard let handle = try? FileHandle(forReadingFrom: body) else {
+                return nil
+            }
+            defer { try? handle.close() }
+            let prefix = try? FileUtilities.readUpToCount(
+                from: handle,
+                count: maximumErrorBodyPrefixByteCount
+            )
+            return prefix.flatMap { storageOriginErrorCode(in: $0) }
+        }
+        return .httpStatus(httpResponse.statusCode, originCode: originCode)
+    }
+
+    /// The `<Code>` of an S3, R2, or GCS style `<Error>` document in the
+    /// first 4 KB of `body`, such as "AccessDenied". Nothing else from the
+    /// body is kept, and a code must be 1-64 characters of [A-Za-z0-9._-].
+    static func storageOriginErrorCode(in body: Data) -> String? {
+        let text = String(decoding: body.prefix(maximumErrorBodyPrefixByteCount), as: UTF8.self)
+        guard let errorElement = text.range(of: "<Error"),
+              let codeStart = text.range(of: "<Code>", range: errorElement.upperBound..<text.endIndex),
+              let codeEnd = text.range(of: "</Code>", range: codeStart.upperBound..<text.endIndex) else {
+            return nil
+        }
+        let code = text[codeStart.upperBound..<codeEnd.lowerBound]
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        guard (1...maximumOriginCodeLength).contains(code.unicodeScalars.count),
+              code.unicodeScalars.allSatisfy(isOriginCodeCharacter) else {
+            return nil
+        }
+        return code
+    }
+
+    private static func isOriginCodeCharacter(_ scalar: Unicode.Scalar) -> Bool {
+        switch scalar {
+        case "A"..."Z", "a"..."z", "0"..."9", ".", "_", "-":
+            return true
+        default:
+            return false
+        }
+    }
+}
+
+extension DownloadError {
+    /// Attempts per download that retries, the first one included.
+    static let maximumAttempts = 3
+
+    /// 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 failure, a cancelled task, and a local file
+    /// failure would fail the same way again.
+    static func isRetryable(_ error: Error) -> Bool {
+        if let downloadError = error as? DownloadError {
+            switch downloadError {
+            case .httpStatus(let status, _):
+                return status == 408 || status == 429 || status >= 500
+            case .incompleteDownload:
+                return true
+            case .invalidContentLength:
+                return false
+            }
+        }
+        let nsError = error as NSError
+        guard nsError.domain == NSURLErrorDomain else {
+            return false
+        }
+        switch URLError.Code(rawValue: nsError.code) {
+        case .timedOut,
+             .cannotFindHost,
+             .cannotConnectToHost,
+             .networkConnectionLost,
+             .dnsLookupFailed,
+             .notConnectedToInternet,
+             .cannotLoadFromNetwork,
+             .callIsActive,
+             .dataNotAllowed,
+             .internationalRoamingOff,
+             .backgroundSessionWasDisconnected,
+             .badServerResponse:
+            return true
+        default:
+            return false
+        }
+    }
 }
 
 class URLSessionDownloadService: NSObject, DownloadService {
@@ -107,6 +206,14 @@ extension URLSessionDownloadService: URLSessionDownloadDelegate {
             return
         }
 
+        // URLSession saves error bodies too, so reject them before they reach verification.
+        if let httpError = DownloadError.httpStatusError(for: downloadTask.response, body: location) {
+            NSLog("[DownloadService] Download failed: \(httpError)")
+            try? FileManager.default.removeItem(at: location)
+            completion?(.failure(httpError))
+            return
+        }
+
         // Verify file size
         let expectedSize = downloadTask.response?.expectedContentLength ?? -1
         let actualSize: Int64?