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

package/cli/commands/buildPatchToolsCommand/buildPatchTools.test.ts

@@ -0,0 +1,118 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import { buildPatchTools, hashBuildScript } from "./buildPatchTools.js";
+
+/**
+ * The command is a thin wrapper around the build script this package ships. What it has
+ * to get right is what it hands the script: the directory the CLI will later look in, and
+ * `--force` when asked. A script that records what it was handed proves both without
+ * cloning and compiling HDiffPatch. The shipped script is run once at the end, against an
+ * install it already finds complete, to show the wrapper speaks its actual interface.
+ */
+
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
+const SHIPPED_BUILD_SCRIPT = path.join(REPO_ROOT, "scripts", "binary-patch", "build-hdiffpatch.sh");
+/** Where `jest.globalSetup.ts` built the tools for this run. */
+const INSTALLED_TOOLS_DIR = process.env.HDIFFPATCH_TOOLS_DIR || path.join(REPO_ROOT, ".hdiffpatch-tools");
+
+let workDir: string;
+
+beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "build-patch-tools-"));
+});
+
+afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+
+function writeScript(body: string): string {
+    const scriptPath = path.join(workDir, "build.sh");
+    fs.writeFileSync(scriptPath, `#!/bin/sh\n${body}\n`, { mode: 0o755 });
+    return scriptPath;
+}
+
+/** A script that writes the install directory it was given, then each argument, one per line. */
+function writeRecordingScript(): string {
+    return writeScript('printf \'%s\\n\' "$HDIFFPATCH_TOOLS_DIR" "$@" > "$HDIFFPATCH_TOOLS_DIR/invocation"');
+}
+
+function readInvocation(toolsDir: string): string[] {
+    return fs.readFileSync(path.join(toolsDir, "invocation"), "utf8").trimEnd().split("\n");
+}
+
+describe("buildPatchTools", () => {
+    it("runs the build script against the tools directory it was given, without forcing a rebuild", () => {
+        const toolsDir = path.join(workDir, "tools");
+        fs.mkdirSync(toolsDir);
+
+        buildPatchTools({ buildScriptPath: writeRecordingScript(), toolsDir, force: false });
+
+        expect(readInvocation(toolsDir)).toEqual([toolsDir]);
+    });
+
+    it("asks the build script to rebuild when forced", () => {
+        const toolsDir = path.join(workDir, "tools");
+        fs.mkdirSync(toolsDir);
+
+        buildPatchTools({ buildScriptPath: writeRecordingScript(), toolsDir, force: true });
+
+        expect(readInvocation(toolsDir)).toEqual([toolsDir, "--force"]);
+    });
+
+    it("fails with the exit code when the build script fails", () => {
+        const buildScriptPath = writeScript("exit 3");
+
+        expect(() => buildPatchTools({ buildScriptPath, toolsDir: workDir, force: false })).toThrow(/exit code 3/);
+    });
+
+    it("fails naming the script when it cannot be started", () => {
+        const buildScriptPath = path.join(workDir, "no-such-script.sh");
+
+        expect(() => buildPatchTools({ buildScriptPath, toolsDir: workDir, force: false })).toThrow(
+            /no-such-script\.sh/,
+        );
+    });
+
+    it("succeeds against an install the shipped script already finds complete", () => {
+        // Without an install the shipped script clones and compiles for minutes, and
+        // `spawnSync` holds the worker past any jest timeout. `jest.globalSetup.ts`
+        // provides the install; this says so when it did not.
+        const missing = ["hdiffz", "hpatchz"].filter((tool) => !fs.existsSync(path.join(INSTALLED_TOOLS_DIR, tool)));
+        if (missing.length > 0) {
+            throw new Error(
+                `${missing.join(", ")} not installed in ${INSTALLED_TOOLS_DIR}: jest.globalSetup.ts should have built the tools first`,
+            );
+        }
+
+        expect(() =>
+            buildPatchTools({ buildScriptPath: SHIPPED_BUILD_SCRIPT, toolsDir: INSTALLED_TOOLS_DIR, force: false }),
+        ).not.toThrow();
+    });
+});
+
+/**
+ * A CI cache of the installed tools is keyed by this hash, so it has to stay the same for as
+ * long as the script would build the same tools, and change as soon as it would not.
+ */
+describe("hashBuildScript", () => {
+    it("hashes two scripts with the same contents to the same hex digest", () => {
+        const first = path.join(workDir, "first.sh");
+        const second = path.join(workDir, "second.sh");
+        fs.writeFileSync(first, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+        fs.writeFileSync(second, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+
+        expect(hashBuildScript(first)).toBe(hashBuildScript(second));
+        expect(hashBuildScript(first)).toMatch(/^[0-9a-f]{64}$/);
+    });
+
+    it("hashes a script whose pinned version changed to a different value", () => {
+        const before = path.join(workDir, "before.sh");
+        const after = path.join(workDir, "after.sh");
+        fs.writeFileSync(before, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+        fs.writeFileSync(after, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.4\n");
+
+        expect(hashBuildScript(after)).not.toBe(hashBuildScript(before));
+    });
+});

package/cli/commands/buildPatchToolsCommand/buildPatchTools.ts

@@ -0,0 +1,46 @@
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { TOOLS_DIR_ENV_NAME } from "../../utils/binaryPatch.js";
+
+interface BuildPatchToolsOptions {
+    /** The `build-hdiffpatch.sh` this package ships. */
+    buildScriptPath: string;
+    /** Where the script installs `hdiffz` and `hpatchz`. It has to be a place the CLI looks in. */
+    toolsDir: string;
+    /** Rebuild even when both tools are already there. */
+    force: boolean;
+}
+
+/**
+ * Runs the build script with the install directory the caller chose.
+ *
+ * The script's output goes straight to the terminal: a first build clones and compiles
+ * HDiffPatch, which takes minutes, and a silent wait would look like a hang. So when the
+ * script fails, its own message has already been shown, and the error raised here only
+ * has to say that it did.
+ */
+export function buildPatchTools({ buildScriptPath, toolsDir, force }: BuildPatchToolsOptions): void {
+    const result = spawnSync(buildScriptPath, force ? ['--force'] : [], {
+        stdio: 'inherit',
+        env: { ...process.env, [TOOLS_DIR_ENV_NAME]: toolsDir },
+    });
+
+    if (result.error) {
+        throw new Error(`failed to run ${buildScriptPath}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const reason = result.status === null ? `signal ${result.signal}` : `exit code ${result.status}`;
+        throw new Error(`${path.basename(buildScriptPath)} failed with ${reason}`);
+    }
+}
+
+/**
+ * SHA-256 of the build script's bytes, for keying a CI cache of the installed tools. The
+ * script pins the sources and the build flags, so it changes whenever the tools it would
+ * build do.
+ */
+export function hashBuildScript(buildScriptPath: string): string {
+    return crypto.createHash('sha256').update(fs.readFileSync(buildScriptPath)).digest('hex');
+}

package/cli/commands/buildPatchToolsCommand/index.ts

@@ -0,0 +1,44 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import { program } from "commander";
+import { TOOLS_DIR_ENV_NAME, TOOLS_DIR_NAME } from "../../utils/binaryPatch.js";
+import { buildPatchTools, hashBuildScript } from "./buildPatchTools.js";
+
+type Options = {
+    toolsDir: string;
+    force: boolean;
+    printHash: boolean;
+}
+
+/**
+ * The CLI runs compiled, from `cli/dist/commands/buildPatchToolsCommand/`, which puts the
+ * package root - and the script shipped under it - four levels up.
+ */
+const BUILD_SCRIPT_PATH = fileURLToPath(
+    new URL("../../../../scripts/binary-patch/build-hdiffpatch.sh", import.meta.url),
+);
+
+/**
+ * Installs where `release` will look: `HDIFFPATCH_TOOLS_DIR` when it is set, and otherwise
+ * a `.hdiffpatch-tools` directory in the working directory, the first place the lookup
+ * checks before walking up.
+ */
+const DEFAULT_TOOLS_DIR = process.env[TOOLS_DIR_ENV_NAME] || path.resolve(process.cwd(), TOOLS_DIR_NAME);
+
+program.command('build-patch-tools')
+    .description('Builds hdiffz and hpatchz from source and installs them where `release --binary-bundle-path` looks for them.\nThe build clones the pinned HDiffPatch sources, so it needs git, make, a C/C++ compiler and network access. It does nothing when the tools are already installed.')
+    .option('--tools-dir <path>', 'directory to install the tools into', DEFAULT_TOOLS_DIR)
+    .option('--force', 'rebuild even when the tools are already installed', false)
+    .option('--print-hash', 'print a hash of the build script, for keying a CI cache of the tools, and exit without building', false)
+    .action((options: Options) => {
+        if (options.printHash) {
+            console.log(hashBuildScript(BUILD_SCRIPT_PATH));
+            return;
+        }
+
+        buildPatchTools({
+            buildScriptPath: BUILD_SCRIPT_PATH,
+            toolsDir: path.resolve(options.toolsDir),
+            force: options.force,
+        });
+    });

package/cli/dist/commands/buildPatchToolsCommand/buildPatchTools.js

@@ -0,0 +1,34 @@
+import { spawnSync } from "child_process";
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { TOOLS_DIR_ENV_NAME } from "../../utils/binaryPatch.js";
+/**
+ * Runs the build script with the install directory the caller chose.
+ *
+ * The script's output goes straight to the terminal: a first build clones and compiles
+ * HDiffPatch, which takes minutes, and a silent wait would look like a hang. So when the
+ * script fails, its own message has already been shown, and the error raised here only
+ * has to say that it did.
+ */
+export function buildPatchTools({ buildScriptPath, toolsDir, force }) {
+    const result = spawnSync(buildScriptPath, force ? ['--force'] : [], {
+        stdio: 'inherit',
+        env: { ...process.env, [TOOLS_DIR_ENV_NAME]: toolsDir },
+    });
+    if (result.error) {
+        throw new Error(`failed to run ${buildScriptPath}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const reason = result.status === null ? `signal ${result.signal}` : `exit code ${result.status}`;
+        throw new Error(`${path.basename(buildScriptPath)} failed with ${reason}`);
+    }
+}
+/**
+ * SHA-256 of the build script's bytes, for keying a CI cache of the installed tools. The
+ * script pins the sources and the build flags, so it changes whenever the tools it would
+ * build do.
+ */
+export function hashBuildScript(buildScriptPath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(buildScriptPath)).digest('hex');
+}

package/cli/dist/commands/buildPatchToolsCommand/buildPatchTools.test.js

@@ -0,0 +1,88 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "@jest/globals";
+import { buildPatchTools, hashBuildScript } from "./buildPatchTools.js";
+/**
+ * The command is a thin wrapper around the build script this package ships. What it has
+ * to get right is what it hands the script: the directory the CLI will later look in, and
+ * `--force` when asked. A script that records what it was handed proves both without
+ * cloning and compiling HDiffPatch. The shipped script is run once at the end, against an
+ * install it already finds complete, to show the wrapper speaks its actual interface.
+ */
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..");
+const SHIPPED_BUILD_SCRIPT = path.join(REPO_ROOT, "scripts", "binary-patch", "build-hdiffpatch.sh");
+/** Where `jest.globalSetup.ts` built the tools for this run. */
+const INSTALLED_TOOLS_DIR = process.env.HDIFFPATCH_TOOLS_DIR || path.join(REPO_ROOT, ".hdiffpatch-tools");
+let workDir;
+beforeEach(() => {
+    workDir = fs.mkdtempSync(path.join(os.tmpdir(), "build-patch-tools-"));
+});
+afterEach(() => {
+    fs.rmSync(workDir, { recursive: true, force: true });
+});
+function writeScript(body) {
+    const scriptPath = path.join(workDir, "build.sh");
+    fs.writeFileSync(scriptPath, `#!/bin/sh\n${body}\n`, { mode: 0o755 });
+    return scriptPath;
+}
+/** A script that writes the install directory it was given, then each argument, one per line. */
+function writeRecordingScript() {
+    return writeScript('printf \'%s\\n\' "$HDIFFPATCH_TOOLS_DIR" "$@" > "$HDIFFPATCH_TOOLS_DIR/invocation"');
+}
+function readInvocation(toolsDir) {
+    return fs.readFileSync(path.join(toolsDir, "invocation"), "utf8").trimEnd().split("\n");
+}
+describe("buildPatchTools", () => {
+    it("runs the build script against the tools directory it was given, without forcing a rebuild", () => {
+        const toolsDir = path.join(workDir, "tools");
+        fs.mkdirSync(toolsDir);
+        buildPatchTools({ buildScriptPath: writeRecordingScript(), toolsDir, force: false });
+        expect(readInvocation(toolsDir)).toEqual([toolsDir]);
+    });
+    it("asks the build script to rebuild when forced", () => {
+        const toolsDir = path.join(workDir, "tools");
+        fs.mkdirSync(toolsDir);
+        buildPatchTools({ buildScriptPath: writeRecordingScript(), toolsDir, force: true });
+        expect(readInvocation(toolsDir)).toEqual([toolsDir, "--force"]);
+    });
+    it("fails with the exit code when the build script fails", () => {
+        const buildScriptPath = writeScript("exit 3");
+        expect(() => buildPatchTools({ buildScriptPath, toolsDir: workDir, force: false })).toThrow(/exit code 3/);
+    });
+    it("fails naming the script when it cannot be started", () => {
+        const buildScriptPath = path.join(workDir, "no-such-script.sh");
+        expect(() => buildPatchTools({ buildScriptPath, toolsDir: workDir, force: false })).toThrow(/no-such-script\.sh/);
+    });
+    it("succeeds against an install the shipped script already finds complete", () => {
+        // Without an install the shipped script clones and compiles for minutes, and
+        // `spawnSync` holds the worker past any jest timeout. `jest.globalSetup.ts`
+        // provides the install; this says so when it did not.
+        const missing = ["hdiffz", "hpatchz"].filter((tool) => !fs.existsSync(path.join(INSTALLED_TOOLS_DIR, tool)));
+        if (missing.length > 0) {
+            throw new Error(`${missing.join(", ")} not installed in ${INSTALLED_TOOLS_DIR}: jest.globalSetup.ts should have built the tools first`);
+        }
+        expect(() => buildPatchTools({ buildScriptPath: SHIPPED_BUILD_SCRIPT, toolsDir: INSTALLED_TOOLS_DIR, force: false })).not.toThrow();
+    });
+});
+/**
+ * A CI cache of the installed tools is keyed by this hash, so it has to stay the same for as
+ * long as the script would build the same tools, and change as soon as it would not.
+ */
+describe("hashBuildScript", () => {
+    it("hashes two scripts with the same contents to the same hex digest", () => {
+        const first = path.join(workDir, "first.sh");
+        const second = path.join(workDir, "second.sh");
+        fs.writeFileSync(first, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+        fs.writeFileSync(second, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+        expect(hashBuildScript(first)).toBe(hashBuildScript(second));
+        expect(hashBuildScript(first)).toMatch(/^[0-9a-f]{64}$/);
+    });
+    it("hashes a script whose pinned version changed to a different value", () => {
+        const before = path.join(workDir, "before.sh");
+        const after = path.join(workDir, "after.sh");
+        fs.writeFileSync(before, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.3\n");
+        fs.writeFileSync(after, "#!/bin/sh\nHDIFFPATCH_TAG=v5.1.4\n");
+        expect(hashBuildScript(after)).not.toBe(hashBuildScript(before));
+    });
+});

package/cli/dist/commands/buildPatchToolsCommand/index.js

@@ -0,0 +1,32 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import { program } from "commander";
+import { TOOLS_DIR_ENV_NAME, TOOLS_DIR_NAME } from "../../utils/binaryPatch.js";
+import { buildPatchTools, hashBuildScript } from "./buildPatchTools.js";
+/**
+ * The CLI runs compiled, from `cli/dist/commands/buildPatchToolsCommand/`, which puts the
+ * package root - and the script shipped under it - four levels up.
+ */
+const BUILD_SCRIPT_PATH = fileURLToPath(new URL("../../../../scripts/binary-patch/build-hdiffpatch.sh", import.meta.url));
+/**
+ * Installs where `release` will look: `HDIFFPATCH_TOOLS_DIR` when it is set, and otherwise
+ * a `.hdiffpatch-tools` directory in the working directory, the first place the lookup
+ * checks before walking up.
+ */
+const DEFAULT_TOOLS_DIR = process.env[TOOLS_DIR_ENV_NAME] || path.resolve(process.cwd(), TOOLS_DIR_NAME);
+program.command('build-patch-tools')
+    .description('Builds hdiffz and hpatchz from source and installs them where `release --binary-bundle-path` looks for them.\nThe build clones the pinned HDiffPatch sources, so it needs git, make, a C/C++ compiler and network access. It does nothing when the tools are already installed.')
+    .option('--tools-dir <path>', 'directory to install the tools into', DEFAULT_TOOLS_DIR)
+    .option('--force', 'rebuild even when the tools are already installed', false)
+    .option('--print-hash', 'print a hash of the build script, for keying a CI cache of the tools, and exit without building', false)
+    .action((options) => {
+    if (options.printHash) {
+        console.log(hashBuildScript(BUILD_SCRIPT_PATH));
+        return;
+    }
+    buildPatchTools({
+        buildScriptPath: BUILD_SCRIPT_PATH,
+        toolsDir: path.resolve(options.toolsDir),
+        force: options.force,
+    });
+});

package/cli/dist/index.js

@@ -26,6 +26,10 @@ import "./commands/showHistoryCommand/index.js";
  * npx code-push init
  */
 import "./commands/initCommand/index.js";
+/**
+ * npx code-push build-patch-tools
+ */
+import "./commands/buildPatchToolsCommand/index.js";
 shell.set("-e");
 shell.set("+v");
 program

package/cli/dist/utils/binaryPatch.js

@@ -31,14 +31,17 @@ export const BINARY_PATCH_ALGORITHM = 'hdiffpatch-m-zstd';
 export const BINARY_PATCH_FORMAT_VERSION = 1;
 const HDIFFZ_OPTIONS = ['-f', '-m-6', '-c-zstd-21-24'];
 const HPATCHZ_OPTIONS = ['-f', '-m'];
-const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
-const TOOLS_DIR_NAME = '.hdiffpatch-tools';
-const BUILD_SCRIPT_PATH = 'scripts/binary-patch/build-hdiffpatch.sh';
+export const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
+export const TOOLS_DIR_NAME = '.hdiffpatch-tools';
+const BUILD_COMMAND = 'npx code-push build-patch-tools';
 /**
  * Finds the hdiffz/hpatchz executable, looking at `HDIFFPATCH_TOOLS_DIR` first and
  * then at a `.hdiffpatch-tools` directory in the working directory or any directory
  * above it. The tools are built from source rather than installed as a package
  * dependency, so the error explains how to get them.
+ *
+ * `build-patch-tools` (`cli/commands/buildPatchToolsCommand/index.ts`) installs into the
+ * first place this looks; a change to the lookup order has to be mirrored there.
  */
 export function resolveBinaryPatchTool(tool) {
     const configuredDir = process.env[TOOLS_DIR_ENV_NAME];
@@ -48,7 +51,7 @@ export function resolveBinaryPatchTool(tool) {
             return configured;
         }
         throw new Error(`${TOOLS_DIR_ENV_NAME} is set to '${configuredDir}' but it does not contain '${tool}'. ` +
-            `Build the tools with '${BUILD_SCRIPT_PATH}'.`);
+            `Build the tools with '${BUILD_COMMAND}'.`);
     }
     let directory = path.resolve(process.cwd());
     for (;;) {
@@ -63,7 +66,7 @@ export function resolveBinaryPatchTool(tool) {
         directory = parent;
     }
     throw new Error(`'${tool}' not found in any '${TOOLS_DIR_NAME}' directory at or above '${process.cwd()}'. ` +
-        `Build it with '${BUILD_SCRIPT_PATH}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`);
+        `Build it with '${BUILD_COMMAND}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`);
 }
 /** Writes the patch that turns the bundle at `basePath` into the one at `targetPath`. */
 export function generatePatch(basePath, targetPath, patchPath) {

package/cli/dist/utils/binaryPatch.test.js

@@ -82,7 +82,7 @@ describe("generatePatch/applyPatch", () => {
         const previous = process.env.HDIFFPATCH_TOOLS_DIR;
         process.env.HDIFFPATCH_TOOLS_DIR = workPath("no-such-dir");
         try {
-            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/build-hdiffpatch\.sh/);
+            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/npx code-push build-patch-tools/);
         }
         finally {
             if (previous === undefined) {

package/cli/index.ts

@@ -34,6 +34,11 @@ import "./commands/showHistoryCommand/index.js";
  */
 import "./commands/initCommand/index.js";
 
+/**
+ * npx code-push build-patch-tools
+ */
+import "./commands/buildPatchToolsCommand/index.js";
+
 shell.set("-e");
 shell.set("+v");
 

package/cli/utils/binaryPatch.test.ts

@@ -101,7 +101,7 @@ describe("generatePatch/applyPatch", () => {
         const previous = process.env.HDIFFPATCH_TOOLS_DIR;
         process.env.HDIFFPATCH_TOOLS_DIR = workPath("no-such-dir");
         try {
-            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/build-hdiffpatch\.sh/);
+            expect(() => resolveBinaryPatchTool("hdiffz")).toThrow(/npx code-push build-patch-tools/);
         } finally {
             if (previous === undefined) {
                 delete process.env.HDIFFPATCH_TOOLS_DIR;

package/cli/utils/binaryPatch.ts

@@ -37,15 +37,18 @@ export type BinaryPatchTool = 'hdiffz' | 'hpatchz';
 const HDIFFZ_OPTIONS = ['-f', '-m-6', '-c-zstd-21-24'];
 const HPATCHZ_OPTIONS = ['-f', '-m'];
 
-const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
-const TOOLS_DIR_NAME = '.hdiffpatch-tools';
-const BUILD_SCRIPT_PATH = 'scripts/binary-patch/build-hdiffpatch.sh';
+export const TOOLS_DIR_ENV_NAME = 'HDIFFPATCH_TOOLS_DIR';
+export const TOOLS_DIR_NAME = '.hdiffpatch-tools';
+const BUILD_COMMAND = 'npx code-push build-patch-tools';
 
 /**
  * Finds the hdiffz/hpatchz executable, looking at `HDIFFPATCH_TOOLS_DIR` first and
  * then at a `.hdiffpatch-tools` directory in the working directory or any directory
  * above it. The tools are built from source rather than installed as a package
  * dependency, so the error explains how to get them.
+ *
+ * `build-patch-tools` (`cli/commands/buildPatchToolsCommand/index.ts`) installs into the
+ * first place this looks; a change to the lookup order has to be mirrored there.
  */
 export function resolveBinaryPatchTool(tool: BinaryPatchTool): string {
     const configuredDir = process.env[TOOLS_DIR_ENV_NAME];
@@ -56,7 +59,7 @@ export function resolveBinaryPatchTool(tool: BinaryPatchTool): string {
         }
         throw new Error(
             `${TOOLS_DIR_ENV_NAME} is set to '${configuredDir}' but it does not contain '${tool}'. ` +
-                `Build the tools with '${BUILD_SCRIPT_PATH}'.`,
+                `Build the tools with '${BUILD_COMMAND}'.`,
         );
     }
 
@@ -75,7 +78,7 @@ export function resolveBinaryPatchTool(tool: BinaryPatchTool): string {
 
     throw new Error(
         `'${tool}' not found in any '${TOOLS_DIR_NAME}' directory at or above '${process.cwd()}'. ` +
-            `Build it with '${BUILD_SCRIPT_PATH}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`,
+            `Build it with '${BUILD_COMMAND}', or set ${TOOLS_DIR_ENV_NAME} to a directory that contains it.`,
     );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bravemobile/react-native-code-push",
-  "version": "13.1.0-beta.5",
+  "version": "13.1.0",
   "description": "React Native plugin for the CodePush service",
   "main": "src/CodePush.js",
   "react-native": "src/CodePush.js",

package/src/CodePush.js

@@ -2,6 +2,7 @@ import { Alert, AppState, Platform } from "react-native";
 import log from "./logging";
 import hoistStatics from 'hoist-non-react-statics';
 import { SemverVersioning } from './versioning/SemverVersioning'
+import invokeTelemetryCallback from './invokeTelemetryCallback';
 
 const NativeCodePushModule = require("./native/NativeCodePush");
 let NativeCodePush = NativeCodePushModule.getNativeCodePush?.() ?? NativeCodePushModule.default;
@@ -83,7 +84,7 @@ async function decideLatestReleaseIsInRollout(versioning, clientId, onRolloutSki
 
   if (!inRollout) {
     log(`Skipping update due to rollout. Bucket ${bucket} is not smaller than rollout range ${latestReleaseInfo.rollout}.`);
-    onRolloutSkipped?.(latestVersion);
+    invokeTelemetryCallback('onRolloutSkipped', onRolloutSkipped, latestVersion);
   }
 
   return inRollout;
@@ -378,11 +379,11 @@ async function tryReportStatus(statusReport, retryOnAppResume) {
       const label = statusReport.package.label;
       if (statusReport.status === "DeploymentSucceeded") {
         log(`Reporting CodePush update success (${label})`);
-        sharedCodePushOptions?.onUpdateSuccess?.(label);
+        invokeTelemetryCallback('onUpdateSuccess', sharedCodePushOptions?.onUpdateSuccess, label);
       } else {
         log(`Reporting CodePush update rollback (${label})`);
         await nativeCodePush.setLatestRollbackInfo(statusReport.package.packageHash);
-        sharedCodePushOptions?.onUpdateRollback?.(label);
+        invokeTelemetryCallback('onUpdateRollback', sharedCodePushOptions?.onUpdateRollback, label);
       }
     }
 
@@ -565,20 +566,8 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
     ...options,
   };
 
-  /*
-   * A callback an app registered to observe how the update archives 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 onUpdateArchiveResult = typeof syncOptions.onUpdateArchiveResult === "function"
-    ? (label, result) => {
-      try {
-        syncOptions.onUpdateArchiveResult(label, result);
-      } catch (error) {
-        log(`An error has occurred : ${error.stack}`);
-      }
-    }
+    ? (label, result) => invokeTelemetryCallback('onUpdateArchiveResult', syncOptions.onUpdateArchiveResult, label, result)
     : null;
 
   syncStatusChangeCallback = typeof syncStatusChangeCallback === "function"
@@ -630,14 +619,14 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
 
     const doDownloadAndInstall = async () => {
       syncStatusChangeCallback(CodePush.SyncStatus.DOWNLOADING_PACKAGE);
-      sharedCodePushOptions.onDownloadStart?.(remotePackageLabel);
+      invokeTelemetryCallback('onDownloadStart', sharedCodePushOptions.onDownloadStart, remotePackageLabel);
 
       const localPackage = await remotePackage.download(
         downloadProgressCallback,
         onUpdateArchiveResult && ((result) => onUpdateArchiveResult(remotePackageLabel, result)),
       );
 
-      sharedCodePushOptions.onDownloadSuccess?.(remotePackageLabel);
+      invokeTelemetryCallback('onDownloadSuccess', sharedCodePushOptions.onDownloadSuccess, remotePackageLabel);
 
       // Determine the correct install mode based on whether the update is mandatory or not.
       resolvedInstallMode = localPackage.isMandatory ? syncOptions.mandatoryInstallMode : syncOptions.installMode;
@@ -721,7 +710,7 @@ async function syncInternal(options = {}, syncStatusChangeCallback, downloadProg
     }
   } catch (error) {
     syncStatusChangeCallback(CodePush.SyncStatus.UNKNOWN_ERROR);
-    sharedCodePushOptions?.onSyncError?.(remotePackageLabel ?? 'unknown', error);
+    invokeTelemetryCallback('onSyncError', sharedCodePushOptions?.onSyncError, remotePackageLabel ?? 'unknown', error);
     log(error.message);
     throw error;
   }
@@ -752,26 +741,26 @@ let CodePush;
  *   updateChecker: updateChecker | undefined,
  *   setUpdateChecker(updateCheckerFunction: updateChecker | undefined): void,
  *
- *   onUpdateSuccess: (label: string) => void | undefined,
- *   setOnUpdateSuccess(onUpdateSuccessFunction: (label: string) => void | undefined): void,
+ *   onUpdateSuccess: (label: string) => void | Promise<void> | undefined,
+ *   setOnUpdateSuccess(onUpdateSuccessFunction: (label: string) => void | Promise<void> | undefined): void,
  *
- *   onUpdateRollback: (label: string) => void | undefined,
- *   setOnUpdateRollback(onUpdateRollbackFunction: (label: string) => void | undefined): void,
+ *   onUpdateRollback: (label: string) => void | Promise<void> | undefined,
+ *   setOnUpdateRollback(onUpdateRollbackFunction: (label: string) => void | Promise<void> | undefined): void,
  *
- *   onDownloadStart: (label: string) => void | undefined,
- *   setOnDownloadStart(onDownloadStartFunction: (label: string) => void | undefined): void,
+ *   onDownloadStart: (label: string) => void | Promise<void> | undefined,
+ *   setOnDownloadStart(onDownloadStartFunction: (label: string) => void | Promise<void> | undefined): void,
  *
- *   onDownloadSuccess: (label: string) => void | undefined,
- *   setOnDownloadSuccess(onDownloadSuccessFunction: (label: string) => void | undefined): void,
+ *   onDownloadSuccess: (label: string) => void | Promise<void> | undefined,
+ *   setOnDownloadSuccess(onDownloadSuccessFunction: (label: string) => void | Promise<void> | undefined): void,
  *
- *   onSyncError: (label: string, error: Error) => void | undefined,
- *   setOnSyncError(onSyncErrorFunction: (label: string, error: Error) => void | undefined): void,
+ *   onSyncError: (label: string, error: Error) => void | Promise<void> | undefined,
+ *   setOnSyncError(onSyncErrorFunction: (label: string, error: Error) => void | Promise<void> | undefined): void,
  *
- *   onRolloutSkipped: (label: string, error: Error) => void | undefined,
- *   setOnRolloutSkipped(onRolloutSkippedFunction: (label: string, error: Error) => void | undefined): void,
+ *   onRolloutSkipped: (label: string, error: Error) => void | Promise<void> | undefined,
+ *   setOnRolloutSkipped(onRolloutSkippedFunction: (label: string, error: Error) => void | Promise<void> | undefined): void,
  *
- *   onUpdateArchiveResult: (label: string, result: object) => void | undefined,
- *   setOnUpdateArchiveResult(onUpdateArchiveResultFunction: (label: string, result: object) => void | undefined): void,
+ *   onUpdateArchiveResult: (label: string, result: object) => void | Promise<void> | undefined,
+ *   setOnUpdateArchiveResult(onUpdateArchiveResultFunction: (label: string, result: object) => void | Promise<void> | undefined): void,
  * }}
  */
 const sharedCodePushOptions = {

package/src/CodePush.test.js

@@ -64,7 +64,7 @@ function diffRelease() {
  *        which only a download that had an archive to try comes back with.
  * @param installedPackage the CodePush update the app is running, if any.
  */
-function createNativeBridge({ updateArchiveResult, installedPackage } = {}) {
+function createNativeBridge({ updateArchiveResult, installedPackage, statusReport } = {}) {
   return {
     addDownloadProgressListener: jest.fn(() => ({ remove: jest.fn() })),
     downloadUpdate: jest.fn(async (updatePackage) => ({
@@ -78,9 +78,12 @@ function createNativeBridge({ updateArchiveResult, installedPackage } = {}) {
     // The rest of what a full `sync()` reaches for.
     InstallMode,
     clearPendingRestart: jest.fn(),
-    getNewStatusReport: jest.fn(async () => null),
+    getNewStatusReport: jest.fn(async () => statusReport ?? null),
     installUpdate: jest.fn(async () => {}),
     notifyApplicationReady: jest.fn(async () => {}),
+    recordStatusReported: jest.fn(),
+    saveStatusReportForRetry: jest.fn(),
+    setLatestRollbackInfo: jest.fn(async () => {}),
   };
 }
 
@@ -89,13 +92,13 @@ function createNativeBridge({ updateArchiveResult, installedPackage } = {}) {
  * native bridge live on the module itself - configured the way an app configures it: the
  * decorator registers the app-wide options, and every sync below is one the app asks for.
  *
- * @param onUpdateArchiveResult a callback the app registers on the decorator, as opposed to
- *        one it passes to a single `sync()` call.
+ * Callback options left after the bridge setup values are removed are registered on the
+ * decorator, the same way an app registers them.
  */
-function loadCodePush({ releaseHistory = {}, updateChecker, updateArchiveResult, onUpdateArchiveResult, installedPackage } = {}) {
+function loadCodePush({ releaseHistory = {}, updateChecker, updateArchiveResult, installedPackage, statusReport, ...codePushOptions } = {}) {
   jest.resetModules();
   const CodePush = require('./CodePush');
-  const nativeBridge = createNativeBridge({ updateArchiveResult, installedPackage });
+  const nativeBridge = createNativeBridge({ updateArchiveResult, installedPackage, statusReport });
 
   CodePush.setUpTestDependencies(
     null,
@@ -106,7 +109,7 @@ function loadCodePush({ releaseHistory = {}, updateChecker, updateArchiveResult,
     checkFrequency: CodePush.CheckFrequency.MANUAL,
     releaseHistoryFetcher: async () => releaseHistory,
     updateChecker,
-    onUpdateArchiveResult,
+    ...codePushOptions,
   });
 
   return { CodePush, nativeBridge };
@@ -492,6 +495,40 @@ describe('the update archive result of a sync', () => {
     expect(localPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
   });
 
+  it('installs the update when the callback returns a rejected Promise', async () => {
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      updateArchiveResult: APPLIED,
+    });
+    const onUpdateArchiveResult = jest.fn(async () => {
+      throw new Error('the telemetry request failed');
+    });
+
+    const syncStatus = await CodePush.sync({ onUpdateArchiveResult });
+    await Promise.resolve();
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(LABEL, APPLIED);
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves a direct download when the callback returns a rejected Promise', async () => {
+    const { CodePush } = loadCodePush({
+      releaseHistory: patchedRelease(),
+      updateArchiveResult: APPLIED,
+    });
+    const onUpdateArchiveResult = jest.fn(async () => {
+      throw new Error('the telemetry request failed');
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+    const localPackage = await remotePackage.download(undefined, onUpdateArchiveResult);
+    await Promise.resolve();
+
+    expect(onUpdateArchiveResult).toHaveBeenCalledWith(APPLIED);
+    expect(localPackage).toMatchObject({ label: LABEL, packageHash: PACKAGE_HASH });
+  });
+
   it('leaves the result off the package a download resolves with', async () => {
     const { CodePush } = loadCodePush({
       releaseHistory: patchedRelease(),
@@ -505,3 +542,110 @@ describe('the update archive result of a sync', () => {
     expect(localPackage).not.toHaveProperty('updateArchiveResult');
   });
 });
+
+describe('telemetry callback errors', () => {
+  it('installs the update when onDownloadStart throws', async () => {
+    const onDownloadStart = jest.fn(() => {
+      throw new Error('the telemetry client is unavailable');
+    });
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: fullOnlyRelease(),
+      onDownloadStart,
+    });
+
+    const syncStatus = await CodePush.sync();
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onDownloadStart).toHaveBeenCalledWith(LABEL);
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it('installs the update when onDownloadSuccess returns a rejected Promise', async () => {
+    const onDownloadSuccess = jest.fn(async () => {
+      throw new Error('the telemetry request failed');
+    });
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: fullOnlyRelease(),
+      onDownloadSuccess,
+    });
+
+    const syncStatus = await CodePush.sync();
+    await Promise.resolve();
+
+    expect(syncStatus).toBe(CodePush.SyncStatus.UPDATE_INSTALLED);
+    expect(onDownloadSuccess).toHaveBeenCalledWith(LABEL);
+    expect(nativeBridge.installUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it('uses the next release when onRolloutSkipped throws', async () => {
+    const onRolloutSkipped = jest.fn(() => {
+      throw new Error('the telemetry client is unavailable');
+    });
+    const { CodePush } = loadCodePush({
+      releaseHistory: {
+        ...fullOnlyRelease(),
+        '1.0.2': {
+          ...fullOnlyRelease()[LABEL],
+          rollout: 0,
+          packageHash: 'b'.repeat(64),
+        },
+      },
+      onRolloutSkipped,
+    });
+
+    const remotePackage = await CodePush.checkForUpdate();
+
+    expect(onRolloutSkipped).toHaveBeenCalledWith('1.0.2');
+    expect(remotePackage.label).toBe(LABEL);
+  });
+
+  it('rejects with the original error when onSyncError throws', async () => {
+    const downloadError = new Error('the update download failed');
+    const onSyncError = jest.fn(() => {
+      throw new Error('the telemetry client is unavailable');
+    });
+    const { CodePush, nativeBridge } = loadCodePush({
+      releaseHistory: fullOnlyRelease(),
+      onSyncError,
+    });
+    nativeBridge.downloadUpdate.mockRejectedValueOnce(downloadError);
+
+    await expect(CodePush.sync()).rejects.toBe(downloadError);
+    expect(onSyncError).toHaveBeenCalledWith(LABEL, downloadError);
+  });
+
+  it('records a successful update when onUpdateSuccess throws', async () => {
+    const statusReport = {
+      status: 'DeploymentSucceeded',
+      package: { label: LABEL, packageHash: PACKAGE_HASH },
+    };
+    const onUpdateSuccess = jest.fn(() => {
+      throw new Error('the telemetry client is unavailable');
+    });
+    const { CodePush, nativeBridge } = loadCodePush({ statusReport, onUpdateSuccess });
+
+    await CodePush.notifyAppReady();
+
+    expect(onUpdateSuccess).toHaveBeenCalledWith(LABEL);
+    expect(nativeBridge.recordStatusReported).toHaveBeenCalledWith(statusReport);
+    expect(nativeBridge.saveStatusReportForRetry).not.toHaveBeenCalled();
+  });
+
+  it('records a rollback when onUpdateRollback returns a rejected Promise', async () => {
+    const statusReport = {
+      status: 'DeploymentFailed',
+      package: { label: LABEL, packageHash: PACKAGE_HASH },
+    };
+    const onUpdateRollback = jest.fn(async () => {
+      throw new Error('the telemetry request failed');
+    });
+    const { CodePush, nativeBridge } = loadCodePush({ statusReport, onUpdateRollback });
+
+    await CodePush.notifyAppReady();
+    await Promise.resolve();
+
+    expect(onUpdateRollback).toHaveBeenCalledWith(LABEL);
+    expect(nativeBridge.recordStatusReported).toHaveBeenCalledWith(statusReport);
+    expect(nativeBridge.saveStatusReportForRetry).not.toHaveBeenCalled();
+  });
+});

package/src/invokeTelemetryCallback.js

@@ -0,0 +1,18 @@
+const log = require("./logging");
+
+module.exports = function invokeTelemetryCallback(name, callback, ...args) {
+  if (typeof callback !== "function") return;
+
+  const logError = (error) => {
+    log(`The ${name} callback failed: ${error?.message ?? error}`);
+  };
+
+  try {
+    const result = callback(...args);
+    if (result && typeof result.then === "function") {
+      Promise.resolve(result).catch(logError);
+    }
+  } catch (error) {
+    logError(error);
+  }
+};

package/src/package-mixins.js

@@ -1,4 +1,4 @@
-const log = require("./logging");
+const invokeTelemetryCallback = require("./invokeTelemetryCallback");
 
 // This function is used to augment remote and local
 // package objects with additional functionality/properties
@@ -42,14 +42,10 @@ module.exports = (NativeCodePush) => {
           // taken off the package and reported on its own, leaving the package exactly what
           // the native side saved.
           const { updateArchiveResult, ...downloadedPackage } = downloadResult ?? {};
-          if (updateArchiveResult && updateArchiveResultCallback) {
+          if (updateArchiveResult) {
             // The result is an observation, so an observer that throws must not turn a
             // downloaded update into a failed one.
-            try {
-              updateArchiveResultCallback(updateArchiveResult);
-            } catch (error) {
-              log(`The update archive result callback threw: ${error?.message ?? error}`);
-            }
+            invokeTelemetryCallback('onUpdateArchiveResult', updateArchiveResultCallback, updateArchiveResult);
           }
 
           return { ...downloadedPackage, ...local };

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

@@ -211,27 +211,27 @@ export interface CodePushOptions extends SyncOptions {
     /**
      * Callback function that is called when the update installation succeeds.
      */
-    onUpdateSuccess?: (label: string) => void;
+    onUpdateSuccess?: (label: string) => void | Promise<void>;
     /**
      * Callback function that is called when the update rolled back.
      */
-    onUpdateRollback?: (label: string) => void;
+    onUpdateRollback?: (label: string) => void | Promise<void>;
     /**
      * Callback function that is called when download starts.
      */
-    onDownloadStart?: (label: string) => void;
+    onDownloadStart?: (label: string) => void | Promise<void>;
     /**
      * Callback function that is called when download finished successfully.
      */
-    onDownloadSuccess?: (label: string) => void;
+    onDownloadSuccess?: (label: string) => void | Promise<void>;
     /**
      * Callback function that is called when sync process failed.
      */
-    onSyncError?: (label: string, error: Error) => void;
+    onSyncError?: (label: string, error: Error) => void | Promise<void>;
     /**
      * Callback function that is called when rollout is skipped.
      */
-    onRolloutSkipped?: (label: string, error: Error) => void;
+    onRolloutSkipped?: (label: string, error: Error) => void | Promise<void>;
 }
 
 export interface DownloadProgress {
@@ -321,7 +321,7 @@ export interface RemotePackage extends Package {
      */
     download(
         downloadProgressCallback?: DownloadProgressCallback,
-        updateArchiveResultCallback?: (result: UpdateArchiveResult) => void,
+        updateArchiveResultCallback?: (result: UpdateArchiveResult) => void | Promise<void>,
     ): Promise<LocalPackage>;
 
     /**
@@ -404,7 +404,7 @@ export interface SyncOptions {
      * depends on the callback: registering none changes nothing, and one that throws is
      * logged and does not fail the download it is reporting on.
      */
-    onUpdateArchiveResult?: (label: string, result: UpdateArchiveResult) => void;
+    onUpdateArchiveResult?: (label: string, result: UpdateArchiveResult) => void | Promise<void>;
 
     /**
      * Specifies whether to ignore the update if the installation fails.