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

package/android/app/src/main/java/com/microsoft/codepush/react/BinaryPatchResult.java

@@ -0,0 +1,64 @@
+package com.microsoft.codepush.react;
+
+/**
+ * Outcome of restoring an update from its binary patch archive.
+ *
+ * A failed result is not an error the user hears about: it is the signal to download the
+ * update's full archive instead. The reason strings are the vocabulary the appliers of
+ * every platform report, and the logs a rollout is judged from are read for exactly these
+ * words, so they must not be reworded.
+ */
+public class BinaryPatchResult {
+
+    /** The bundle inside the app binary could not be opened or read. */
+    public static final String REASON_BASE_BUNDLE_UNAVAILABLE = "base_bundle_unavailable";
+
+    /** The bundle inside the app binary is not the one the patch was computed against. */
+    public static final String REASON_BASE_HASH_MISMATCH = "base_hash_mismatch";
+
+    /** The manifest is missing, malformed, points outside the archive, or asks for too much. */
+    public static final String REASON_INVALID_MANIFEST = "invalid_manifest";
+
+    /** The patch was produced by a format or a codec this client cannot apply. */
+    public static final String REASON_UNSUPPORTED_FORMAT = "unsupported_format";
+
+    /** The applier refused the patch, or the restored bundle could not be written. */
+    public static final String REASON_PATCH_APPLY_FAILED = "patch_apply_failed";
+
+    /** The restored bundle is not the one the manifest promised. */
+    public static final String REASON_TARGET_VERIFICATION_FAILED = "target_verification_failed";
+
+    /**
+     * The update restored from the patch did not pass the checks every update passes before
+     * it is installed - the folder hash above all.
+     *
+     * This one is reported by the caller rather than by the applier: by the time it applies,
+     * the applier has already handed back a bundle it was happy with.
+     */
+    public static final String REASON_PACKAGE_VERIFICATION_FAILED = "package_verification_failed";
+
+    private final boolean mSucceeded;
+    private final String mFailureReason;
+
+    private BinaryPatchResult(boolean succeeded, String failureReason) {
+        mSucceeded = succeeded;
+        mFailureReason = failureReason;
+    }
+
+    public static BinaryPatchResult success() {
+        return new BinaryPatchResult(true, null);
+    }
+
+    public static BinaryPatchResult failure(String failureReason) {
+        return new BinaryPatchResult(false, failureReason);
+    }
+
+    public boolean succeeded() {
+        return mSucceeded;
+    }
+
+    /** Why the full archive has to be downloaded instead, or null when the patch was applied. */
+    public String getFailureReason() {
+        return mFailureReason;
+    }
+}

package/android/app/src/main/java/com/microsoft/codepush/react/CodePush.java

@@ -61,7 +61,7 @@ public class CodePush extends TurboReactPackage {
     private CodePush(Context context, boolean isDebugMode) {
         mContext = context.getApplicationContext();
 
-        mUpdateManager = new CodePushUpdateManager(context.getFilesDir().getAbsolutePath());
+        mUpdateManager = new CodePushUpdateManager(context.getFilesDir().getAbsolutePath(), mContext);
         mTelemetryManager = new CodePushTelemetryManager(mContext);
         mDeploymentKey = "deprecated_deployment_key";
         mIsDebugMode = isDebugMode;

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushBinaryPatch.java

@@ -0,0 +1,293 @@
+package com.microsoft.codepush.react;
+
+import org.json.JSONObject;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+/**
+ * Rebuilds the JS bundle of an update that was downloaded as a binary patch archive.
+ *
+ * A patch archive holds everything the full archive holds except the JS bundle, which it
+ * carries as a patch against the bundle that shipped inside the app binary, plus a
+ * manifest describing how to rebuild it. Restoring means applying that patch, verifying
+ * the result, moving it to where the bundle belongs and deleting the two patch-only
+ * files. What is left is byte for byte the contents of the full archive, so the folder
+ * hash check that follows the install is unchanged and stays the last line of defence.
+ *
+ * Nothing here trusts the patch. Neither the diff format nor the zstd streams inside it
+ * carry a checksum of the data they produce, so an apply that reports success is not
+ * proof of a correct result: a base bundle of the right size but the wrong content, or a
+ * corrupted patch body, both produce wrong bytes without any error. The base bundle is
+ * hashed before the patch is applied and the restored bundle is hashed afterwards, and
+ * the restored bytes only reach the update contents once both checks have passed.
+ *
+ * Every failure is reported as a {@link BinaryPatchResult}, never as an exception: the
+ * caller answers all of them the same way, by downloading the full archive instead.
+ */
+public class CodePushBinaryPatch {
+
+    /** Reads the JS bundle that shipped inside the app binary. */
+    public interface BaseBundleProvider {
+        byte[] readBaseBundle(String bundleFileName) throws IOException;
+    }
+
+    /**
+     * Applies a patch to a base bundle and writes the restored bundle to a file.
+     *
+     * The result codes are the ones the native applier returns, so they have to stay in
+     * step with the codes in the JNI wrapper.
+     */
+    public interface PatchApplier {
+        int RESULT_OK = 0;
+        int RESULT_INVALID_ARGUMENT = 1;
+        int RESULT_IO_ERROR = 2;
+        int RESULT_INVALID_HEADER = 3;
+        int RESULT_UNSUPPORTED_COMPRESSION = 4;
+        int RESULT_SIZE_MISMATCH = 5;
+        int RESULT_APPLY_FAILED = 6;
+        /** Reported by the wrapper itself, when the native library could not be loaded. */
+        int RESULT_LIBRARY_UNAVAILABLE = 7;
+
+        int apply(byte[] base, byte[] patch, String outputPath, long expectedTargetSize);
+    }
+
+    private static final int COPY_BUFFER_SIZE = 1024 * 8;
+
+    private final BaseBundleProvider mBaseBundleProvider;
+    private final PatchApplier mPatchApplier;
+
+    public CodePushBinaryPatch(BaseBundleProvider baseBundleProvider, PatchApplier patchApplier) {
+        mBaseBundleProvider = baseBundleProvider;
+        mPatchApplier = patchApplier;
+    }
+
+    /**
+     * Turns the contents of a downloaded patch archive into the contents of the full one.
+     *
+     * @param unzippedFolderPath   the unzipped archive, which is modified in place
+     * @param workingFolderPath    scratch directory for the restored bundle, emptied before
+     *                             and after the attempt so an interrupted run leaves nothing
+     * @param baseBundleFileName   name of the JS bundle inside the app binary
+     */
+    public BinaryPatchResult restoreBundle(String unzippedFolderPath, String workingFolderPath, String baseBundleFileName) {
+        File contentsFolder = resolveContentsFolder(new File(unzippedFolderPath));
+        File manifestFile = new File(contentsFolder, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME);
+        if (!manifestFile.isFile()) {
+            return BinaryPatchResult.failure(BinaryPatchResult.REASON_INVALID_MANIFEST);
+        }
+
+        JSONObject manifest;
+        try {
+            manifest = CodePushUtils.getJsonObjectFromFile(manifestFile.getAbsolutePath());
+        } catch (IOException | CodePushMalformedDataException e) {
+            CodePushUtils.log(e);
+            return BinaryPatchResult.failure(BinaryPatchResult.REASON_INVALID_MANIFEST);
+        }
+
+        if (manifest.optInt(CodePushConstants.BINARY_PATCH_FORMAT_VERSION_KEY, -1) != CodePushConstants.BINARY_PATCH_FORMAT_VERSION
+                || !CodePushConstants.BINARY_PATCH_ALGORITHM.equals(manifest.optString(CodePushConstants.BINARY_PATCH_ALGORITHM_KEY, null))) {
+            return BinaryPatchResult.failure(BinaryPatchResult.REASON_UNSUPPORTED_FORMAT);
+        }
+
+        File targetBundleFile = resolveInsideFolder(contentsFolder, manifest.optString(CodePushConstants.BINARY_PATCH_BUNDLE_PATH_KEY, null));
+        File patchFile = resolveInsideFolder(contentsFolder, manifest.optString(CodePushConstants.BINARY_PATCH_FILE_KEY, null));
+        String baseBundleHash = manifest.optString(CodePushConstants.BINARY_PATCH_BASE_BUNDLE_HASH_KEY, null);
+        String targetBundleHash = manifest.optString(CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_HASH_KEY, null);
+        long targetBundleSize = manifest.optLong(CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_SIZE_KEY, -1);
+        if (targetBundleFile == null || patchFile == null || !patchFile.isFile()
+                || isNullOrEmpty(baseBundleHash) || isNullOrEmpty(targetBundleHash)
+                || targetBundleSize <= 0 || targetBundleSize > CodePushConstants.BINARY_PATCH_MAX_TARGET_BUNDLE_SIZE) {
+            return BinaryPatchResult.failure(BinaryPatchResult.REASON_INVALID_MANIFEST);
+        }
+
+        // An earlier attempt that was killed while patching leaves its restored bundle behind.
+        FileUtils.deleteDirectoryAtPath(workingFolderPath);
+        File workingFolder = new File(workingFolderPath);
+        if (!workingFolder.mkdirs()) {
+            CodePushUtils.log("Unable to create the binary patch working directory at " + workingFolderPath);
+            return BinaryPatchResult.failure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED);
+        }
+
+        try {
+            if (workingFolder.getUsableSpace() < targetBundleSize) {
+                CodePushUtils.log("Not enough free space to restore a " + targetBundleSize + " byte bundle.");
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED);
+            }
+
+            byte[] baseBundle;
+            try {
+                baseBundle = mBaseBundleProvider.readBaseBundle(baseBundleFileName);
+            } catch (Exception e) {
+                CodePushUtils.log(e);
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_BASE_BUNDLE_UNAVAILABLE);
+            }
+            if (baseBundle == null) {
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_BASE_BUNDLE_UNAVAILABLE);
+            }
+            if (!baseBundleHash.equals(CodePushUpdateUtils.computeHashForBytes(baseBundle))) {
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_BASE_HASH_MISMATCH);
+            }
+
+            byte[] patch;
+            try {
+                patch = readFile(patchFile);
+            } catch (IOException e) {
+                CodePushUtils.log(e);
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED);
+            }
+
+            File restoredBundleFile = new File(workingFolder, CodePushConstants.BINARY_PATCH_TARGET_FILE_NAME);
+            int resultCode = mPatchApplier.apply(baseBundle, patch, restoredBundleFile.getAbsolutePath(), targetBundleSize);
+            if (resultCode != PatchApplier.RESULT_OK) {
+                CodePushUtils.log("The binary patch applier returned " + resultCode + ".");
+                return BinaryPatchResult.failure(reasonForResultCode(resultCode));
+            }
+
+            if (restoredBundleFile.length() != targetBundleSize) {
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED);
+            }
+            String restoredBundleHash;
+            try {
+                restoredBundleHash = CodePushUpdateUtils.computeHashForFile(restoredBundleFile);
+            } catch (IOException e) {
+                CodePushUtils.log(e);
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED);
+            }
+            if (!targetBundleHash.equals(restoredBundleHash)) {
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED);
+            }
+
+            if (!moveFile(restoredBundleFile, targetBundleFile) || !patchFile.delete() || !manifestFile.delete()) {
+                // The contents are half restored, so they must not be installed. The full
+                // archive that follows unzips over them, which is what clears them.
+                CodePushUtils.log("Unable to put the restored bundle in place of the patch.");
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED);
+            }
+
+            return BinaryPatchResult.success();
+        } finally {
+            FileUtils.deleteDirectoryAtPath(workingFolderPath);
+        }
+    }
+
+    /**
+     * Finds the contents root inside an unzipped archive.
+     *
+     * An archive wraps its files in a single directory, and the manifest's paths are
+     * relative to that directory rather than to the archive. An archive whose files are at
+     * the top level is its own contents root, which is how the tooling that unpacks one
+     * reads it too.
+     */
+    private static File resolveContentsFolder(File unzippedFolder) {
+        File[] entries = unzippedFolder.listFiles();
+        if (entries != null && entries.length == 1 && entries[0].isDirectory()) {
+            return entries[0];
+        }
+
+        return unzippedFolder;
+    }
+
+    /**
+     * Resolves a path the manifest points at, refusing anything that would reach outside
+     * the archive - an archive is untrusted input, and its manifest is no more trusted
+     * than its entries.
+     *
+     * @return the resolved file, or null when the path is unusable
+     */
+    private static File resolveInsideFolder(File folder, String relativePath) {
+        if (isNullOrEmpty(relativePath) || new File(relativePath).isAbsolute()) {
+            return null;
+        }
+
+        try {
+            String folderPath = folder.getCanonicalPath() + File.separator;
+            String resolvedPath = new File(folder, relativePath).getCanonicalPath();
+            if (!resolvedPath.startsWith(folderPath)) {
+                return null;
+            }
+
+            return new File(resolvedPath);
+        } catch (IOException e) {
+            CodePushUtils.log(e);
+            return null;
+        }
+    }
+
+    private static String reasonForResultCode(int resultCode) {
+        return resultCode == PatchApplier.RESULT_UNSUPPORTED_COMPRESSION
+                ? BinaryPatchResult.REASON_UNSUPPORTED_FORMAT
+                : BinaryPatchResult.REASON_PATCH_APPLY_FAILED;
+    }
+
+    /** Rename, falling back to a copy for the case where the two paths are on different volumes. */
+    private static boolean moveFile(File sourceFile, File destinationFile) {
+        File destinationFolder = destinationFile.getParentFile();
+        if (destinationFolder != null && !destinationFolder.exists() && !destinationFolder.mkdirs()) {
+            return false;
+        }
+
+        if (sourceFile.renameTo(destinationFile)) {
+            return true;
+        }
+
+        try {
+            copyFile(sourceFile, destinationFile);
+        } catch (IOException e) {
+            CodePushUtils.log(e);
+            return false;
+        }
+
+        return sourceFile.delete();
+    }
+
+    private static void copyFile(File sourceFile, File destinationFile) throws IOException {
+        InputStream input = new FileInputStream(sourceFile);
+        try {
+            OutputStream output = new FileOutputStream(destinationFile);
+            try {
+                byte[] buffer = new byte[COPY_BUFFER_SIZE];
+                int bytesRead;
+                while ((bytesRead = input.read(buffer)) > 0) {
+                    output.write(buffer, 0, bytesRead);
+                }
+            } finally {
+                output.close();
+            }
+        } finally {
+            input.close();
+        }
+    }
+
+    private static byte[] readFile(File file) throws IOException {
+        long fileSize = file.length();
+        if (fileSize <= 0 || fileSize > Integer.MAX_VALUE) {
+            throw new IOException("Cannot read " + file.getAbsolutePath() + ", it is " + fileSize + " bytes long.");
+        }
+
+        byte[] contents = new byte[(int) fileSize];
+        InputStream input = new FileInputStream(file);
+        try {
+            int offset = 0;
+            while (offset < contents.length) {
+                int bytesRead = input.read(contents, offset, contents.length - offset);
+                if (bytesRead < 0) {
+                    throw new IOException("Unexpected end of " + file.getAbsolutePath() + ".");
+                }
+                offset += bytesRead;
+            }
+        } finally {
+            input.close();
+        }
+
+        return contents;
+    }
+
+    private static boolean isNullOrEmpty(String value) {
+        return value == null || value.isEmpty();
+    }
+}

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushConstants.java

@@ -2,6 +2,31 @@ package com.microsoft.codepush.react;
 
 public class CodePushConstants {
     public static final String ASSETS_BUNDLE_PREFIX = "assets://";
+    // The binary patch values below are the client half of the contract the CLI writes
+    // into a patch archive. The CLI is TypeScript, so its constants cannot be imported
+    // here: any change to the manifest it produces has to be repeated in this file.
+    public static final String BINARY_PATCH_ALGORITHM = "hdiffpatch-m-zstd";
+    public static final String BINARY_PATCH_ALGORITHM_KEY = "algorithm";
+    public static final String BINARY_PATCH_BASE_BUNDLE_HASH_KEY = "baseBundleHash";
+    public static final String BINARY_PATCH_BUNDLE_PATH_KEY = "bundlePath";
+    public static final String BINARY_PATCH_DOWNLOAD_URL_KEY = "binaryPatchDownloadUrl";
+    public static final String BINARY_PATCH_FILE_KEY = "patchFile";
+    public static final String BINARY_PATCH_FOLDER_NAME = "binary-patch";
+    public static final int BINARY_PATCH_FORMAT_VERSION = 1;
+    public static final String BINARY_PATCH_FORMAT_VERSION_KEY = "formatVersion";
+    public static final String BINARY_PATCH_MANIFEST_FILE_NAME = "codepush-binary-patch.json";
+    // A manifest asking for a bundle larger than this is treated as malformed rather than
+    // as a reason to reserve that much memory and disk. A large Hermes bundle stays under
+    // 50 MB, and a release that somehow exceeds the bound still installs from its full
+    // archive, so the headroom below is generous enough for the limit to only ever catch
+    // a manifest that is wrong. The other platform's applier holds the same value.
+    public static final long BINARY_PATCH_MAX_TARGET_BUNDLE_SIZE = 128L * 1024 * 1024;
+    // Not part of the CLI's contract: the field a download that tried a patch reports its
+    // outcome under, on the package it resolves with and on no package it stores.
+    public static final String BINARY_PATCH_RESULT_KEY = "binaryPatchResult";
+    public static final String BINARY_PATCH_TARGET_BUNDLE_HASH_KEY = "targetBundleHash";
+    public static final String BINARY_PATCH_TARGET_BUNDLE_SIZE_KEY = "targetBundleSize";
+    public static final String BINARY_PATCH_TARGET_FILE_NAME = "target.bundle";
     public static final String CODE_PUSH_FOLDER_PREFIX = "CodePush";
     public static final String CODE_PUSH_HASH_FILE_NAME = "CodePushHash";
     public static final String CODE_PUSH_OLD_HASH_FILE_NAME = "CodePushHash.json";

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushNativeModule.java

@@ -336,7 +336,7 @@ public class CodePushNativeModule extends NativeCodePushSpec {
             public void run() {
                 try {
                     JSONObject mutableUpdatePackage = CodePushUtils.convertReadableToJsonObject(updatePackage);
-                    mUpdateManager.downloadPackage(mutableUpdatePackage, mCodePush.getAssetsBundleFileName(), new DownloadProgressCallback() {
+                    JSONObject binaryPatchResult = mUpdateManager.downloadPackage(mutableUpdatePackage, mCodePush.getAssetsBundleFileName(), new DownloadProgressCallback() {
                         private volatile boolean hasScheduledNextFrame = false;
                         private volatile DownloadProgress latestDownloadProgress = null;
                         private final DownloadProgressEventDispatcher progressEventDispatcher = new DownloadProgressEventDispatcher(
@@ -384,7 +384,17 @@ public class CodePushNativeModule extends NativeCodePushSpec {
                     });
 
                     JSONObject newPackage = mUpdateManager.getPackage(CodePushUtils.tryGetString(updatePackage, CodePushConstants.PACKAGE_HASH_KEY));
-                    promise.resolve(CodePushUtils.convertJsonObjectToWritable(newPackage));
+                    WritableMap downloadedPackage = CodePushUtils.convertJsonObjectToWritable(newPackage);
+                    if (binaryPatchResult != null) {
+                        // The result describes this download rather than the update, so it is
+                        // put on what this call resolves with and nowhere else: the metadata
+                        // the update manager has already written knows nothing about it, and
+                        // whoever asked for the download decides what the result is worth.
+                        downloadedPackage.putMap(CodePushConstants.BINARY_PATCH_RESULT_KEY,
+                                CodePushUtils.convertJsonObjectToWritable(binaryPatchResult));
+                    }
+
+                    promise.resolve(downloadedPackage);
                 } catch (CodePushInvalidUpdateException e) {
                     CodePushUtils.log(e);
                     mSettingsManager.saveFailedUpdate(CodePushUtils.convertReadableToJsonObject(updatePackage));

package/android/app/src/main/java/com/microsoft/codepush/react/CodePushUpdateManager.java

@@ -1,14 +1,17 @@
 package com.microsoft.codepush.react;
 
+import android.content.Context;
 import android.os.Build;
 
 import org.json.JSONObject;
 
 import java.io.BufferedInputStream;
 import java.io.BufferedOutputStream;
+import java.io.ByteArrayOutputStream;
 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
+import java.io.InputStream;
 import java.net.HttpURLConnection;
 import java.net.MalformedURLException;
 import java.net.URL;
@@ -19,9 +22,15 @@ import javax.net.ssl.HttpsURLConnection;
 public class CodePushUpdateManager {
 
     private String mDocumentsDirectory;
+    private final CodePushBinaryPatch mBinaryPatch;
 
-    public CodePushUpdateManager(String documentsDirectory) {
+    public CodePushUpdateManager(String documentsDirectory, Context context) {
+        this(documentsDirectory, new CodePushBinaryPatch(new AssetsBaseBundleProvider(context), new HDiffPatchNative()));
+    }
+
+    CodePushUpdateManager(String documentsDirectory, CodePushBinaryPatch binaryPatch) {
         mDocumentsDirectory = documentsDirectory;
+        mBinaryPatch = binaryPatch;
     }
 
     private String getDownloadFilePath() {
@@ -32,6 +41,10 @@ public class CodePushUpdateManager {
         return CodePushUtils.appendPathComponent(getCodePushPath(), CodePushConstants.UNZIPPED_FOLDER_NAME);
     }
 
+    private String getBinaryPatchFolderPath() {
+        return CodePushUtils.appendPathComponent(getCodePushPath(), CodePushConstants.BINARY_PATCH_FOLDER_NAME);
+    }
+
     private String getDocumentsDirectory() {
         return mDocumentsDirectory;
     }
@@ -143,8 +156,92 @@ public class CodePushUpdateManager {
         }
     }
 
-    public void downloadPackage(JSONObject updatePackage, String expectedBundleFileName,
-                                DownloadProgressCallback progressCallback) throws IOException {
+    /**
+     * @return what the attempt at installing the update from its binary patch archive ended
+     *         in, or null when the update had no patch archive to attempt. The result belongs
+     *         to this download alone: the metadata written for the update never carries it.
+     */
+    public JSONObject downloadPackage(JSONObject updatePackage, String expectedBundleFileName,
+                                      DownloadProgressCallback progressCallback) throws IOException {
+        // 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.
+        String binaryPatchDownloadUrl = updatePackage.optString(CodePushConstants.BINARY_PATCH_DOWNLOAD_URL_KEY, null);
+        BinaryPatchAttempt patchAttempt = null;
+        if (binaryPatchDownloadUrl != null) {
+            patchAttempt = new BinaryPatchAttempt();
+            if (tryDownloadBinaryPatchPackage(updatePackage, expectedBundleFileName, progressCallback,
+                    binaryPatchDownloadUrl, patchAttempt)) {
+                return patchAttempt.result();
+            }
+        }
+
+        downloadAndInstallPackage(updatePackage, expectedBundleFileName, progressCallback,
+                updatePackage.optString(CodePushConstants.DOWNLOAD_URL_KEY, null), false, null);
+
+        return patchAttempt == null ? null : patchAttempt.result();
+    }
+
+    /**
+     * Installs the update from its binary patch archive.
+     *
+     * Every way this can fail ends the same way, with the update being downloaded in full
+     * instead, so none of them is reported to 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.
+     *
+     * @param patchAttempt records what the attempt ended in, for the caller to hand to
+     *                     whoever asked for the download
+     * @return true when the update was installed, false when the caller has to download the
+     *         full archive instead
+     */
+    private boolean tryDownloadBinaryPatchPackage(JSONObject updatePackage, String expectedBundleFileName,
+                                                  DownloadProgressCallback progressCallback,
+                                                  String binaryPatchDownloadUrl, BinaryPatchAttempt patchAttempt) {
+        try {
+            BinaryPatchResult patchResult = downloadAndInstallPackage(updatePackage, expectedBundleFileName,
+                    progressCallback, binaryPatchDownloadUrl, true, patchAttempt);
+            if (patchResult.succeeded()) {
+                return true;
+            }
+
+            patchAttempt.recordFallback(patchResult.getFailureReason());
+            CodePushUtils.log("Binary patch update failed (" + patchResult.getFailureReason()
+                    + "). Downloading the full update instead.");
+        } catch (Exception | OutOfMemoryError e) {
+            // Applying a patch is the one path that holds a whole bundle in memory, so
+            // running out of it is a failure this has to absorb like any other: by the time
+            // it lands here the arrays are unreachable, and the full archive is downloaded
+            // to disk in chunks rather than held.
+            patchAttempt.recordFallbackAfterError();
+            CodePushUtils.log(e);
+            CodePushUtils.log("The binary patch update could not be completed. Downloading the full update instead.");
+        } finally {
+            FileUtils.deleteDirectoryAtPath(getBinaryPatchFolderPath());
+        }
+
+        return false;
+    }
+
+    /**
+     * Downloads an update from one of its archives and installs it.
+     *
+     * @param isBinaryPatchUpdate 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.
+     * @param patchAttempt the record the patch is timed into, or null for a full download,
+     *                     which has no patch to time
+     * @return the outcome of the patch: a failed result means the update was not installed
+     *         and the caller has to fall back to the full archive. Downloading the full
+     *         archive always succeeds or throws.
+     */
+    BinaryPatchResult downloadAndInstallPackage(JSONObject updatePackage, String expectedBundleFileName,
+                                                DownloadProgressCallback progressCallback,
+                                                String downloadUrlString, boolean isBinaryPatchUpdate,
+                                                BinaryPatchAttempt patchAttempt) throws IOException {
         String newUpdateHash = updatePackage.optString(CodePushConstants.PACKAGE_HASH_KEY, null);
         String newUpdateFolderPath = getPackageFolderPath(newUpdateHash);
         String newUpdateMetadataPath = CodePushUtils.appendPathComponent(newUpdateFolderPath, CodePushConstants.PACKAGE_FILE_NAME);
@@ -154,7 +251,6 @@ public class CodePushUpdateManager {
             FileUtils.deleteDirectoryAtPath(newUpdateFolderPath);
         }
 
-        String downloadUrlString = updatePackage.optString(CodePushConstants.DOWNLOAD_URL_KEY, null);
         HttpURLConnection connection = null;
         BufferedInputStream bin = null;
         FileOutputStream fos = null;
@@ -232,6 +328,21 @@ public class CodePushUpdateManager {
             FileUtils.unzipFile(downloadFile, unzippedFolderPath);
             FileUtils.deleteFileOrFolderSilently(downloadFile);
 
+            // 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) {
+                long patchStartTime = System.currentTimeMillis();
+                BinaryPatchResult patchResult = mBinaryPatch.restoreBundle(unzippedFolderPath,
+                        getBinaryPatchFolderPath(), expectedBundleFileName);
+                if (!patchResult.succeeded()) {
+                    return patchResult;
+                }
+
+                long applyDurationMs = System.currentTimeMillis() - patchStartTime;
+                patchAttempt.recordBundleRestored(applyDurationMs);
+                CodePushUtils.log("Restored the update from its binary patch in " + applyDurationMs + " ms.");
+            }
+
             // Merge contents with current update based on the manifest
             String diffManifestFilePath = CodePushUtils.appendPathComponent(unzippedFolderPath,
                     CodePushConstants.DIFF_MANIFEST_FILE_NAME);
@@ -268,12 +379,22 @@ public class CodePushUpdateManager {
                 CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.RELATIVE_BUNDLE_PATH_KEY, relativeBundlePath);
             }
         } 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.
+                return BinaryPatchResult.failure(BinaryPatchResult.REASON_INVALID_MANIFEST);
+            }
+
             // File is a jsbundle, move it to a folder with the packageHash as its name
             FileUtils.moveFile(downloadFile, newUpdateFolderPath, expectedBundleFileName);
         }
 
         // Save metadata to the folder.
         CodePushUtils.writeJsonToFile(updatePackage, newUpdateMetadataPath);
+
+        return BinaryPatchResult.success();
     }
 
     public void installPackage(JSONObject updatePackage, boolean removePendingUpdate) {
@@ -349,4 +470,38 @@ public class CodePushUpdateManager {
     public void clearUpdates() {
         FileUtils.deleteDirectoryAtPath(getCodePushPath());
     }
+
+    /** Reads the JS bundle that shipped inside the app binary out of the APK's assets. */
+    private static class AssetsBaseBundleProvider implements CodePushBinaryPatch.BaseBundleProvider {
+
+        private final Context mContext;
+
+        AssetsBaseBundleProvider(Context context) {
+            mContext = context;
+        }
+
+        @Override
+        public byte[] readBaseBundle(String bundleFileName) throws IOException {
+            // The bundle is stored uncompressed in the APK, so it is read straight into
+            // memory: a copy on disk would buy nothing and cost the space the restored
+            // bundle needs.
+            InputStream assetStream = mContext.getAssets().open(bundleFileName);
+            try {
+                // An uncompressed asset knows its whole length up front, so the buffer is
+                // sized for it: growing one would repeatedly hold two copies of a bundle
+                // that is already the largest allocation on this path.
+                ByteArrayOutputStream bundleBytes = new ByteArrayOutputStream(
+                        Math.max(assetStream.available(), CodePushConstants.DOWNLOAD_BUFFER_SIZE));
+                byte[] buffer = new byte[CodePushConstants.DOWNLOAD_BUFFER_SIZE];
+                int bytesRead;
+                while ((bytesRead = assetStream.read(buffer)) > 0) {
+                    bundleBytes.write(buffer, 0, bytesRead);
+                }
+
+                return bundleBytes.toByteArray();
+            } finally {
+                assetStream.close();
+            }
+        }
+    }
 }