react-native-bspatch 2.0.0 → 3.0.0

package/src/ota/otaMetadata.ts

@@ -6,7 +6,7 @@ const OTA_DIR = `${ReactNativeBlobUtil.fs.dirs.DocumentDir}/ota`;
 const METADATA_PATH = `${OTA_DIR}/metadata.json`;
 const METADATA_TMP_PATH = `${METADATA_PATH}.tmp`;
 
-/** Promise-based lock to prevent concurrent metadata writes (double-tap guard). */
+/** Serializes metadata updates (see updateMetadata). */
 let saveLock: Promise<void> = Promise.resolve();
 
 /**
@@ -47,18 +47,20 @@ export const loadMetadata = async (
 };
 
 /**
- * Persists OTA metadata to the local filesystem.
- *
- * @param metadata - The metadata object to save.
+ * Atomically updates metadata: load → fn → save, serialized with every other
+ * update so a background install and markHealthy can't overwrite each other.
  */
-export const saveMetadata = async (metadata: OtaMetadata): Promise<void> => {
-    // Wait for any in-flight save to complete before starting our own
+export const updateMetadata = async (
+    defaultVersion: number,
+    fn: (metadata: OtaMetadata) => OtaMetadata,
+): Promise<OtaMetadata> => {
     const prevLock = saveLock;
-    let settleFn: (() => void) | undefined;
-    saveLock = new Promise<void>(resolve => { settleFn = resolve; });
+    let release!: () => void;
+    saveLock = new Promise<void>(resolve => (release = resolve));
 
     try {
         await prevLock;
+        const metadata = fn(await loadMetadata(defaultVersion));
         await ensureOtaDir();
         // Write-then-rename so a kill mid-write never leaves truncated JSON
         await ReactNativeBlobUtil.fs.writeFile(
@@ -70,11 +72,12 @@ export const saveMetadata = async (metadata: OtaMetadata): Promise<void> => {
             await ReactNativeBlobUtil.fs.unlink(METADATA_PATH);
         }
         await ReactNativeBlobUtil.fs.mv(METADATA_TMP_PATH, METADATA_PATH);
+        return metadata;
     } catch (e) {
         console.error('[otaMetadata] Failed to save metadata:', e);
         throw new Error(`Failed to save metadata: ${(e as Error).message}`);
     } finally {
-        settleFn!();
+        release();
     }
 };
 
@@ -155,26 +158,33 @@ export const cleanupOldVersions = async (
 };
 
 /**
- * Marks the current session as healthy, indicating a successful boot.
- * This prevents the native bridge from rolling back the version on the next launch.
+ * Marks the running version healthy: the native resolver stops treating its
+ * launches as pending, so it is never rolled back afterwards (crash on first
+ * launch → rollback; crash after a verified launch → app bug, not a bad bundle).
  * Also cleans up obsolete version directories from disk.
  *
  * @param defaultVersion - Base version for metadata lookup fallback.
+ * @param runningVersion - Version loaded at boot. If a background install has
+ *   since switched currentVersion, the new version hasn't run yet and is left pending.
  * @returns The updated metadata.
  */
 export const markHealthy = async (
     defaultVersion: number,
+    runningVersion: number,
     appVersion?: string,
 ): Promise<OtaMetadata> => {
-    const metadata = await loadMetadata(defaultVersion);
-    const updated: OtaMetadata = {
-        ...metadata,
-        // Stamp legacy metadata so the native resolver can detect a store update later
-        appVersion: metadata.appVersion ?? appVersion,
-        lastLaunchSuccessful: true,
-        rollbackCount: 0,
-    };
-    await saveMetadata(updated);
+    const updated = await updateMetadata(defaultVersion, metadata =>
+        metadata.currentVersion !== runningVersion
+            ? metadata
+            : {
+                  ...metadata,
+                  // Stamp legacy metadata so the native resolver can detect a store update later
+                  appVersion: metadata.appVersion ?? appVersion,
+                  lastLaunchSuccessful: true,
+                  rollbackCount: 0,
+                  verifiedVersion: runningVersion,
+              },
+    );
 
     // Garbage collect older versions on disk to free storage
     await cleanupOldVersions(updated, defaultVersion);

package/src/ota/storage/GitHubRawStorage.ts

@@ -3,17 +3,17 @@ import ReactNativeBlobUtil from 'react-native-blob-util';
 import type { OtaConfig, OtaPatch, OtaStorageProvider } from '../types';
 
 /**
- * Storage Provider for fetching OTA updates directly from a GitHub Raw repository.
+ * Storage Provider for any static host with this layout: GitHub raw, a public
+ * Cloudflare R2 bucket (r2.dev or custom domain), S3, a CDN...
  *
  * Direct URL mapping:
  * - Manifest: `${baseUrl}/${baseFolder}/ota_registry.json`
  * - Patch file: `${baseUrl}/${baseFolder}/${appVersion}/${channel}/${filename}`
  * - Assets: `${baseUrl}/${baseFolder}/assets/${hash}.${ext}`
  *
- * NOTE: All manifest/registry fetches include Cache-Control: no-cache and a
- * timestamp query param to bypass GitHub CDN's 5-minute (max-age=300) cache.
- * Asset URLs are content-addressed (hash-named) so they are immutable and
- * intentionally NOT cache-busted.
+ * NOTE: Only the registry is mutable: it is fetched with Cache-Control: no-cache
+ * and a timestamp query param (GitHub's CDN caches for 5 minutes). Bundles,
+ * patches, manifests and assets are never overwritten, so they stay cacheable.
  */
 
 /** Headers to bypass GitHub CDN cache on mutable files (registry, manifests) */
@@ -32,7 +32,9 @@ const normalizeChannel = (channel: string): string => {
 
 export class GitHubRawStorageProvider implements OtaStorageProvider {
     async fetchManifest(config: OtaConfig): Promise<OtaPatch[]> {
-        if (!config.customServer) return config.bundledPatches || [];
+        if (!config.customServer) {
+            throw new Error('[GitHubRawStorage] customServer configuration missing');
+        }
 
         const { baseUrl, channel, baseFolder = 'ota' } = config.customServer;
         const channelName = normalizeChannel(channel);
@@ -69,21 +71,14 @@ export class GitHubRawStorageProvider implements OtaStorageProvider {
             const appGroup = registry?.apps?.[config.appVersion];
             const flavorGroup = appGroup?.flavors?.[channelName];
 
-            if (!flavorGroup?.patches?.length) {
-                return config.bundledPatches || [];
-            }
-
-            return (flavorGroup.patches || []).filter(
+            return (flavorGroup?.patches ?? []).filter(
                 (p: OtaPatch) =>
                     !p.platform ||
                     p.platform.toLowerCase() === Platform.OS.toLowerCase(),
             );
         } catch (error) {
-            console.warn(
-                '[GitHubRawStorage] Manifest fetch error:',
-                (error as Error).message,
-            );
-            return config.bundledPatches || [];
+            // Surface it: "no patches" would report a broken registry as up to date
+            throw new Error(`[GitHubRawStorage] Manifest fetch error: ${(error as Error).message}`);
         }
     }
 
@@ -101,11 +96,8 @@ export class GitHubRawStorageProvider implements OtaStorageProvider {
             : baseUrl;
         const channelName = normalizeChannel(channel);
 
-        // Cache-bust: patch files are versioned by name but GitHub CDN may
-        // serve a stale 404 response for newly uploaded files within 5 min.
-        return bustCache(
-            `${normalizedBaseUrl}/${baseFolder}/${config.appVersion}/${channelName}/${filename}`,
-        );
+        // Versioned names, never overwritten: no cache-bust, so a CDN can cache them
+        return `${normalizedBaseUrl}/${baseFolder}/${config.appVersion}/${channelName}/${filename}`;
     }
 
     async getAssetUrl(

package/src/ota/types.ts

@@ -35,10 +35,8 @@ export type OtaPatch = {
     label: string;
     /** App version this patch belongs to */
     appVersion: string;
-    /** Release tag (legacy, keep for type compatibility) */
-    releaseTag?: string;
-    /** Filename on the server (e.g. "v1-to-v3.patch") */
-    filename: string;
+    /** Patch file on the server; absent on the full-bundle entry (installs `fullBundleUrl`) */
+    filename?: string;
     /** Version the app must be at to apply this patch */
     fromVersion: number;
     /** Version this patch upgrades to */
@@ -49,14 +47,12 @@ export type OtaPatch = {
     bundleHash?: string;
     /** Minimum native app version required (semver) */
     minAppVersion?: string;
-    /** URL for full bundle download (fallback when patch fails) */
+    /** Full bundle file: used when there is no OTA bundle to patch from, or the patch fails */
     fullBundleUrl?: string;
     /** RSA/ECDSA SHA-256 signature (base64) of the patch file */
     signature?: string;
     /** RSA/ECDSA SHA-256 signature (base64) of the resulting bundle */
     bundleSignature?: string;
-    /** Whether this update is mandatory */
-    mandatory?: boolean;
     /** URL to the asset manifest JSON for this version */
     assetManifestUrl?: string;
     /** Target platform for this patch */
@@ -77,15 +73,6 @@ export type OtaAsset = {
     originalPath: string;
 };
 
-export type OtaRemotePatch = {
-    version: number;
-    minAppVersion: string;
-    patchUrl: string;
-    bundleHash: string;
-    baseHash: string;
-    mandatory: boolean;
-};
-
 export type OtaMetadata = {
     currentVersion: number;
     previousVersions: number[];
@@ -95,6 +82,8 @@ export type OtaMetadata = {
     appVersion?: string;
     /** Versions that crashed on boot and were rolled back; never re-applied */
     failedVersions?: number[];
+    /** Last version that launched and rendered successfully; the native resolver never rolls it back */
+    verifiedVersion?: number;
 };
 
 export type OtaMetrics = {
@@ -108,7 +97,6 @@ export type OtaMetrics = {
 export type OtaNetworkStrategy = {
     retry?: number;
     timeoutMs?: number;
-    wifiOnly?: boolean;
 };
 
 export type OtaConfig = {
@@ -116,8 +104,6 @@ export type OtaConfig = {
     appVersion?: string;
     /** Initial version baked into the APK (usually 1) */
     baseAppVersion: number;
-    /** Default patches if manifest fetch fails */
-    bundledPatches?: OtaPatch[];
     /**
      * Allow OTA checks and patch application while React Native is running in
      * development mode (`__DEV__`). Disabled by default for safety.
@@ -126,7 +112,6 @@ export type OtaConfig = {
 
     /** Enterprise configurations */
     updateMode?: OtaUpdateMode;
-    maxRollback?: number;
     network?: OtaNetworkStrategy;
 
     /** Telemetry: structured event callback for analytics */