@bravemobile/react-native-code-push 13.0.0 → 13.1.0-beta.0

package/src/CodePush.test.js

@@ -0,0 +1,382 @@
+/**
+ * A binary patch is announced in the release history and consumed by the native side,
+ * which only ever sees the object handed to `downloadUpdate`. These cases pin that path:
+ * what the release history says, what `checkForUpdate` resolves to, what the native
+ * module is given when the update is downloaded, and what an app that asked to hear how
+ * the patch went is told about it.
+ */
+
+jest.mock('react-native', () => ({
+  Alert: { alert: jest.fn() },
+  AppState: { addEventListener: jest.fn(() => ({ remove: jest.fn() })) },
+  NativeEventEmitter: class NativeEventEmitter {
+    addListener() {
+      return { remove: jest.fn() };
+    }
+  },
+  NativeModules: {},
+  Platform: { OS: 'ios' },
+  TurboModuleRegistry: { get: () => null },
+}));
+
+// The install modes are the ones of the native module the bridge below stands in for.
+const { InstallMode } = require('./native/NativeCodePush');
+
+const BINARY_VERSION = '1.0.0';
+const LABEL = '1.0.1';
+const PACKAGE_HASH = 'a'.repeat(64);
+const DOWNLOAD_URL = 'https://cdn.example.com/full.zip';
+const BINARY_PATCH_DOWNLOAD_URL = 'https://cdn.example.com/full.zip-patch.zip';
+
+/** The release the CLI writes when only the full bundle was published. */
+function fullOnlyRelease() {
+  return {
+    [LABEL]: {
+      enabled: true,
+      mandatory: false,
+      downloadUrl: DOWNLOAD_URL,
+      packageHash: PACKAGE_HASH,
+    },
+  };
+}
+
+/** The release the CLI writes when the update was published with a binary patch too. */
+function patchedRelease() {
+  return {
+    [LABEL]: {
+      ...fullOnlyRelease()[LABEL],
+      binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
+    },
+  };
+}
+
+/**
+ * @param binaryPatchResult what the native side reports the patch attempt ended in, which
+ *        only a download that had a patch to try comes back with.
+ */
+function createNativeBridge({ binaryPatchResult } = {}) {
+  return {
+    addDownloadProgressListener: jest.fn(() => ({ remove: jest.fn() })),
+    downloadUpdate: jest.fn(async (updatePackage) => ({
+      ...updatePackage,
+      ...(binaryPatchResult ? { binaryPatchResult } : {}),
+    })),
+    // No CodePush update is installed, so the app runs the bundle of its binary.
+    getUpdateMetadata: jest.fn(async () => null),
+    isFailedUpdate: jest.fn(async () => false),
+    isFirstRun: jest.fn(async () => false),
+    // The rest of what a full `sync()` reaches for.
+    InstallMode,
+    clearPendingRestart: jest.fn(),
+    getNewStatusReport: jest.fn(async () => null),
+    installUpdate: jest.fn(async () => {}),
+    notifyApplicationReady: jest.fn(async () => {}),
+  };
+}
+
+/**
+ * Loads a fresh copy of the module - the options passed to `codePush()` and the injected
+ * native bridge live on the module itself - configured the way an app configures it: the
+ * decorator registers the app-wide options, and every sync below is one the app asks for.
+ *
+ * @param onBinaryPatchResult a callback the app registers on the decorator, as opposed to
+ *        one it passes to a single `sync()` call.
+ */
+function loadCodePush({ releaseHistory = {}, updateChecker, binaryPatchResult, onBinaryPatchResult } = {}) {
+  jest.resetModules();
+  const CodePush = require('./CodePush');
+  const nativeBridge = createNativeBridge({ binaryPatchResult });
+
+  CodePush.setUpTestDependencies(
+    null,
+    { appVersion: BINARY_VERSION, clientUniqueId: 'test-client-id' },
+    nativeBridge,
+  );
+  CodePush({
+    checkFrequency: CodePush.CheckFrequency.MANUAL,
+    releaseHistoryFetcher: async () => releaseHistory,
+    updateChecker,
+    onBinaryPatchResult,
+  });
+
+  return { CodePush, nativeBridge };
+}
+
+/** The metadata the native module is given, without the functions mixed into the package. */
+function downloadedPackageMetadata(nativeBridge) {
+  expect(nativeBridge.downloadUpdate).toHaveBeenCalledTimes(1);
+  return nativeBridge.downloadUpdate.mock.calls[0][0];
+}
+
+describe('checkForUpdate with a binary patch in the release history', () => {
+  it('carries the patch url into the update and on to the native module', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: patchedRelease() });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage.downloadUrl).toBe(DOWNLOAD_URL);
+    expect(remotePackage.binaryPatchDownloadUrl).toBe(BINARY_PATCH_DOWNLOAD_URL);
+
+    await remotePackage.download();
+
+    expect(downloadedPackageMetadata(nativeBridge)).toMatchObject({
+      downloadUrl: DOWNLOAD_URL,
+      binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
+      label: LABEL,
+      packageHash: PACKAGE_HASH,
+    });
+  });
+
+  it('reads the patch url of the release being installed, not of another one', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: {
+        '1.0.1': {
+          enabled: true,
+          mandatory: false,
+          downloadUrl: 'https://cdn.example.com/older.zip',
+          binaryPatchDownloadUrl: 'https://cdn.example.com/older.zip-patch.zip',
+          packageHash: 'b'.repeat(64),
+        },
+        '1.0.2': {
+          enabled: true,
+          mandatory: false,
+          downloadUrl: DOWNLOAD_URL,
+          binaryPatchDownloadUrl: BINARY_PATCH_DOWNLOAD_URL,
+          packageHash: PACKAGE_HASH,
+        },
+      },
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage.label).toBe('1.0.2');
+    expect(remotePackage.binaryPatchDownloadUrl).toBe(BINARY_PATCH_DOWNLOAD_URL);
+  });
+});
+
+describe('checkForUpdate without a binary patch in the release history', () => {
+  it('leaves the patch url out of the update and of the native metadata', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({ releaseHistory: fullOnlyRelease() });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage.downloadUrl).toBe(DOWNLOAD_URL);
+    expect(remotePackage).not.toHaveProperty('binaryPatchDownloadUrl');
+
+    await remotePackage.download();
+
+    expect(downloadedPackageMetadata(nativeBridge)).not.toHaveProperty('binaryPatchDownloadUrl');
+  });
+
+  it('serves a release history written before binary patches existed', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: {
+        [BINARY_VERSION]: {
+          enabled: true,
+          mandatory: false,
+          downloadUrl: 'https://cdn.example.com/binary.zip',
+          packageHash: 'c'.repeat(64),
+        },
+        [LABEL]: {
+          enabled: true,
+          mandatory: true,
+          downloadUrl: DOWNLOAD_URL,
+          packageHash: PACKAGE_HASH,
+          rollout: 100,
+        },
+      },
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage).toMatchObject({
+      label: LABEL,
+      appVersion: BINARY_VERSION,
+      downloadUrl: DOWNLOAD_URL,
+      packageHash: PACKAGE_HASH,
+      isMandatory: true,
+    });
+    expect(remotePackage).not.toHaveProperty('binaryPatchDownloadUrl');
+  });
+});
+
+describe('checkForUpdate through the deprecated updateChecker', () => {
+  it('carries the patch url of the update check response', async () => {
+    const { CodePush } = loadCodePush({
+      updateChecker: async () => ({
+        update_info: {
+          is_available: true,
+          download_url: DOWNLOAD_URL,
+          binary_patch_download_url: BINARY_PATCH_DOWNLOAD_URL,
+          target_binary_range: BINARY_VERSION,
+          label: LABEL,
+          package_hash: PACKAGE_HASH,
+        },
+      }),
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage.binaryPatchDownloadUrl).toBe(BINARY_PATCH_DOWNLOAD_URL);
+  });
+
+  it('leaves it out when the update check response has none', async () => {
+    const { CodePush } = loadCodePush({
+      updateChecker: async () => ({
+        update_info: {
+          is_available: true,
+          download_url: DOWNLOAD_URL,
+          target_binary_range: BINARY_VERSION,
+          label: LABEL,
+          package_hash: PACKAGE_HASH,
+        },
+      }),
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(remotePackage).not.toHaveProperty('binaryPatchDownloadUrl');
+  });
+});
+
+/**
+ * How a patch attempt went is reported to the app that asked to hear about it, and to
+ * nobody else: it is not part of the update, and an app that asked for nothing gets the
+ * install it always got.
+ */
+describe('the binary patch result of a sync', () => {
+  const APPLIED = { status: 'applied', applyDurationMs: 812 };
+  const FELL_BACK = { status: 'fallback', fallbackReason: 'base_hash_mismatch', applyDurationMs: 1503 };
+
+  /** The metadata the update is installed from, as the native module is given it. */
+  function installedPackageMetadata(nativeBridge) {
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+    return nativeBridge.installUpdate.mock.calls[0][0];
+  }
+
+  it('tells the app the update was installed from its patch, and how long that took', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+    });
+    const onBinaryPatchResult = jest.fn();
+
+    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
+    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, APPLIED);
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it('tells the app why the update came from the full archive instead', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: FELL_BACK,
+    });
+    const onBinaryPatchResult = jest.fn();
+
+    // A patch that could not be applied is not a failed update: the full archive installs.
+    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, FELL_BACK);
+  });
+
+  it('tells the app that registered the callback on the decorator, even about a sync it asked for itself', async () => {
+    const onBinaryPatchResult = jest.fn();
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+      onBinaryPatchResult,
+    });
+
+    // The decorator checks nothing on its own, so this sync is the app's own call.
+    const syncStatus = await CodePush.sync();
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
+    expect(onBinaryPatchResult).toHaveBeenCalledWith(LABEL, APPLIED);
+  });
+
+  it('tells only the callback of the sync call when one was passed to it', async () => {
+    const registeredOnTheDecorator = jest.fn();
+    const passedToTheSyncCall = jest.fn();
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+      onBinaryPatchResult: registeredOnTheDecorator,
+    });
+
+    const syncStatus = await CodePush.sync({ onBinaryPatchResult: passedToTheSyncCall });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(passedToTheSyncCall).toHaveBeenCalledTimes(1);
+    expect(passedToTheSyncCall).toHaveBeenCalledWith(LABEL, APPLIED);
+    expect(registeredOnTheDecorator).not.toHaveBeenCalled();
+  });
+
+  it('says nothing about a download that had no patch to try', async () => {
+    const { CodePush } = loadCodePush({ releaseHistory: fullOnlyRelease() });
+    const onBinaryPatchResult = jest.fn();
+
+    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onBinaryPatchResult).not.toHaveBeenCalled();
+  });
+
+  it('installs the update even when the callback throws', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+    });
+    const onBinaryPatchResult = jest.fn(() => {
+      throw new Error('the telemetry the app sends the result to is down');
+    });
+
+    const syncStatus = await CodePush.sync({ onBinaryPatchResult });
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onBinaryPatchResult).toHaveBeenCalledTimes(1);
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the result out of the package the update is installed from', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+    });
+
+    await CodePush.sync({ onBinaryPatchResult: jest.fn() });
+
+    const installedPackage = installedPackageMetadata(nativeBridge);
+    expect(installedPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
+    expect(installedPackage).not.toHaveProperty('binaryPatchResult');
+  });
+
+  it('installs the same update, without the result, when no callback is registered', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: FELL_BACK,
+    });
+
+    const syncStatus = await CodePush.sync();
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(installedPackageMetadata(nativeBridge)).not.toHaveProperty('binaryPatchResult');
+  });
+
+  it('leaves the result off the package a download resolves with', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      binaryPatchResult: APPLIED,
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+    const localPackage = await remotePackage.download();
+
+    expect(localPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
+    expect(localPackage).not.toHaveProperty('binaryPatchResult');
+  });
+});

package/src/package-mixins.js

@@ -4,7 +4,15 @@
 module.exports = (NativeCodePush) => {
   const remote = () => {
     return {
-      async download(downloadProgressCallback) {
+      /**
+       * @param downloadProgressCallback Called as the archive is received.
+       * @param binaryPatchResultCallback Called with `{ status, fallbackReason?, applyDurationMs }`
+       *        when the update was published with a binary patch, so that the app can observe
+       *        how the patch went. It says nothing about whether the download succeeded - a
+       *        patch that could not be applied is reported here and the update is downloaded
+       *        in full - and it is the only place the result is ever available.
+       */
+      async download(downloadProgressCallback, binaryPatchResultCallback) {
         if (!this.downloadUrl) {
           throw new Error("Cannot download an update without a download url");
         }
@@ -23,7 +31,17 @@ module.exports = (NativeCodePush) => {
           const updatePackageCopy = Object.assign({}, this);
           Object.keys(updatePackageCopy).forEach((key) => (typeof updatePackageCopy[key] === 'function') && delete updatePackageCopy[key]);
 
-          const downloadedPackage = await NativeCodePush.downloadUpdate(updatePackageCopy, !!downloadProgressCallback);
+          const downloadResult = await NativeCodePush.downloadUpdate(updatePackageCopy, !!downloadProgressCallback);
+
+          // The patch result describes the download that just happened, not the update it
+          // delivered, and the package is handed around as the update's metadata from here
+          // on - it is even written back to the native side on install. So the result is
+          // taken off the package and reported on its own, leaving the package exactly what
+          // the native side saved.
+          const { binaryPatchResult, ...downloadedPackage } = downloadResult ?? {};
+          if (binaryPatchResult) {
+            binaryPatchResultCallback?.(binaryPatchResult);
+          }
 
           return { ...downloadedPackage, ...local };
         } finally {

package/typings/react-native-code-push.d.ts

@@ -28,6 +28,12 @@ export interface ReleaseInfo {
     enabled: boolean;
     mandatory: boolean;
     downloadUrl: string;
+    /**
+     * The URL of a binary patch archive built against the JS bundle embedded in the app binary.
+     * It is only present when the release was published together with such a patch, and a client
+     * that cannot use it downloads the full update from `downloadUrl` instead.
+     */
+    binaryPatchDownloadUrl?: string;
     packageHash: string;
     rollout?: number;
 }
@@ -35,6 +41,12 @@ export interface ReleaseInfo {
 // from code-push SDK
 export interface UpdateCheckResponse {
     download_url?: string;
+    /**
+     * The URL of a binary patch archive built against the JS bundle embedded in the app binary.
+     * It is only present when the release was published together with such a patch, and a client
+     * that cannot use it downloads the full update from `download_url` instead.
+     */
+    binary_patch_download_url?: string;
     description?: string;
     is_available: boolean;
     is_disabled?: boolean;
@@ -47,6 +59,50 @@ export interface UpdateCheckResponse {
     is_mandatory?: boolean;
 }
 
+/**
+ * Why an update that was published with a binary patch had to be downloaded in full
+ * instead. These are the words every platform's applier reports, so a rollout can be
+ * judged by them whichever platform it is running on.
+ */
+export type BinaryPatchFallbackReason =
+    /** The bundle inside the app binary could not be opened or read. */
+    | "base_bundle_unavailable"
+    /** The bundle inside the app binary is not the one the patch was computed against. */
+    | "base_hash_mismatch"
+    /** The manifest is missing, malformed, points outside the archive, or asks for too much. */
+    | "invalid_manifest"
+    /** The patch was produced by a format or a codec this client cannot apply. */
+    | "unsupported_format"
+    /** The applier refused the patch, or the restored bundle could not be written. */
+    | "patch_apply_failed"
+    /** The restored bundle is not the one the manifest promised. */
+    | "target_verification_failed"
+    /** The update restored from the patch did not pass the checks that follow the restore. */
+    | "package_verification_failed";
+
+/**
+ * How installing an update from its binary patch archive went.
+ */
+export interface BinaryPatchResult {
+    /**
+     * Whether the update was installed from its patch archive, or had to be downloaded in
+     * full instead. A fallback is not an error: the update is installed either way.
+     */
+    status: "applied" | "fallback";
+
+    /**
+     * Why the full archive had to be downloaded. Absent when the patch was applied, and
+     * also when the attempt ended in an error none of the appliers has a word for.
+     */
+    fallbackReason?: BinaryPatchFallbackReason;
+
+    /**
+     * How long the patch work took, in milliseconds: applying the patch when it was
+     * applied, and the whole attempt when it was given up on.
+     */
+    applyDurationMs: number;
+}
+
 export interface CodePushOptions extends SyncOptions {
     /**
      * The `ignoreFailedUpdates` option is only available as an option for `CodePush.sync()`.
@@ -192,6 +248,14 @@ export interface RemotePackage extends Package {
      * The URL at which the package is available for download.
      */
     downloadUrl: string;
+
+    /**
+     * The URL at which a binary patch archive of this package is available for download.
+     * The patch is built against the JS bundle embedded in the app binary, so it is only
+     * present when the release was published together with one. When it is absent, the
+     * package is downloaded in full from `downloadUrl`.
+     */
+    binaryPatchDownloadUrl?: string;
 }
 
 export interface SyncOptions {
@@ -239,6 +303,19 @@ export interface SyncOptions {
      */
     rollbackRetryOptions?: RollbackRetryOptions;
 
+    /**
+     * An optional callback for observing how an update published with a binary patch was
+     * installed: whether it came from the patch archive, why it did not when it did not, and
+     * how long the patch work took. It is called once per download that had a patch to try,
+     * with the label of the release being installed.
+     *
+     * Purely for observation. The library neither stores the result nor sends it anywhere -
+     * an app that wants it in its telemetry sends it itself - and nothing about the update
+     * depends on the callback: registering none changes nothing, and one that throws is
+     * logged and does not fail the install.
+     */
+    onBinaryPatchResult?: (label: string, result: BinaryPatchResult) => void;
+
     /**
      * Specifies whether to ignore the update if the installation fails.
      * If set to false, the update will be retried when the sync method is called, even if the previous installation attempt failed.