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

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

@@ -86,6 +86,19 @@ public class CodePushUpdateUtils {
         return String.format("%064x", new java.math.BigInteger(1, hash));
     }
 
+    /**
+     * SHA-256 of a single file's bytes, as lowercase hex - the way a binary patch manifest
+     * records the bundle it was computed against and the bundle it produces.
+     */
+    public static String computeHashForFile(File file) throws IOException {
+        return computeHash(new FileInputStream(file));
+    }
+
+    /** SHA-256 of the bytes in memory, in the same form as {@link #computeHashForFile}. */
+    public static String computeHashForBytes(byte[] data) {
+        return computeHash(new ByteArrayInputStream(data));
+    }
+
     public static void copyNecessaryFilesFromCurrentPackage(String diffManifestFilePath, String currentPackageFolderPath, String newPackageFolderPath) throws IOException {
         if (currentPackageFolderPath == null || !new File(currentPackageFolderPath).exists()) {
             CodePushUtils.log("Unable to copy files from current package during diff update, because currentPackageFolderPath is invalid.");

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

@@ -0,0 +1,52 @@
+package com.microsoft.codepush.react;
+
+/**
+ * The native HDiffPatch applier, which is what actually turns the bundle inside the app
+ * binary into the bundle an update wants to run.
+ *
+ * The library is loaded on first use rather than when the class is loaded, and a load
+ * failure is reported as a result code instead of an error: an app whose build did not
+ * produce the library still has to install its updates, it just has to download them in
+ * full.
+ */
+public class HDiffPatchNative implements CodePushBinaryPatch.PatchApplier {
+
+    private static final String LIBRARY_NAME = "codepush-binarypatch";
+
+    private static boolean sLibraryLoadAttempted = false;
+    private static boolean sLibraryLoaded = false;
+
+    @Override
+    public int apply(byte[] base, byte[] patch, String outputPath, long expectedTargetSize) {
+        if (!loadLibrary()) {
+            return RESULT_LIBRARY_UNAVAILABLE;
+        }
+
+        return applyPatch(base, patch, outputPath, expectedTargetSize);
+    }
+
+    private static synchronized boolean loadLibrary() {
+        if (!sLibraryLoadAttempted) {
+            sLibraryLoadAttempted = true;
+            try {
+                System.loadLibrary(LIBRARY_NAME);
+                sLibraryLoaded = true;
+            } catch (UnsatisfiedLinkError e) {
+                CodePushUtils.log("Unable to load the binary patch library: " + e.getMessage());
+            }
+        }
+
+        return sLibraryLoaded;
+    }
+
+    /**
+     * Writes the bundle that `patch` produces from `base` to `outputPath`.
+     *
+     * The base bundle and the patch are passed as arrays because the applier needs random
+     * access to both, while the restored bundle is written straight to a file, so the two
+     * bundles are never in memory at the same time.
+     *
+     * @return one of the RESULT_* codes of {@link CodePushBinaryPatch.PatchApplier}
+     */
+    private static native int applyPatch(byte[] base, byte[] patch, String outputPath, long expectedTargetSize);
+}

package/android/app/src/test/java/com/microsoft/codepush/react/CodePushBinaryPatchTest.java

@@ -0,0 +1,393 @@
+package com.microsoft.codepush.react;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertTrue;
+
+import org.json.JSONObject;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.nio.charset.Charset;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
+
+public class CodePushBinaryPatchTest {
+
+    private static final String BUNDLE_FILE_NAME = "index.android.bundle";
+    private static final String PATCH_FILE_NAME = BUNDLE_FILE_NAME + ".patch";
+
+    private static final byte[] BASE_BUNDLE = bytes("the bundle inside the app binary");
+    private static final byte[] TARGET_BUNDLE = bytes("the bundle the update wants to run");
+    private static final byte[] PATCH = bytes("the difference between the two");
+
+    @Rule
+    public TemporaryFolder mTemporaryFolder = new TemporaryFolder();
+
+    private File mContentsFolder;
+    private File mWorkingFolder;
+    private File mManifestFile;
+    private File mPatchFile;
+    private File mBundleFile;
+
+    @Before
+    public void setUp() throws IOException {
+        mContentsFolder = mTemporaryFolder.newFolder("unzipped");
+        mWorkingFolder = new File(mTemporaryFolder.getRoot(), CodePushConstants.BINARY_PATCH_FOLDER_NAME);
+        mManifestFile = new File(mContentsFolder, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME);
+        mPatchFile = new File(mContentsFolder, PATCH_FILE_NAME);
+        mBundleFile = new File(mContentsFolder, BUNDLE_FILE_NAME);
+
+        writeFile(mPatchFile, PATCH);
+        writeManifest(validManifest());
+    }
+
+    @Test
+    public void appliesAPatchAndLeavesTheContentsOfAFullArchiveBehind() throws IOException {
+        FakePatchApplier applier = new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, TARGET_BUNDLE);
+
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE, applier);
+
+        assertTrue(result.succeeded());
+        assertArrayEquals(TARGET_BUNDLE, readFile(mBundleFile));
+        assertFalse("the patch file is not part of the update", mPatchFile.exists());
+        assertFalse("the manifest is not part of the update", mManifestFile.exists());
+        assertArrayEquals(BASE_BUNDLE, applier.base);
+        assertArrayEquals(PATCH, applier.patch);
+        assertEquals(TARGET_BUNDLE.length, applier.expectedTargetSize);
+        assertNoTemporaryFilesLeft();
+    }
+
+    @Test
+    public void appliesAPatchThatSitsInTheArchivesOwnRootDirectory() throws IOException {
+        // An archive wraps its files in one directory, and the manifest's paths are relative
+        // to that directory rather than to the unzipped archive.
+        File unzippedFolder = mTemporaryFolder.newFolder("archive");
+        File archiveRoot = new File(unzippedFolder, "CodePush");
+        assertTrue(archiveRoot.mkdirs());
+        assertTrue(mManifestFile.renameTo(new File(archiveRoot, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME)));
+        assertTrue(mPatchFile.renameTo(new File(archiveRoot, PATCH_FILE_NAME)));
+
+        BinaryPatchResult result = new CodePushBinaryPatch(providerOf(BASE_BUNDLE), succeedingApplier())
+                .restoreBundle(unzippedFolder.getAbsolutePath(), mWorkingFolder.getAbsolutePath(), BUNDLE_FILE_NAME);
+
+        assertTrue(result.succeeded());
+        assertArrayEquals(TARGET_BUNDLE, readFile(new File(archiveRoot, BUNDLE_FILE_NAME)));
+        assertFalse(new File(archiveRoot, PATCH_FILE_NAME).exists());
+        assertFalse(new File(archiveRoot, CodePushConstants.BINARY_PATCH_MANIFEST_FILE_NAME).exists());
+        assertNoTemporaryFilesLeft();
+    }
+
+    @Test
+    public void removesWhatAnInterruptedAttemptLeftInTheWorkingDirectory() throws IOException {
+        assertTrue(mWorkingFolder.mkdirs());
+        writeFile(new File(mWorkingFolder, CodePushConstants.BINARY_PATCH_TARGET_FILE_NAME), bytes("half a bundle"));
+
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, TARGET_BUNDLE));
+
+        assertTrue(result.succeeded());
+        assertArrayEquals(TARGET_BUNDLE, readFile(mBundleFile));
+        assertNoTemporaryFilesLeft();
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenThereIsNone() {
+        assertTrue(mManifestFile.delete());
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenItIsNotJson() throws IOException {
+        writeFile(mManifestFile, bytes("not json at all"));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnUnsupportedFormatForAnotherFormatVersion() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_FORMAT_VERSION_KEY,
+                CodePushConstants.BINARY_PATCH_FORMAT_VERSION + 1));
+
+        assertFailure(BinaryPatchResult.REASON_UNSUPPORTED_FORMAT, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnUnsupportedFormatForAnotherAlgorithm() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_ALGORITHM_KEY, "bsdiff-bz2"));
+
+        assertFailure(BinaryPatchResult.REASON_UNSUPPORTED_FORMAT, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenTheBundlePathLeavesTheArchive() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_BUNDLE_PATH_KEY,
+                "../" + BUNDLE_FILE_NAME));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+        assertFalse(new File(mTemporaryFolder.getRoot(), BUNDLE_FILE_NAME).exists());
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenThePatchPathLeavesTheArchive() throws IOException {
+        writeFile(new File(mTemporaryFolder.getRoot(), PATCH_FILE_NAME), PATCH);
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_FILE_KEY, "../" + PATCH_FILE_NAME));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenTheBundlePathIsAbsolute() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_BUNDLE_PATH_KEY,
+                new File(mTemporaryFolder.getRoot(), BUNDLE_FILE_NAME).getAbsolutePath()));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenTheArchiveHasNoPatchFile() {
+        assertTrue(mPatchFile.delete());
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenTheTargetSizeIsEmpty() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_SIZE_KEY, 0));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnInvalidManifestWhenTheTargetSizeIsBeyondTheLimit() throws IOException {
+        writeManifest(putValue(validManifest(), CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_SIZE_KEY,
+                CodePushConstants.BINARY_PATCH_MAX_TARGET_BUNDLE_SIZE + 1));
+
+        assertFailure(BinaryPatchResult.REASON_INVALID_MANIFEST, restoreBundle(BASE_BUNDLE, succeedingApplier()));
+    }
+
+    @Test
+    public void reportsAnUnavailableBaseBundleWhenTheBinaryBundleCannotBeRead() {
+        CodePushBinaryPatch binaryPatch = new CodePushBinaryPatch(new CodePushBinaryPatch.BaseBundleProvider() {
+            @Override
+            public byte[] readBaseBundle(String bundleFileName) throws IOException {
+                throw new IOException("no such asset: " + bundleFileName);
+            }
+        }, succeedingApplier());
+
+        assertFailure(BinaryPatchResult.REASON_BASE_BUNDLE_UNAVAILABLE, restoreBundle(binaryPatch));
+    }
+
+    @Test
+    public void reportsABaseHashMismatchWhenTheBinaryHoldsAnotherBundle() {
+        FakePatchApplier applier = new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, TARGET_BUNDLE);
+
+        BinaryPatchResult result = restoreBundle(bytes("a bundle from another app build"), applier);
+
+        assertFailure(BinaryPatchResult.REASON_BASE_HASH_MISMATCH, result);
+        assertEquals("a patch is not applied to a base it was not computed against", 0, applier.invocationCount);
+    }
+
+    @Test
+    public void reportsAnUnsupportedFormatWhenTheApplierRejectsTheCodec() {
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_UNSUPPORTED_COMPRESSION, null));
+
+        assertFailure(BinaryPatchResult.REASON_UNSUPPORTED_FORMAT, result);
+    }
+
+    @Test
+    public void reportsAFailedApplyWhenThePatchHeaderIsCorrupt() {
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_INVALID_HEADER, null));
+
+        assertFailure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED, result);
+        assertNoRestoredBundleInTheContents();
+    }
+
+    @Test
+    public void reportsAFailedApplyWhenTheNativeLibraryIsMissing() {
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_LIBRARY_UNAVAILABLE, null));
+
+        assertFailure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED, result);
+    }
+
+    @Test
+    public void reportsAFailedVerificationWhenTheRestoredBundleHasAnotherSize() {
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, bytes("too short")));
+
+        assertFailure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED, result);
+        assertNoRestoredBundleInTheContents();
+    }
+
+    @Test
+    public void reportsAFailedVerificationWhenTheRestoredBundleHasAnotherContent() {
+        // A corrupted patch body applies without any error and produces wrong bytes, which
+        // only the target hash catches.
+        byte[] wrongBundle = TARGET_BUNDLE.clone();
+        wrongBundle[0] = (byte) (wrongBundle[0] ^ 0xFF);
+
+        BinaryPatchResult result = restoreBundle(BASE_BUNDLE,
+                new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, wrongBundle));
+
+        assertFailure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED, result);
+        assertNoRestoredBundleInTheContents();
+    }
+
+    private BinaryPatchResult restoreBundle(byte[] baseBundle, CodePushBinaryPatch.PatchApplier applier) {
+        return restoreBundle(new CodePushBinaryPatch(providerOf(baseBundle), applier));
+    }
+
+    private BinaryPatchResult restoreBundle(CodePushBinaryPatch binaryPatch) {
+        return binaryPatch.restoreBundle(mContentsFolder.getAbsolutePath(), mWorkingFolder.getAbsolutePath(),
+                BUNDLE_FILE_NAME);
+    }
+
+    private void assertFailure(String expectedReason, BinaryPatchResult result) {
+        assertFalse(result.succeeded());
+        assertEquals(expectedReason, result.getFailureReason());
+        assertNoTemporaryFilesLeft();
+    }
+
+    private void assertNoTemporaryFilesLeft() {
+        assertFalse("the working directory outlived the patch attempt", mWorkingFolder.exists());
+    }
+
+    /** The update must never be installed from bytes that did not pass verification. */
+    private void assertNoRestoredBundleInTheContents() {
+        assertFalse(mBundleFile.exists());
+        assertTrue(mPatchFile.exists());
+        assertTrue(mManifestFile.exists());
+    }
+
+    private JSONObject validManifest() {
+        JSONObject manifest = new JSONObject();
+        putValue(manifest, CodePushConstants.BINARY_PATCH_FORMAT_VERSION_KEY, CodePushConstants.BINARY_PATCH_FORMAT_VERSION);
+        putValue(manifest, CodePushConstants.BINARY_PATCH_ALGORITHM_KEY, CodePushConstants.BINARY_PATCH_ALGORITHM);
+        putValue(manifest, CodePushConstants.BINARY_PATCH_BUNDLE_PATH_KEY, BUNDLE_FILE_NAME);
+        putValue(manifest, CodePushConstants.BINARY_PATCH_FILE_KEY, PATCH_FILE_NAME);
+        putValue(manifest, CodePushConstants.BINARY_PATCH_BASE_BUNDLE_HASH_KEY, sha256(BASE_BUNDLE));
+        putValue(manifest, CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_HASH_KEY, sha256(TARGET_BUNDLE));
+        putValue(manifest, CodePushConstants.BINARY_PATCH_TARGET_BUNDLE_SIZE_KEY, TARGET_BUNDLE.length);
+        return manifest;
+    }
+
+    private static JSONObject putValue(JSONObject manifest, String key, Object value) {
+        CodePushUtils.setJSONValueForKey(manifest, key, value);
+        return manifest;
+    }
+
+    private void writeManifest(JSONObject manifest) throws IOException {
+        writeFile(mManifestFile, bytes(manifest.toString()));
+    }
+
+    private static CodePushBinaryPatch.BaseBundleProvider providerOf(final byte[] baseBundle) {
+        return new CodePushBinaryPatch.BaseBundleProvider() {
+            @Override
+            public byte[] readBaseBundle(String bundleFileName) {
+                assertEquals(BUNDLE_FILE_NAME, bundleFileName);
+                return baseBundle;
+            }
+        };
+    }
+
+    private static CodePushBinaryPatch.PatchApplier succeedingApplier() {
+        return new FakePatchApplier(CodePushBinaryPatch.PatchApplier.RESULT_OK, TARGET_BUNDLE);
+    }
+
+    /** Stands in for the native applier, which is exercised on a device instead. */
+    private static class FakePatchApplier implements CodePushBinaryPatch.PatchApplier {
+
+        private final int mResultCode;
+        private final byte[] mRestoredBundle;
+
+        int invocationCount;
+        byte[] base;
+        byte[] patch;
+        long expectedTargetSize;
+
+        FakePatchApplier(int resultCode, byte[] restoredBundle) {
+            mResultCode = resultCode;
+            mRestoredBundle = restoredBundle;
+        }
+
+        @Override
+        public int apply(byte[] base, byte[] patch, String outputPath, long expectedTargetSize) {
+            this.invocationCount++;
+            this.base = base;
+            this.patch = patch;
+            this.expectedTargetSize = expectedTargetSize;
+
+            if (mRestoredBundle != null) {
+                try {
+                    writeFile(new File(outputPath), mRestoredBundle);
+                } catch (IOException e) {
+                    return RESULT_IO_ERROR;
+                }
+            }
+
+            return mResultCode;
+        }
+    }
+
+    private static void writeFile(File file, byte[] contents) throws IOException {
+        OutputStream output = new FileOutputStream(file);
+        try {
+            output.write(contents);
+        } finally {
+            output.close();
+        }
+    }
+
+    private static byte[] readFile(File file) throws IOException {
+        byte[] contents = new byte[(int) file.length()];
+        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);
+                }
+                offset += bytesRead;
+            }
+        } finally {
+            input.close();
+        }
+
+        return contents;
+    }
+
+    private static byte[] bytes(String text) {
+        return text.getBytes(Charset.forName("UTF-8"));
+    }
+
+    /** Hashes the way a manifest does, without going through the code under test. */
+    private static String sha256(byte[] data) {
+        MessageDigest digest;
+        try {
+            digest = MessageDigest.getInstance("SHA-256");
+        } catch (NoSuchAlgorithmException e) {
+            throw new IllegalStateException(e);
+        }
+
+        StringBuilder hex = new StringBuilder();
+        for (byte hashByte : digest.digest(data)) {
+            hex.append(String.format("%02x", hashByte));
+        }
+
+        return hex.toString();
+    }
+}

package/android/app/src/test/java/com/microsoft/codepush/react/CodePushUpdateManagerBinaryPatchTest.java

@@ -0,0 +1,207 @@
+package com.microsoft.codepush.react;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+import org.json.JSONObject;
+import org.junit.Before;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.rules.TemporaryFolder;
+
+import java.io.File;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Which archive an update is downloaded from, and how the one download that is allowed to
+ * fail falls back to the other one.
+ */
+public class CodePushUpdateManagerBinaryPatchTest {
+
+    private static final String BUNDLE_FILE_NAME = "index.android.bundle";
+    private static final String FULL_ARCHIVE_URL = "https://example.test/updates/full.zip";
+    private static final String PATCH_ARCHIVE_URL = "https://example.test/updates/full.zip-patch.zip";
+    /** Long enough that a timing that wrongly included it could not be mistaken for one that did not. */
+    private static final long FULL_ARCHIVE_DOWNLOAD_DURATION_MS = 300;
+
+    @Rule
+    public TemporaryFolder mTemporaryFolder = new TemporaryFolder();
+
+    private String mDocumentsDirectory;
+    private File mBinaryPatchFolder;
+
+    @Before
+    public void setUp() {
+        mDocumentsDirectory = mTemporaryFolder.getRoot().getAbsolutePath();
+        mBinaryPatchFolder = new File(
+                new File(mDocumentsDirectory, CodePushConstants.CODE_PUSH_FOLDER_PREFIX),
+                CodePushConstants.BINARY_PATCH_FOLDER_NAME);
+    }
+
+    @Test
+    public void downloadsTheFullArchiveWhenTheUpdateHasNoBinaryPatch() throws IOException {
+        RecordingUpdateManager updateManager = new RecordingUpdateManager(mDocumentsDirectory,
+                BinaryPatchResult.success());
+
+        JSONObject patchResult = updateManager.downloadPackage(updatePackage(null), BUNDLE_FILE_NAME, ignoreProgress());
+
+        assertEquals(Arrays.asList(FULL_ARCHIVE_URL), updateManager.downloadedUrls);
+        assertEquals(Arrays.asList(false), updateManager.patchAttempts);
+        assertNull("a download with no patch to try has nothing to report about one", patchResult);
+    }
+
+    @Test
+    public void downloadsOnlyTheBinaryPatchArchiveWhenThePatchApplies() throws IOException {
+        RecordingUpdateManager updateManager = new RecordingUpdateManager(mDocumentsDirectory,
+                BinaryPatchResult.success());
+
+        JSONObject patchResult = updateManager.downloadPackage(updatePackage(PATCH_ARCHIVE_URL), BUNDLE_FILE_NAME,
+                ignoreProgress());
+
+        assertEquals(Arrays.asList(PATCH_ARCHIVE_URL), updateManager.downloadedUrls);
+        assertEquals(Arrays.asList(true), updateManager.patchAttempts);
+        assertEquals("applied", patchResult.optString("status", null));
+    }
+
+    @Test
+    public void fallsBackToTheFullArchiveOnceWhenThePatchCannotBeApplied() throws IOException {
+        RecordingUpdateManager updateManager = new RecordingUpdateManager(mDocumentsDirectory,
+                BinaryPatchResult.failure(BinaryPatchResult.REASON_BASE_HASH_MISMATCH));
+
+        JSONObject patchResult = updateManager.downloadPackage(updatePackage(PATCH_ARCHIVE_URL), BUNDLE_FILE_NAME,
+                ignoreProgress());
+
+        assertEquals(Arrays.asList(PATCH_ARCHIVE_URL, FULL_ARCHIVE_URL), updateManager.downloadedUrls);
+        // The second download is not a patch download, so it has no patch of its own to fail
+        // at: the fallback can only happen the once.
+        assertEquals(Arrays.asList(true, false), updateManager.patchAttempts);
+        assertEquals("fallback", patchResult.optString("status", null));
+        // The reason travels to the app exactly as the applier worded it.
+        assertEquals(BinaryPatchResult.REASON_BASE_HASH_MISMATCH, patchResult.optString("fallbackReason", null));
+    }
+
+    @Test
+    public void fallsBackToTheFullArchiveWhenTheBinaryPatchArchiveCannotBeDownloaded() throws IOException {
+        RecordingUpdateManager updateManager = new RecordingUpdateManager(mDocumentsDirectory, null);
+
+        JSONObject patchResult = updateManager.downloadPackage(updatePackage(PATCH_ARCHIVE_URL), BUNDLE_FILE_NAME,
+                ignoreProgress());
+
+        assertEquals(Arrays.asList(PATCH_ARCHIVE_URL, FULL_ARCHIVE_URL), updateManager.downloadedUrls);
+        assertEquals(Arrays.asList(true, false), updateManager.patchAttempts);
+        assertEquals("fallback", patchResult.optString("status", null));
+        // An archive that could not be downloaded is not something the appliers have a word
+        // for, and no word is invented for it here.
+        assertFalse(patchResult.has("fallbackReason"));
+    }
+
+    @Test
+    public void timesThePatchAttemptRatherThanTheDownloadThatFollowedIt() throws IOException {
+        RecordingUpdateManager updateManager = new RecordingUpdateManager(mDocumentsDirectory,
+                BinaryPatchResult.failure(BinaryPatchResult.REASON_PATCH_APPLY_FAILED));
+        updateManager.fullArchiveDownloadDurationMs = FULL_ARCHIVE_DOWNLOAD_DURATION_MS;
+
+        JSONObject patchResult = updateManager.downloadPackage(updatePackage(PATCH_ARCHIVE_URL), BUNDLE_FILE_NAME,
+                ignoreProgress());
+
+        // The attempt was over before the full archive was even asked for, so what it reports
+        // is time the patch spent and nothing else.
+        long reportedDurationMs = patchResult.optLong("applyDurationMs", -1);
+        assertTrue("the fallback is timed over the download that followed it: " + reportedDurationMs + " ms",
+                reportedDurationMs >= 0 && reportedDurationMs < FULL_ARCHIVE_DOWNLOAD_DURATION_MS);
+    }
+
+    @Test
+    public void removesTheBinaryPatchWorkingDirectoryWhateverTheOutcomeIs() throws IOException {
+        List<BinaryPatchResult> outcomes = Arrays.asList(BinaryPatchResult.success(),
+                BinaryPatchResult.failure(BinaryPatchResult.REASON_TARGET_VERIFICATION_FAILED), null);
+
+        for (BinaryPatchResult outcome : outcomes) {
+            assertTrue(mBinaryPatchFolder.mkdirs());
+            assertTrue(new File(mBinaryPatchFolder, CodePushConstants.BINARY_PATCH_TARGET_FILE_NAME).createNewFile());
+
+            new RecordingUpdateManager(mDocumentsDirectory, outcome)
+                    .downloadPackage(updatePackage(PATCH_ARCHIVE_URL), BUNDLE_FILE_NAME, ignoreProgress());
+
+            assertFalse(mBinaryPatchFolder.exists());
+        }
+    }
+
+    private static JSONObject updatePackage(String binaryPatchDownloadUrl) {
+        JSONObject updatePackage = new JSONObject();
+        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.PACKAGE_HASH_KEY, "package-hash");
+        CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.DOWNLOAD_URL_KEY, FULL_ARCHIVE_URL);
+        if (binaryPatchDownloadUrl != null) {
+            CodePushUtils.setJSONValueForKey(updatePackage, CodePushConstants.BINARY_PATCH_DOWNLOAD_URL_KEY,
+                    binaryPatchDownloadUrl);
+        }
+
+        return updatePackage;
+    }
+
+    private static DownloadProgressCallback ignoreProgress() {
+        return new DownloadProgressCallback() {
+            @Override
+            public void call(DownloadProgress downloadProgress) {
+            }
+        };
+    }
+
+    /**
+     * Records which archive each download went to instead of downloading and installing it.
+     * Downloading is what these cover, so the manager is built without the collaborator that
+     * applies a patch - nothing here reaches it.
+     */
+    private static class RecordingUpdateManager extends CodePushUpdateManager {
+
+        private final BinaryPatchResult mPatchOutcome;
+
+        final List<String> downloadedUrls = new ArrayList<>();
+        final List<Boolean> patchAttempts = new ArrayList<>();
+
+        /** How long the full archive takes to download, for timings that must not include it. */
+        long fullArchiveDownloadDurationMs = 0;
+
+        /** @param patchOutcome what the patch download ends in, or null when it cannot be downloaded */
+        RecordingUpdateManager(String documentsDirectory, BinaryPatchResult patchOutcome) {
+            super(documentsDirectory, (CodePushBinaryPatch) null);
+            mPatchOutcome = patchOutcome;
+        }
+
+        @Override
+        BinaryPatchResult downloadAndInstallPackage(JSONObject updatePackage, String expectedBundleFileName,
+                                                    DownloadProgressCallback progressCallback,
+                                                    String downloadUrlString, boolean isBinaryPatchUpdate,
+                                                    BinaryPatchAttempt patchAttempt) throws IOException {
+            downloadedUrls.add(downloadUrlString);
+            patchAttempts.add(isBinaryPatchUpdate);
+
+            if (!isBinaryPatchUpdate) {
+                sleep(fullArchiveDownloadDurationMs);
+                return BinaryPatchResult.success();
+            }
+            if (mPatchOutcome == null) {
+                throw new IOException("the binary patch archive is not there");
+            }
+
+            return mPatchOutcome;
+        }
+
+        private static void sleep(long durationMs) {
+            if (durationMs <= 0) {
+                return;
+            }
+
+            try {
+                Thread.sleep(durationMs);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+        }
+    }
+}