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

package/ios/CodePush/CodePushPackage.m

@@ -1,4 +1,5 @@
 #import "CodePush.h"
+#import "CodePushBinaryPatch.h"
 #if __has_include(<SSZipArchive/SSZipArchive.h>)
 #import <SSZipArchive/SSZipArchive.h>
 #else
@@ -9,8 +10,18 @@
 
 #pragma mark - Private constants
 
+static NSString *const BinaryPatchDownloadUrlKey = @"binaryPatchDownloadUrl";
+static NSString *const BinaryPatchFolderName = @"binary-patch";
+// The fields of what a download that tried a patch reports back with. They are read by the
+// app that asked for the download and by nothing else, so they never reach a file.
+static NSString *const BinaryPatchResultApplyDurationMsKey = @"applyDurationMs";
+static NSString *const BinaryPatchResultFallbackReasonKey = @"fallbackReason";
+static NSString *const BinaryPatchResultStatusKey = @"status";
+static NSString *const BinaryPatchResultStatusApplied = @"applied";
+static NSString *const BinaryPatchResultStatusFallback = @"fallback";
 static NSString *const DiffManifestFileName = @"hotcodepush.json";
 static NSString *const DownloadFileName = @"download.zip";
+static NSString *const DownloadUrlKey = @"downloadUrl";
 static NSString *const RelativeBundlePathKey = @"bundlePath";
 static NSString *const StatusFile = @"codepush.json";
 static NSString *const UpdateBundleFileName = @"app.jsbundle";
@@ -47,8 +58,136 @@ static NSString *const UnzippedFolderName = @"unzipped";
  expectedBundleFileName:(NSString *)expectedBundleFileName
          operationQueue:(dispatch_queue_t)operationQueue
        progressCallback:(void (^)(long long, long long))progressCallback
-           doneCallback:(void (^)())doneCallback
+           doneCallback:(void (^)(NSDictionary *binaryPatchResult))doneCallback
            failCallback:(void (^)(NSError *err))failCallback
+{
+    void (^downloadFullPackage)(NSDictionary *) = ^(NSDictionary *binaryPatchResult) {
+        [self downloadAndInstallPackage:updatePackage
+                 expectedBundleFileName:expectedBundleFileName
+                         operationQueue:operationQueue
+                            downloadUrl:updatePackage[DownloadUrlKey]
+                    isBinaryPatchUpdate:NO
+                       progressCallback:progressCallback
+                           doneCallback:^{
+                               doneCallback(binaryPatchResult);
+                           }
+                           failCallback:failCallback
+                   patchAppliedCallback:nil
+                  patchFallbackCallback:nil];
+    };
+
+    // A release that was published with a binary patch offers two archives of the same
+    // update. The patch is worth trying because it is a fraction of the size, and the
+    // full archive is always there when it does not work out.
+    NSString *binaryPatchDownloadUrl = updatePackage[BinaryPatchDownloadUrlKey];
+    if (![binaryPatchDownloadUrl isKindOfClass:[NSString class]] || [binaryPatchDownloadUrl length] == 0) {
+        // A download that never had a patch to try has nothing to report about one.
+        return downloadFullPackage(nil);
+    }
+
+    // Every way the patch can fail ends the same way, with the update being downloaded in
+    // full instead, so none of them reaches the caller as an error. The fallback happens
+    // exactly once without anything having to count it: the full archive is downloaded by
+    // a call that is not allowed to take the patch path, so it has no failure of its own
+    // to fall back from.
+    NSDate *patchAttemptStartTime = [NSDate date];
+    // Set once the applier has restored the bundle, which is also what tells a failure
+    // that follows apart from one that came before.
+    __block NSNumber *applyDurationMs = nil;
+    [self downloadAndInstallPackage:updatePackage
+             expectedBundleFileName:expectedBundleFileName
+                     operationQueue:operationQueue
+                        downloadUrl:binaryPatchDownloadUrl
+                isBinaryPatchUpdate:YES
+                   progressCallback:progressCallback
+                       doneCallback:^{
+                           [self deleteBinaryPatchFolder];
+                           doneCallback([self appliedBinaryPatchResult:applyDurationMs]);
+                       }
+                       failCallback:^(NSError *err) {
+                           [self deleteBinaryPatchFolder];
+                           CPLog(@"The binary patch update could not be completed (%@). Downloading the full update instead.", err.localizedDescription);
+                           // An error raised after the bundle was restored is the restored
+                           // update failing the checks every update passes before it is
+                           // installed. Before that point the appliers have no word for what
+                           // happened - the patch archive not being downloadable, say - and
+                           // inventing one here would put a value on the wire that no
+                           // platform reports, so the fallback is reported without a reason.
+                           NSString *failureReason = applyDurationMs == nil
+                               ? nil
+                               : CodePushBinaryPatchReasonPackageVerificationFailed;
+                           downloadFullPackage([self binaryPatchFallbackResult:failureReason
+                                                              attemptStartTime:patchAttemptStartTime]);
+                       }
+               patchAppliedCallback:^(double durationMs) {
+                   applyDurationMs = @(durationMs);
+               }
+              patchFallbackCallback:^(NSString *failureReason) {
+                  [self deleteBinaryPatchFolder];
+                  CPLog(@"Binary patch update failed (%@). Downloading the full update instead.", failureReason);
+                  downloadFullPackage([self binaryPatchFallbackResult:failureReason
+                                                     attemptStartTime:patchAttemptStartTime]);
+              }];
+}
+
+/*
+ * The result of a patch attempt the update was installed from, timed over the apply itself.
+ */
++ (NSDictionary *)appliedBinaryPatchResult:(NSNumber *)applyDurationMs
+{
+    return @{
+        BinaryPatchResultStatusKey: BinaryPatchResultStatusApplied,
+        BinaryPatchResultApplyDurationMsKey: applyDurationMs ?: @0,
+    };
+}
+
+/*
+ * The result of a patch attempt the update had to be downloaded in full after.
+ *
+ * There is no completed apply to time here, so the attempt itself is what is timed: from the
+ * patch archive being asked for to the moment the attempt was given up on. The reason is left
+ * out when the attempt ended in an error none of the appliers has a word for.
+ */
++ (NSDictionary *)binaryPatchFallbackResult:(NSString *)failureReason
+                           attemptStartTime:(NSDate *)attemptStartTime
+{
+    NSMutableDictionary *result = [NSMutableDictionary dictionaryWithDictionary:@{
+        BinaryPatchResultStatusKey: BinaryPatchResultStatusFallback,
+        BinaryPatchResultApplyDurationMsKey: @(round([[NSDate date] timeIntervalSinceDate:attemptStartTime] * 1000)),
+    }];
+    if (failureReason) {
+        result[BinaryPatchResultFallbackReasonKey] = failureReason;
+    }
+
+    return result;
+}
+
+/*
+ * Downloads an update from one of its archives and installs it.
+ *
+ * isBinaryPatchUpdate says whether the archive holds a binary patch of the JS bundle,
+ * which has to be applied before the contents are the update. Only an archive downloaded
+ * from the binary patch URL is treated that way, so an update being downloaded in full
+ * can never end up on the patch path.
+ *
+ * patchAppliedCallback is called with how long the apply took the moment the bundle has
+ * been restored, which is before the update is known to install. It is nil for a full
+ * download, which has no patch to apply.
+ *
+ * patchFallbackCallback is called instead of doneCallback when the patch cannot be
+ * applied: the update was not installed, and the caller has to download the full archive.
+ * It is nil for a full download, which has nothing to fall back to.
+ */
++ (void)downloadAndInstallPackage:(NSDictionary *)updatePackage
+           expectedBundleFileName:(NSString *)expectedBundleFileName
+                   operationQueue:(dispatch_queue_t)operationQueue
+                      downloadUrl:(NSString *)downloadUrl
+              isBinaryPatchUpdate:(BOOL)isBinaryPatchUpdate
+                 progressCallback:(void (^)(long long, long long))progressCallback
+                     doneCallback:(void (^)(void))doneCallback
+                     failCallback:(void (^)(NSError *err))failCallback
+             patchAppliedCallback:(void (^)(double applyDurationMs))patchAppliedCallback
+            patchFallbackCallback:(void (^)(NSString *failureReason))patchFallbackCallback
 {
     NSString *newUpdateHash = updatePackage[@"packageHash"];
     NSString *newUpdateFolderPath = [self getPackageFolderPath:newUpdateHash];
@@ -109,6 +248,24 @@ static NSString *const UnzippedFolderName = @"unzipped";
                                                             nonFailingError = nil;
                                                         }
                                                         
+                                                        // Rebuild the JS bundle the archive only carries a patch of, which leaves the
+                                                        // contents identical to the ones the full archive would have delivered.
+                                                        if (isBinaryPatchUpdate) {
+                                                            NSDate *patchStartTime = [NSDate date];
+                                                            NSString *patchFailureReason = nil;
+                                                            if (![CodePushBinaryPatch restoreBundleInUnzippedFolder:unzippedFolderPath
+                                                                                                     workingFolder:[self getBinaryPatchFolderPath]
+                                                                                                     baseBundleURL:[CodePush binaryBundleURL]
+                                                                                                     failureReason:&patchFailureReason]) {
+                                                                patchFallbackCallback(patchFailureReason);
+                                                                return;
+                                                            }
+
+                                                            double applyDurationMs = round([[NSDate date] timeIntervalSinceDate:patchStartTime] * 1000);
+                                                            CPLog(@"Restored the update from its binary patch in %.0f ms.", applyDurationMs);
+                                                            patchAppliedCallback(applyDurationMs);
+                                                        }
+
                                                         NSString *diffManifestFilePath = [unzippedFolderPath stringByAppendingPathComponent:DiffManifestFileName];
                                                         BOOL isDiffUpdate = [[NSFileManager defaultManager] fileExistsAtPath:diffManifestFilePath];
                                                         
@@ -252,6 +409,15 @@ static NSString *const UnzippedFolderName = @"unzipped";
                                                         }
 
                                                     } else {
+                                                        if (isBinaryPatchUpdate) {
+                                                            // Whatever the patch URL served, it is not a patch archive - an error page
+                                                            // answered with a 200 looks like this too. Moving it into place would
+                                                            // install bytes no hash has ever been checked against, so the full archive
+                                                            // is downloaded instead.
+                                                            patchFallbackCallback(CodePushBinaryPatchReasonInvalidManifest);
+                                                            return;
+                                                        }
+
                                                         [[NSFileManager defaultManager] createDirectoryAtPath:newUpdateFolderPath
                                                                                   withIntermediateDirectories:YES
                                                                                                    attributes:nil
@@ -284,7 +450,22 @@ static NSString *const UnzippedFolderName = @"unzipped";
                                                 
                                                 failCallback:failCallback];
     
-    [downloadHandler download:updatePackage[@"downloadUrl"]];
+    [downloadHandler download:downloadUrl];
+}
+
+/*
+ * Removes what a patch attempt works in, whichever way the attempt ended - and whatever
+ * an attempt that was killed halfway through left there.
+ */
++ (void)deleteBinaryPatchFolder
+{
+    [[NSFileManager defaultManager] removeItemAtPath:[self getBinaryPatchFolderPath]
+                                               error:nil];
+}
+
++ (NSString *)getBinaryPatchFolderPath
+{
+    return [[self getCodePushPath] stringByAppendingPathComponent:BinaryPatchFolderName];
 }
 
 + (NSString *)getCodePushPath

package/ios/CodePush/CodePushUpdateUtils.m

@@ -7,6 +7,9 @@ NSString * const AssetsFolderName = @"assets";
 NSString * const BinaryHashKey = @"CodePushBinaryHash";
 NSString * const ManifestFolderPrefix = @"CodePush";
 
+/* How much of a file is read at a time while hashing it. */
+static const NSUInteger HashChunkSize = 1024 * 8;
+
 /*
  Ignore list for hashing
  */
@@ -95,11 +98,56 @@ NSString * const IgnoreDSStore = @".DS_Store";
 {
     uint8_t digest[CC_SHA256_DIGEST_LENGTH];
     CC_SHA256(inputData.bytes, (CC_LONG)inputData.length, digest);
+    return [self hashStringForDigest:digest];
+}
+
+/*
+ A file is hashed a chunk at a time, so that hashing one costs no more memory than the
+ chunk however large the file is.
+ */
++ (NSString *)computeHashForFileAtPath:(NSString *)filePath
+{
+    NSFileHandle *fileHandle = [NSFileHandle fileHandleForReadingAtPath:filePath];
+    if (!fileHandle) {
+        CPLog(@"Unable to open %@ to hash it.", filePath);
+        return nil;
+    }
+
+    CC_SHA256_CTX context;
+    CC_SHA256_Init(&context);
+
+    while (YES) {
+        @autoreleasepool {
+            NSError *error = nil;
+            NSData *chunk = [fileHandle readDataUpToLength:HashChunkSize error:&error];
+            if (!chunk) {
+                CPLog(@"Unable to read %@ to hash it: %@", filePath, error);
+                [fileHandle closeAndReturnError:nil];
+                return nil;
+            }
+
+            if (chunk.length == 0) {
+                break;
+            }
+
+            CC_SHA256_Update(&context, chunk.bytes, (CC_LONG)chunk.length);
+        }
+    }
+
+    [fileHandle closeAndReturnError:nil];
+
+    uint8_t digest[CC_SHA256_DIGEST_LENGTH];
+    CC_SHA256_Final(digest, &context);
+    return [self hashStringForDigest:digest];
+}
+
++ (NSString *)hashStringForDigest:(const uint8_t *)digest
+{
     NSMutableString* inputHash = [NSMutableString stringWithCapacity:CC_SHA256_DIGEST_LENGTH * 2];
     for (int i = 0; i < CC_SHA256_DIGEST_LENGTH; i++) {
         [inputHash appendFormat:@"%02x", digest[i]];
     }
-    
+
     return inputHash;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bravemobile/react-native-code-push",
-  "version": "13.0.0",
+  "version": "13.1.0-beta.0",
   "description": "React Native plugin for the CodePush service",
   "main": "src/CodePush.js",
   "react-native": "src/CodePush.js",
@@ -42,15 +42,19 @@
     "bin/code-push.js",
     "android",
     "ios",
+    "cpp",
     "cli/dist",
     "cli/**/*.ts",
     "!cli/node_modules",
+    "scripts/export-embedded-bundle.sh",
+    "scripts/binary-patch/build-hdiffpatch.sh",
     "expo",
     "typings",
     "*.podspec",
     "react-native.config.js",
     "app.plugin.js",
     "package.json",
+    "THIRD-PARTY-NOTICES",
     "!ios/build",
     "!android/build",
     "!android/app/build",
@@ -58,6 +62,7 @@
     "!android/gradlew",
     "!android/gradlew.bat",
     "!android/local.properties",
+    "!cpp/binarypatch/host",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__mocks__",
@@ -74,11 +79,13 @@
     "typecheck": "npm run type:src && npm run type:cli && npm run type:scripts && npm run type:e2e",
     "build:cli": "npm run --workspace cli clean && npm run --workspace cli build",
     "prepack": "npm run build:cli",
-    "publish": "npm publish --access=public",
     "eslint": "eslint --quiet .",
-    "jest": "jest src/versioning/* expo/* && npm run --workspace cli test",
+    "jest": "jest src/CodePush.test.js src/versioning/* expo/* && npm run --workspace cli test",
     "e2e": "ts-node --project e2e/tsconfig.json e2e/run.ts"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Soomgo-Mobile/react-native-code-push.git"

package/scripts/binary-patch/build-hdiffpatch.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+#
+# Builds the `hdiffz` / `hpatchz` command line tools that the CodePush CLI uses to
+# generate and verify binary patches, and installs them into `.hdiffpatch-tools/`
+# (git-ignored) at the repository root.
+#
+# The tools are built from source instead of being vendored as prebuilt binaries so
+# that the exact upstream revision is reproducible on every platform and no opaque
+# executable is committed to the repository.
+#
+# The `make` flags below disable every codec except zstd. That keeps the build to a
+# single extra dependency (sisong/zstd, which must sit next to the HDiffPatch clone)
+# and matches the patch format the appliers support: `hdiffz -f -m-6 -c-zstd-21-24`.
+#
+# Usage:
+#   scripts/binary-patch/build-hdiffpatch.sh [--force]
+#
+# Environment:
+#   HDIFFPATCH_TOOLS_DIR  install directory (default: <repo>/.hdiffpatch-tools)
+#
+set -euo pipefail
+
+HDIFFPATCH_REPO="https://github.com/sisong/HDiffPatch.git"
+HDIFFPATCH_TAG="v5.1.3"
+# sisong/zstd is a fork of facebook/zstd that HDiffPatch's makefile expects as a
+# sibling directory. It publishes no release tags, so it is pinned by commit: an
+# unpinned default branch would silently change the generator on any upstream push,
+# and this SHA is the snapshot the vendored decompressor sources came from.
+ZSTD_REPO="https://github.com/sisong/zstd.git"
+ZSTD_COMMIT="68c88c7c7ad22b5e6882a5296ef96d27dc8750c4"
+
+force=0
+for arg in "$@"; do
+  case "$arg" in
+    --force) force=1 ;;
+    *)
+      echo "error: unknown argument: $arg" >&2
+      echo "usage: $0 [--force]" >&2
+      exit 2
+      ;;
+  esac
+done
+
+script_dir=$(cd "$(dirname "$0")" && pwd)
+repo_root=$(cd "$script_dir/../.." && pwd)
+tools_dir="${HDIFFPATCH_TOOLS_DIR:-$repo_root/.hdiffpatch-tools}"
+
+if [ "$force" -eq 0 ] && [ -x "$tools_dir/hdiffz" ] && [ -x "$tools_dir/hpatchz" ]; then
+  echo "hdiffz/hpatchz already present in $tools_dir (pass --force to rebuild)"
+  exit 0
+fi
+
+for tool in git make cc c++; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    echo "error: '$tool' is required to build hdiffz/hpatchz" >&2
+    exit 1
+  fi
+done
+
+work_dir=$(mktemp -d)
+cleanup() { rm -rf "$work_dir"; }
+trap cleanup EXIT
+
+echo "cloning $HDIFFPATCH_REPO @ $HDIFFPATCH_TAG"
+git clone --quiet --depth 1 --branch "$HDIFFPATCH_TAG" "$HDIFFPATCH_REPO" "$work_dir/HDiffPatch"
+echo "cloning $ZSTD_REPO @ $ZSTD_COMMIT"
+# `git clone --branch` does not take a commit, so the pinned commit is fetched into an
+# empty repository instead - still a single-commit download.
+git init --quiet "$work_dir/zstd"
+git -C "$work_dir/zstd" remote add origin "$ZSTD_REPO"
+git -C "$work_dir/zstd" fetch --quiet --depth 1 origin "$ZSTD_COMMIT"
+git -C "$work_dir/zstd" checkout --quiet FETCH_HEAD
+
+jobs=$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)
+echo "building hdiffz/hpatchz (zstd only, $jobs jobs)"
+make -C "$work_dir/HDiffPatch" \
+  BSD=0 LDEF=0 LZMA=0 MD5=0 VCD=0 BZIP2=0 ZLIB=0 ZSTD=1 DIR_DIFF=0 XXH=0 \
+  -j"$jobs"
+
+mkdir -p "$tools_dir"
+cp "$work_dir/HDiffPatch/hdiffz" "$work_dir/HDiffPatch/hpatchz" "$tools_dir/"
+chmod +x "$tools_dir/hdiffz" "$tools_dir/hpatchz"
+
+echo "installed:"
+echo "  $tools_dir/hdiffz"
+echo "  $tools_dir/hpatchz"

package/scripts/export-embedded-bundle.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+#
+# Exports the JS bundle an Xcode build embeds in the app, so a later CodePush release can
+# compute a binary patch against exactly the bytes the store binary ships.
+#
+# Call it at the end of the "Bundle React Native code and images" build phase:
+#
+#     "$SRCROOT/../node_modules/@bravemobile/react-native-code-push/scripts/export-embedded-bundle.sh"
+#
+# The bundle and a `binary-patch-base.json` record describing it land in
+# `$BUILD_DIR/codepush/embedded-bundle/$CONFIGURATION-$PLATFORM_NAME/`. Set
+# CODEPUSH_EXPORT_DIR to export somewhere else; the `$CONFIGURATION-$PLATFORM_NAME`
+# directory is appended to it either way, so builds of different configurations never
+# overwrite each other.
+#
+# Builds that embed no bundle - Debug for the simulator, or any build run with
+# SKIP_BUNDLING - have nothing to export, and the script exits without doing anything.
+
+set -euo pipefail
+
+if [[ -z "${CONFIGURATION_BUILD_DIR:-}" || -z "${UNLOCALIZED_RESOURCES_FOLDER_PATH:-}" || -z "${BUILD_DIR:-}" || -z "${CONFIGURATION:-}" || -z "${PLATFORM_NAME:-}" ]]; then
+    echo "error: export-embedded-bundle.sh must run as an Xcode build phase; the build settings it needs are not set." >&2
+    exit 1
+fi
+
+# The name React Native gives the bundle it writes into the app, which BUNDLE_NAME renames.
+embedded_bundle="$CONFIGURATION_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/${BUNDLE_NAME:-main}.jsbundle"
+
+if [[ ! -f "$embedded_bundle" ]]; then
+    exit 0
+fi
+
+export_dir="${CODEPUSH_EXPORT_DIR:-$BUILD_DIR/codepush/embedded-bundle}/$CONFIGURATION-$PLATFORM_NAME"
+mkdir -p "$export_dir"
+cp "$embedded_bundle" "$export_dir/"
+
+exported_bundle="$export_dir/$(basename "$embedded_bundle")"
+bundle_hash="$(shasum -a 256 "$exported_bundle" | awk '{ print $1 }')"
+
+# Read from the built product rather than the source Info.plist, where the versions are
+# still unexpanded build settings.
+binary_version=""
+build_number=""
+info_plist="$CONFIGURATION_BUILD_DIR/${INFOPLIST_PATH:-}"
+if [[ -n "${INFOPLIST_PATH:-}" && -f "$info_plist" ]]; then
+    binary_version="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$info_plist" 2>/dev/null || true)"
+    build_number="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' "$info_plist" 2>/dev/null || true)"
+fi
+
+# A build outside a git checkout still exports a usable record, just without the commit.
+git_sha="$(git -C "${PROJECT_DIR:-$PWD}" rev-parse HEAD 2>/dev/null || true)"
+
+# Record name and field names are a contract shared with the CodePush CLI
+# (cli/functions/makeBinaryPatchBundle.ts) and the Android export script
+# (android/codepush-export.gradle). Keep the three in step.
+record_json=""
+
+append_field() {
+    local name="$1" value="$2"
+    if [[ -z "$value" ]]; then
+        return 0
+    fi
+    if [[ -n "$record_json" ]]; then
+        record_json+=","$'\n'
+    fi
+    record_json+="  \"$name\": \"$value\""
+}
+
+append_field baseBundleHash "$bundle_hash"
+append_field binaryVersion "$binary_version"
+append_field buildNumber "$build_number"
+append_field gitSha "$git_sha"
+
+printf '{\n%s\n}\n' "$record_json" > "$export_dir/binary-patch-base.json"
+
+echo "CodePush: exported the embedded bundle to $exported_bundle"

package/src/CodePush.js

@@ -181,6 +181,11 @@ async function checkForUpdate(handleBinaryVersionMismatchCallback = null) {
          */
         const updateInfo = {
           download_url: latestReleaseInfo.downloadUrl,
+          /**
+           * Only released updates that were published with a binary patch carry this.
+           * When it is missing, the update is downloaded in full from `download_url`.
+           */
+          binary_patch_download_url: latestReleaseInfo.binaryPatchDownloadUrl,
           // (`enabled` will always be true in the release information obtained from the previous process.)
           is_available: latestReleaseInfo.enabled,
           package_hash: latestReleaseInfo.packageHash,
@@ -234,8 +239,9 @@ async function checkForUpdate(handleBinaryVersionMismatchCallback = null) {
    * 4) The server said there is an update, but the update's hash is the same as that
    *    of the binary's currently running version. This should only happen in Android -
    *    unlike iOS, we don't attach the binary's hash to the updateCheck request
-   *    because we want to avoid having to install diff updates against the binary's
-   *    version, which we can't do yet on Android.
+   *    because an update built against the binary's version does not need one: a
+   *    release published with a binary patch carries the patch archive next to the
+   *    full one, and the client decides for itself which of the two to install.
    */
   if (!update || update.updateAppVersion ||
       localPackage && (update.packageHash === localPackage.packageHash) ||
@@ -281,6 +287,11 @@ function mapToRemotePackageMetadata(updateInfo) {
     packageHash: updateInfo.package_hash ?? '',
     packageSize: updateInfo.package_size ?? 0,
     downloadUrl: updateInfo.download_url ?? '',
+    // The field stays out of the package unless the update really has a binary patch,
+    // so that the native side sees exactly what it saw before patches existed.
+    ...(updateInfo.binary_patch_download_url
+      ? { binaryPatchDownloadUrl: updateInfo.binary_patch_download_url }
+      : {}),
   };
 }
 
@@ -532,9 +543,28 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
     mandatoryInstallMode: CodePush.InstallMode.IMMEDIATE,
     minimumBackgroundDuration: 0,
     updateDialog: null,
+    // The callback registered on the decorator is the default for every sync, including a
+    // manual one; a callback passed to this call overrides it for this call.
+    onBinaryPatchResult: sharedCodePushOptions.onBinaryPatchResult ?? null,
     ...options,
   };
 
+  /*
+   * A callback an app registered to observe how a binary patch went must not be able to
+   * cost it an update, so it is isolated the way the other sync callbacks are: whatever it
+   * throws is logged and the install carries on. An app that registered none leaves the
+   * download exactly as it was before this option existed.
+   */
+  const onBinaryPatchResult = typeof syncOptions.onBinaryPatchResult === "function"
+    ? (label, result) => {
+      try {
+        syncOptions.onBinaryPatchResult(label, result);
+      } catch (error) {
+        log(`An error has occurred : ${error.stack}`);
+      }
+    }
+    : null;
+
   syncStatusChangeCallback = typeof syncStatusChangeCallback === "function"
     ? syncStatusChangeCallback
     : (syncStatus) => {
@@ -586,7 +616,10 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
       syncStatusChangeCallback(CodePush.SyncStatus.DOWNLOADING_PACKAGE);
       sharedCodePushOptions.onDownloadStart?.(remotePackageLabel);
 
-      const localPackage = await remotePackage.download(downloadProgressCallback);
+      const localPackage = await remotePackage.download(
+        downloadProgressCallback,
+        onBinaryPatchResult && ((result) => onBinaryPatchResult(remotePackageLabel, result)),
+      );
 
       sharedCodePushOptions.onDownloadSuccess?.(remotePackageLabel);
 
@@ -720,6 +753,9 @@ let CodePush;
  *
  *   onRolloutSkipped: (label: string, error: Error) => void | undefined,
  *   setOnRolloutSkipped(onRolloutSkippedFunction: (label: string, error: Error) => void | undefined): void,
+ *
+ *   onBinaryPatchResult: (label: string, result: object) => void | undefined,
+ *   setOnBinaryPatchResult(onBinaryPatchResultFunction: (label: string, result: object) => void | undefined): void,
  * }}
  */
 const sharedCodePushOptions = {
@@ -770,6 +806,12 @@ const sharedCodePushOptions = {
     if (typeof onRolloutSkippedFunction !== 'function') throw new Error('Please pass a function to onRolloutSkipped');
     this.onRolloutSkipped = onRolloutSkippedFunction;
   },
+  onBinaryPatchResult: undefined,
+  setOnBinaryPatchResult(onBinaryPatchResultFunction) {
+    if (!onBinaryPatchResultFunction) return;
+    if (typeof onBinaryPatchResultFunction !== 'function') throw new Error('Please pass a function to onBinaryPatchResult');
+    this.onBinaryPatchResult = onBinaryPatchResultFunction;
+  },
 }
 
 function codePushify(options = {}) {
@@ -806,6 +848,7 @@ function codePushify(options = {}) {
   sharedCodePushOptions.setOnDownloadSuccess(options.onDownloadSuccess);
   sharedCodePushOptions.setOnSyncError(options.onSyncError);
   sharedCodePushOptions.setOnRolloutSkipped(options.onRolloutSkipped);
+  sharedCodePushOptions.setOnBinaryPatchResult(options.onBinaryPatchResult);
 
   const decorator = (RootComponent) => {
     class CodePushComponent extends React.Component {