@otaupdate/react-native 1.0.0

package/android/src/main/java/com/otaupdate/OtaUpdateStore.kt

@@ -0,0 +1,268 @@
+package com.otaupdate
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+import java.util.UUID
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * On-disk state for downloaded JS bundles, and the rollback state machine.
+ *
+ * Layout under `filesDir/ota`:
+ *   status.json            the state below
+ *   packages/<sha256>/     one unzipped release each
+ *
+ * The state machine exists so a bundle that crashes on boot cannot brick the
+ * app:
+ *
+ *   install()            -> pending = {hash, isLoading = false}
+ *   next app start       -> promote: current = pending.hash, isLoading = true
+ *   notifyAppReady()     -> confirm: lastConfirmed = current, pending = null
+ *   start while loading  -> the previous boot never confirmed: roll back to
+ *                           lastConfirmed and blacklist the bad hash
+ */
+class OtaUpdateStore(private val context: Context) {
+
+  companion object {
+    const val TAG = "OtaUpdate"
+    private const val PREFS = "com.otaupdate.prefs"
+    private const val CLIENT_ID_KEY = "client_unique_id"
+
+    @Volatile private var didUpdateThisLaunch: Boolean = false
+
+    /** True when this launch swapped in a freshly installed bundle. */
+    @JvmStatic fun isFirstRunOfUpdate(): Boolean = didUpdateThisLaunch
+  }
+
+  private val rootDir: File = File(context.filesDir, "ota")
+  private val packagesDir: File = File(rootDir, "packages")
+  private val statusFile: File = File(rootDir, "status.json")
+
+  var currentHash: String? = null
+    private set
+  var lastConfirmedHash: String? = null
+    private set
+  var pendingHash: String? = null
+    private set
+  private var pendingIsLoading: Boolean = false
+  private val failedHashes = mutableSetOf<String>()
+  private val packages = mutableMapOf<String, JSONObject>()
+
+  init {
+    packagesDir.mkdirs()
+    load()
+  }
+
+  // --- Persistence ----------------------------------------------------------
+
+  @Synchronized
+  private fun load() {
+    if (!statusFile.exists()) return
+    try {
+      val json = JSONObject(statusFile.readText())
+      currentHash = json.optString("currentHash").ifEmpty { null }
+      lastConfirmedHash = json.optString("lastConfirmedHash").ifEmpty { null }
+      pendingHash = json.optString("pendingHash").ifEmpty { null }
+      pendingIsLoading = json.optBoolean("pendingIsLoading", false)
+
+      val failed = json.optJSONArray("failedHashes") ?: JSONArray()
+      for (i in 0 until failed.length()) failedHashes.add(failed.getString(i))
+
+      val pkgs = json.optJSONObject("packages") ?: JSONObject()
+      for (key in pkgs.keys()) packages[key] = pkgs.getJSONObject(key)
+    } catch (e: Exception) {
+      // A corrupt status file must not stop the app booting: fall back to the
+      // bundle shipped in the APK.
+      Log.e(TAG, "status.json unreadable, resetting OTA state", e)
+      reset()
+    }
+  }
+
+  @Synchronized
+  private fun save() {
+    try {
+      rootDir.mkdirs()
+      val json = JSONObject()
+      json.put("currentHash", currentHash ?: JSONObject.NULL)
+      json.put("lastConfirmedHash", lastConfirmedHash ?: JSONObject.NULL)
+      json.put("pendingHash", pendingHash ?: JSONObject.NULL)
+      json.put("pendingIsLoading", pendingIsLoading)
+      json.put("failedHashes", JSONArray(failedHashes.toList()))
+      json.put("packages", JSONObject(packages as Map<*, *>))
+      statusFile.writeText(json.toString())
+    } catch (e: Exception) {
+      Log.e(TAG, "failed to persist OTA state", e)
+    }
+  }
+
+  // --- Rollback state machine ----------------------------------------------
+
+  /**
+   * Called once per **process** start, before the JS bundle path is resolved.
+   * Returns true if a rollback happened.
+   */
+  @Synchronized
+  fun initializeAfterRestart(): Boolean {
+    val pending = pendingHash ?: return false
+
+    if (pendingIsLoading) {
+      // We already booted into this package and never heard notifyAppReady().
+      Log.w(TAG, "update $pending failed to become ready — rolling back")
+      failedHashes.add(pending)
+      currentHash = lastConfirmedHash
+      pendingHash = null
+      pendingIsLoading = false
+      didUpdateThisLaunch = false
+      save()
+      deletePackage(pending)
+      return true
+    }
+
+    promotePendingIfAny()
+    return false
+  }
+
+  /**
+   * Promote a freshly installed package without ever interpreting the call as a
+   * failed boot.
+   *
+   * IMMEDIATE and ON_NEXT_RESUME reload the JS bundle *inside the running
+   * process*, so the bundle path is resolved a second time with no new process
+   * start. Routing that through `initializeAfterRestart` would see
+   * `pendingIsLoading == true` and wrongly roll the update back; skipping it
+   * entirely would reload the old bundle. This is the middle ground.
+   */
+  @Synchronized
+  fun promotePendingIfAny(): Boolean {
+    val pending = pendingHash ?: return false
+    if (pendingIsLoading) return false
+
+    Log.i(TAG, "booting into pending update $pending")
+    currentHash = pending
+    pendingIsLoading = true
+    didUpdateThisLaunch = true
+    save()
+    return true
+  }
+
+  /** Confirms the running bundle. After this it can never be rolled back. */
+  @Synchronized
+  fun notifyApplicationReady() {
+    if (pendingHash == null) return
+    Log.i(TAG, "update ${pendingHash} confirmed healthy")
+    lastConfirmedHash = currentHash
+    pendingHash = null
+    pendingIsLoading = false
+    save()
+  }
+
+  @Synchronized
+  fun markPending(hash: String) {
+    pendingHash = hash
+    pendingIsLoading = false
+    save()
+  }
+
+  @Synchronized
+  fun hasFailed(hash: String): Boolean = failedHashes.contains(hash)
+
+  @Synchronized
+  fun isPending(): Boolean = pendingHash != null
+
+  // --- Packages -------------------------------------------------------------
+
+  fun packageDir(hash: String): File = File(packagesDir, hash)
+
+  @Synchronized
+  fun recordPackage(
+    hash: String,
+    label: String,
+    bundlePath: String,
+    description: String?,
+    isMandatory: Boolean,
+    size: Long,
+    appVersion: String,
+  ) {
+    packages[hash] = JSONObject().apply {
+      put("label", label)
+      put("bundlePath", bundlePath)
+      put("description", description ?: JSONObject.NULL)
+      put("isMandatory", isMandatory)
+      put("size", size)
+      put("appVersion", appVersion)
+      put("installedAt", System.currentTimeMillis())
+    }
+    save()
+  }
+
+  @Synchronized
+  fun packageInfo(hash: String?): JSONObject? = hash?.let { packages[it] }
+
+  /**
+   * Absolute path of the JS bundle to load, or null to use the one bundled in
+   * the APK. Falls back to the binary bundle if the file has vanished.
+   */
+  @Synchronized
+  fun currentBundlePath(): String? {
+    val hash = currentHash ?: return null
+    val info = packages[hash] ?: return null
+    val path = info.optString("bundlePath")
+    if (path.isEmpty() || !File(path).exists()) {
+      Log.w(TAG, "bundle for $hash is missing on disk — using the binary bundle")
+      currentHash = lastConfirmedHash.takeIf { it != hash }
+      save()
+      return currentHash?.let { packages[it]?.optString("bundlePath") }?.takeIf { File(it).exists() }
+    }
+    return path
+  }
+
+  @Synchronized
+  fun deletePackage(hash: String) {
+    packages.remove(hash)
+    packageDir(hash).deleteRecursively()
+    save()
+  }
+
+  /** Drops everything except the running and last-confirmed packages. */
+  @Synchronized
+  fun pruneOldPackages() {
+    val keep = setOfNotNull(currentHash, lastConfirmedHash, pendingHash)
+    for (hash in packages.keys.toList()) {
+      if (hash !in keep) {
+        packages.remove(hash)
+        packageDir(hash).deleteRecursively()
+      }
+    }
+    save()
+  }
+
+  @Synchronized
+  fun reset() {
+    currentHash = null
+    lastConfirmedHash = null
+    pendingHash = null
+    pendingIsLoading = false
+    failedHashes.clear()
+    packages.clear()
+    didUpdateThisLaunch = false
+    packagesDir.deleteRecursively()
+    packagesDir.mkdirs()
+    save()
+  }
+
+  // --- Device identity ------------------------------------------------------
+
+  /**
+   * Stable per-install id used for rollout bucketing. Not a hardware id — it
+   * is a random UUID that lives and dies with the app's data directory.
+   */
+  fun clientUniqueId(): String {
+    val prefs = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+    prefs.getString(CLIENT_ID_KEY, null)?.let { return it }
+    val id = UUID.randomUUID().toString()
+    prefs.edit().putString(CLIENT_ID_KEY, id).apply()
+    return id
+  }
+}

package/app.plugin.js

@@ -0,0 +1,3 @@
+// Expo resolves `app.plugin.js` when a project lists this package in
+// app.json's `plugins` array.
+module.exports = require('./plugin/build/index').default;

package/expo-module.config.json

@@ -0,0 +1,6 @@
+{
+  "platforms": ["android"],
+  "android": {
+    "modules": []
+  }
+}

package/ios/OtaUpdate.h

@@ -0,0 +1,46 @@
+//
+//  OtaUpdate.h
+//  react-native-ota-update
+//
+//  Public entry point for the host app.
+//
+//  Objective-C rather than Swift on purpose: the header below has to be
+//  importable from an AppDelegate written in either language, and a plain
+//  ObjC module (module_name = OtaUpdate) is importable from both without a
+//  bridging header or a generated -Swift.h.
+//
+//  AppDelegate.mm:
+//    #import <OtaUpdate/OtaUpdate.h>
+//    - (NSURL *)bundleURL { return [OtaUpdate bundleURL]; }
+//
+//  AppDelegate.swift:
+//    import OtaUpdate
+//    override func bundleURL() -> URL? { OtaUpdate.bundleURL() }
+//
+
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface OtaUpdate : RCTEventEmitter <RCTBridgeModule>
+
+/**
+ * The JS bundle React Native should load for this launch: the newest healthy
+ * downloaded bundle, or the one inside the app binary when there is none.
+ *
+ * Also advances the rollback state machine, so call it exactly where React
+ * Native asks for its bundle URL and nowhere else.
+ */
++ (nullable NSURL *)bundleURL;
+
+/** Same as `bundleURL`, but for a binary bundle with a non-default name. */
++ (nullable NSURL *)bundleURLForResource:(NSString *)resourceName
+                           withExtension:(NSString *)extension;
+
+/** The bundle inside the app binary, ignoring any downloaded update. */
++ (nullable NSURL *)binaryBundleURL;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/OtaUpdate.m

@@ -0,0 +1,302 @@
+#import "OtaUpdate.h"
+#import "OtaUpdateInstaller.h"
+#import "OtaUpdateStore.h"
+
+#import <React/RCTBridge.h>
+#import <React/RCTReloadCommand.h>
+#import <React/RCTUtils.h>
+
+static NSString *const kProgressEvent = @"OtaUpdateDownloadProgress";
+static NSString *const kDeploymentKeyPlist = @"OtaDeploymentKey";
+static NSString *const kServerUrlPlist = @"OtaServerUrl";
+
+typedef NS_ENUM(NSInteger, OtaInstallMode) {
+  OtaInstallModeOnNextRestart = 0,
+  OtaInstallModeOnNextResume = 1,
+  OtaInstallModeImmediate = 2,
+};
+
+@interface OtaUpdate ()
+@property (nonatomic, assign) BOOL hasListeners;
+@property (nonatomic, assign) BOOL restartOnResume;
+@property (nonatomic, assign) NSTimeInterval minimumBackgroundDuration;
+@property (nonatomic, assign) NSTimeInterval backgroundedAt;
+@end
+
+@implementation OtaUpdate
+
+RCT_EXPORT_MODULE()
+
++ (BOOL)requiresMainQueueSetup {
+  return NO;
+}
+
+- (dispatch_queue_t)methodQueue {
+  // Downloads and unzipping must never touch the main queue.
+  return dispatch_queue_create("com.otaupdate.module", DISPATCH_QUEUE_SERIAL);
+}
+
+- (NSArray<NSString *> *)supportedEvents {
+  return @[ kProgressEvent ];
+}
+
+- (void)startObserving {
+  self.hasListeners = YES;
+}
+
+- (void)stopObserving {
+  self.hasListeners = NO;
+}
+
+- (NSDictionary *)constantsToExport {
+  return @{
+    @"INSTALL_MODE_ON_NEXT_RESTART" : @(OtaInstallModeOnNextRestart),
+    @"INSTALL_MODE_ON_NEXT_RESUME" : @(OtaInstallModeOnNextResume),
+    @"INSTALL_MODE_IMMEDIATE" : @(OtaInstallModeImmediate),
+  };
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    [[NSNotificationCenter defaultCenter] addObserver:self
+                                             selector:@selector(applicationDidEnterBackground)
+                                                 name:UIApplicationDidEnterBackgroundNotification
+                                               object:nil];
+    [[NSNotificationCenter defaultCenter] addObserver:self
+                                             selector:@selector(applicationWillEnterForeground)
+                                                 name:UIApplicationWillEnterForegroundNotification
+                                               object:nil];
+  }
+  return self;
+}
+
+- (void)dealloc {
+  [[NSNotificationCenter defaultCenter] removeObserver:self];
+}
+
+#pragma mark - Bundle resolution (called from AppDelegate)
+
++ (NSURL *)bundleURL {
+  return [self bundleURLForResource:@"main" withExtension:@"jsbundle"];
+}
+
++ (NSURL *)binaryBundleURL {
+  return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"];
+}
+
++ (NSURL *)bundleURLForResource:(NSString *)resourceName withExtension:(NSString *)extension {
+  static dispatch_once_t onceToken;
+  __block BOOL firstResolutionInProcess = NO;
+  dispatch_once(&onceToken, ^{
+    // The rollback decision belongs to a process start, and only that.
+    firstResolutionInProcess = YES;
+    [[OtaUpdateStore sharedStore] initializeAfterRestart];
+  });
+  if (!firstResolutionInProcess) {
+    // Resolved again without a new process: an in-process reload from an
+    // IMMEDIATE or ON_NEXT_RESUME install. Promote the pending package, but do
+    // not let it look like a boot that failed to confirm.
+    [[OtaUpdateStore sharedStore] promotePendingIfAny];
+  }
+
+  @try {
+    NSString *path = [[OtaUpdateStore sharedStore] currentBundlePath];
+    if (path.length > 0) return [NSURL fileURLWithPath:path];
+  } @catch (NSException *exception) {
+    // Never let OTA state break app start-up.
+    NSLog(@"[OtaUpdate] failed to resolve bundle (%@) — using the binary bundle", exception.reason);
+  }
+  return [[NSBundle mainBundle] URLForResource:resourceName withExtension:extension];
+}
+
+#pragma mark - Configuration
+
+RCT_EXPORT_METHOD(getConfiguration
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  NSDictionary *info = [store packageInfoForHash:store.currentHash];
+  NSDictionary *plist = [[NSBundle mainBundle] infoDictionary];
+
+  resolve(@{
+    @"deploymentKey" : plist[kDeploymentKeyPlist] ?: @"",
+    @"serverUrl" : plist[kServerUrlPlist] ?: @"",
+    @"appVersion" : plist[@"CFBundleShortVersionString"] ?: @"0.0.0",
+    @"clientUniqueId" : [store clientUniqueId],
+    @"packageHash" : store.currentHash ?: [NSNull null],
+    @"label" : info[@"label"] ?: [NSNull null],
+    // Read from the native runtime, not settable from JS — this is what makes
+    // backend bundle-identifier enforcement meaningful.
+    @"bundleIdentifier" : [[NSBundle mainBundle] bundleIdentifier] ?: @"",
+  });
+}
+
+RCT_EXPORT_METHOD(getCurrentPackage
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  NSString *hash = store.currentHash;
+  NSDictionary *info = [store packageInfoForHash:hash];
+  if (!hash || !info) {
+    resolve([NSNull null]);
+    return;
+  }
+
+  NSString *description = info[@"description"];
+  resolve(@{
+    @"packageHash" : hash,
+    @"label" : info[@"label"] ?: @"",
+    @"description" : [description isKindOfClass:[NSString class]] ? description : [NSNull null],
+    @"isMandatory" : info[@"isMandatory"] ?: @NO,
+    @"bundlePath" : info[@"bundlePath"] ?: [NSNull null],
+    @"size" : info[@"size"] ?: @0,
+    @"appVersion" : [[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"] ?: @"",
+    @"isPending" : @([store isPending]),
+    @"isFirstRun" : @(store.isFirstRunOfUpdate),
+  });
+}
+
+RCT_EXPORT_METHOD(isFirstRun
+                  : (NSString *)packageHash resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  resolve(@(store.isFirstRunOfUpdate && [store.currentHash isEqualToString:packageHash]));
+}
+
+#pragma mark - Download
+
+RCT_EXPORT_METHOD(downloadUpdate
+                  : (NSDictionary *)update resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  NSString *downloadUrl = update[@"downloadUrl"];
+  NSString *packageHash = update[@"packageHash"];
+  NSString *label = update[@"label"] ?: @"";
+
+  if (downloadUrl.length == 0 || packageHash.length == 0) {
+    reject(@"ota_invalid_update", @"downloadUrl and packageHash are required", nil);
+    return;
+  }
+
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  __weak __typeof(self) weakSelf = self;
+
+  [OtaUpdateInstaller
+      installUpdateWithStore:store
+                 downloadURL:downloadUrl
+                expectedHash:packageHash
+                    progress:^(long long received, long long total) {
+                      __strong __typeof(weakSelf) self = weakSelf;
+                      if (!self || !self.hasListeners) return;
+                      [self sendEventWithName:kProgressEvent
+                                         body:@{
+                                           @"receivedBytes" : @(received),
+                                           @"totalBytes" : @(total),
+                                         }];
+                    }
+                  completion:^(NSString *bundlePath, long long size, NSError *error) {
+                    if (error || !bundlePath) {
+                      reject(@"ota_download_failed",
+                             error.localizedDescription ?: @"Update download failed", error);
+                      return;
+                    }
+
+                    NSString *description = update[@"description"];
+                    [store recordPackageWithHash:packageHash
+                                           label:label
+                                      bundlePath:bundlePath
+                                     description:[description isKindOfClass:[NSString class]] ? description : nil
+                                     isMandatory:[update[@"isMandatory"] boolValue]
+                                            size:size
+                                      appVersion:[[NSBundle mainBundle] infoDictionary][@"CFBundleShortVersionString"] ?: @""];
+
+                    resolve(@{
+                      @"bundlePath" : bundlePath,
+                      @"packageHash" : packageHash,
+                      @"label" : label,
+                      @"size" : @(size),
+                    });
+                  }];
+}
+
+#pragma mark - Install
+
+RCT_EXPORT_METHOD(installUpdate
+                  : (NSString *)packageHash installMode
+                  : (nonnull NSNumber *)installMode minimumBackgroundDuration
+                  : (nonnull NSNumber *)minimumBackgroundDuration resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  [store markPending:packageHash];
+
+  switch (installMode.integerValue) {
+    case OtaInstallModeImmediate:
+      resolve(nil);
+      [self reload];
+      break;
+    case OtaInstallModeOnNextResume:
+      self.restartOnResume = YES;
+      self.minimumBackgroundDuration = minimumBackgroundDuration.doubleValue;
+      resolve(nil);
+      break;
+    default:
+      // ON_NEXT_RESTART: bundleURL picks it up on the next cold start.
+      resolve(nil);
+      break;
+  }
+}
+
+RCT_EXPORT_METHOD(notifyApplicationReady
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  OtaUpdateStore *store = [OtaUpdateStore sharedStore];
+  [store notifyApplicationReady];
+  // Reclaim disk from superseded packages now that this one is known good.
+  [store pruneOldPackages];
+  resolve(nil);
+}
+
+RCT_EXPORT_METHOD(restartApp
+                  : (BOOL)onlyIfUpdateIsPending resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  if (onlyIfUpdateIsPending && ![[OtaUpdateStore sharedStore] isPending]) {
+    resolve(@NO);
+    return;
+  }
+  resolve(@YES);
+  [self reload];
+}
+
+RCT_EXPORT_METHOD(clearUpdates
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  [[OtaUpdateStore sharedStore] reset];
+  resolve(nil);
+}
+
+- (void)reload {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    // Works under both the bridge and bridgeless runtimes.
+    RCTTriggerReloadCommandListeners(@"OTA update applied");
+  });
+}
+
+#pragma mark - ON_NEXT_RESUME wiring
+
+- (void)applicationDidEnterBackground {
+  self.backgroundedAt = [[NSDate date] timeIntervalSince1970];
+}
+
+- (void)applicationWillEnterForeground {
+  if (!self.restartOnResume || self.backgroundedAt <= 0) return;
+  NSTimeInterval backgroundedFor = [[NSDate date] timeIntervalSince1970] - self.backgroundedAt;
+  if (backgroundedFor >= self.minimumBackgroundDuration) {
+    self.restartOnResume = NO;
+    [self reload];
+  }
+}
+
+@end

package/ios/OtaUpdateInstaller.h

@@ -0,0 +1,25 @@
+#import <Foundation/Foundation.h>
+#import "OtaUpdateStore.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+extern NSString *const OtaUpdateErrorDomain;
+
+/**
+ * Downloads a release zip, verifies its SHA-256 against the value published by
+ * the server, then unzips it. Verification happens before anything is
+ * unpacked, so a corrupt or tampered payload never becomes a runnable bundle.
+ */
+@interface OtaUpdateInstaller : NSObject
+
++ (void)installUpdateWithStore:(OtaUpdateStore *)store
+                   downloadURL:(NSString *)downloadURL
+                  expectedHash:(NSString *)expectedHash
+                      progress:(void (^)(long long received, long long total))progress
+                    completion:(void (^)(NSString *_Nullable bundlePath,
+                                         long long size,
+                                         NSError *_Nullable error))completion;
+
+@end
+
+NS_ASSUME_NONNULL_END