@hot-updater/react-native 1.0.0-rc.16 → 1.0.0-rc.17

package/src/checkForUpdate.ts

@@ -9,8 +9,18 @@ import {
 import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
 import { Platform } from "react-native";
 
+import {
+  emitAfterAppReady,
+  getPreviousProcessExit,
+  getRunningReleaseId,
+} from "./appReady";
+import type {
+  ReleaseTransitionKind,
+  UpdateErrorResource,
+  UpdateErrorStage,
+} from "./clientPlugin";
 import { HotUpdaterError, StaleReleaseCatalogError } from "./error";
-import type { HotUpdaterHttpClient, HotUpdaterHttpSession } from "./httpClient";
+import type { HotUpdaterHttpClient } from "./httpClient";
 import {
   acceptReleaseCatalog,
   commitReleaseSelection,
@@ -21,20 +31,20 @@ import {
   getCohort,
   getDefaultChannel,
   getFingerprintHash,
-  getInstallId,
   getMinBundleId,
   getCrashHistory,
-  getPersistedUserIdentity,
   isReleaseSelectionCurrent,
   isChannelSwitched,
-  updateBundle,
+  stageBundle,
 } from "./native";
-import { reportBundleDownloaded } from "./notifyAppReadyInsights";
 import {
   hasExpectedReleaseCatalogScope,
   type ExpectedReleaseCatalogScope,
 } from "./releaseCatalogCache";
 import { hotUpdaterStore } from "./store";
+import { classifyUpdateError, InvalidUpdateResponseError } from "./updateError";
+
+export type { ReleaseTransitionKind };
 
 export interface CheckForUpdateOptions {
   /**
@@ -76,14 +86,7 @@ export type CheckForUpdateResult = {
   updateBundle: () => Promise<boolean>;
 };
 
-export type ReleaseTransitionKind =
-  | "INSTALL"
-  | "ADOPT_RELEASE"
-  | "USE_EMBEDDED"
-  | "USE_BUILTIN";
-
 export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
-  insights?: boolean;
   client: HotUpdaterHttpClient;
 }
 
@@ -113,7 +116,7 @@ const validateCatalog = (
     !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) ||
     !hasExpectedReleaseCatalogScope(catalog, expectedScope)
   ) {
-    throw new HotUpdaterError("Received an invalid Release catalog");
+    throw new InvalidUpdateResponseError("Received an invalid Release catalog");
   }
 };
 
@@ -126,40 +129,45 @@ const resetProgress = () => {
   });
 };
 
-const notifyUnchangedSelection = async (input: {
-  readonly active: PersistedSelectionReceipt | null;
-  readonly desired: PersistedSelectionReceipt;
-  readonly appVersion: string;
-  readonly cohort: string;
-  readonly fingerprintHash: string | null;
-  readonly platform: "ios" | "android";
-  readonly session: HotUpdaterHttpSession;
-  readonly requestHeaders?: Record<string, string>;
-  readonly requestTimeout?: number;
-}): Promise<void> => {
-  const { userId, username } = getPersistedUserIdentity();
-  try {
-    await input.session.sendInsightsEvent({
-      appVersion: input.appVersion,
-      channel: input.desired.channel,
-      cohort: input.cohort,
-      fingerprintHash: input.fingerprintHash,
-      fromBundleId: null,
-      fromReleaseId: input.active?.releaseId ?? null,
-      installId: getInstallId(),
-      platform: input.platform,
-      requestHeaders: input.requestHeaders,
-      requestTimeout: input.requestTimeout,
-      toBundleId: input.desired.bundleId,
-      toReleaseId: input.desired.releaseId,
-      type: "UNCHANGED",
-      updateStrategy: null,
-      ...(userId === undefined ? {} : { userId }),
-      ...(username === undefined ? {} : { username }),
-    });
-  } catch (error) {
-    console.warn("[HotUpdater] Unchanged selection insights failed:", error);
-  }
+/** The running bundle, the channel checked, and the update's target. */
+type UpdateErrorScope = {
+  readonly channel: string;
+  readonly bundleId: string;
+  readonly updateStrategy: "fingerprint" | "appVersion";
+  readonly targetBundleId?: string;
+  readonly targetReleaseId?: string | null;
+};
+
+/**
+ * Tells plugins why an update failed, when it failed as an update. An error
+ * the SDK's JavaScript raised happened in `stage`, fetching `resource`.
+ */
+export const reportUpdateError = (
+  error: unknown,
+  stage: UpdateErrorStage,
+  resource: UpdateErrorResource | undefined,
+  scope: UpdateErrorScope,
+): void => {
+  emitAfterAppReady("onUpdateError", () => {
+    const classification = classifyUpdateError(error, stage, resource);
+    if (classification === null) return null;
+    const previousProcessExit = getPreviousProcessExit();
+    return {
+      ...classification,
+      ...(previousProcessExit === null ? {} : { previousProcessExit }),
+      channel: scope.channel,
+      bundleId: scope.bundleId,
+      releaseId: getRunningReleaseId(scope.bundleId, getChannel()),
+      updateStrategy: scope.updateStrategy,
+      ...(scope.targetBundleId === undefined
+        ? {}
+        : { targetBundleId: scope.targetBundleId }),
+      ...(scope.targetReleaseId == null
+        ? {}
+        : { targetReleaseId: scope.targetReleaseId }),
+      cause: error,
+    };
+  });
 };
 
 async function checkForReleaseCatalogUpdate(input: {
@@ -210,6 +218,8 @@ async function checkForReleaseCatalogUpdate(input: {
     requestTimeout: options.requestTimeout,
     updateStrategy: options.updateStrategy,
   });
+  // The server says this scope has no catalog yet: no update, not a failure.
+  if (catalog === null) return null;
   validateCatalog(catalog, expectedScope);
   const catalogId = catalog.catalogId;
   const scopeKey = catalog.scopeKey;
@@ -263,7 +273,7 @@ async function checkForReleaseCatalogUpdate(input: {
       scopeKey,
     })
   ) {
-    throw new HotUpdaterError(
+    throw new InvalidUpdateResponseError(
       "Rejected a stale or inconsistent Release catalog",
     );
   }
@@ -327,7 +337,20 @@ async function checkForReleaseCatalogUpdate(input: {
     scopeKey,
     selectionContextHash,
   };
-  const updateBundleForSelection = async (): Promise<boolean> => {
+  const fromReleaseId =
+    active?.bundleId === input.currentBundleId
+      ? active.releaseId
+      : activeState.stableSelection?.bundleId === input.currentBundleId
+        ? activeState.stableSelection.releaseId
+        : null;
+  const errorScope = {
+    bundleId: input.currentBundleId,
+    channel: input.targetChannel,
+    targetBundleId: desired.bundleId,
+    targetReleaseId: desired.releaseId,
+    updateStrategy: options.updateStrategy,
+  };
+  const installSelection = async (): Promise<boolean> => {
     resetProgress();
     if (!isReleaseSelectionCurrent(guard)) {
       throw new StaleReleaseCatalogError();
@@ -338,18 +361,14 @@ async function checkForReleaseCatalogUpdate(input: {
         guard,
         selection: receipt,
       });
-      if (committed && transitionKind === "ADOPT_RELEASE" && options.insights) {
-        await notifyUnchangedSelection({
-          active,
-          appVersion: input.currentAppVersion,
-          cohort: input.cohort,
-          desired: receipt,
-          fingerprintHash: input.fingerprintHash,
-          platform: input.platform,
-          requestHeaders: options.requestHeaders,
-          requestTimeout: options.requestTimeout,
-          session,
-        });
+      if (committed && transitionKind === "ADOPT_RELEASE") {
+        emitAfterAppReady("onUpdateCheck", () => ({
+          status: "UNCHANGED",
+          channel: receipt.channel,
+          bundleId: receipt.bundleId,
+          releaseId: receipt.releaseId,
+          previousReleaseId: active?.releaseId ?? null,
+        }));
       }
       return committed;
     }
@@ -363,7 +382,7 @@ async function checkForReleaseCatalogUpdate(input: {
     if (!isReleaseSelectionCurrent(guard)) {
       throw new StaleReleaseCatalogError();
     }
-    const downloaded = await updateBundle({
+    const delivery = await stageBundle({
       assets: artifact.assets,
       bundleId: desired.bundleId,
       channel: input.targetChannel,
@@ -374,35 +393,53 @@ async function checkForReleaseCatalogUpdate(input: {
       shouldSkipCurrentBundleIdCheck: true,
       status: desired.status,
     });
-    if (downloaded) {
-      await reportBundleDownloaded(options, {
+    if (delivery !== null && desired.bundleId !== input.currentBundleId) {
+      emitAfterAppReady("onBundleDownloaded", () => ({
+        channel: input.targetChannel,
         fromBundleId: input.currentBundleId,
-        fromReleaseId:
-          active?.bundleId === input.currentBundleId
-            ? active.releaseId
-            : activeState.stableSelection?.bundleId === input.currentBundleId
-              ? activeState.stableSelection.releaseId
-              : null,
+        fromReleaseId,
         toBundleId: desired.bundleId,
         toReleaseId: desired.releaseId,
-        channel: input.targetChannel,
         updateStrategy: options.updateStrategy,
-      });
+        ...delivery,
+      }));
+    }
+    return true;
+  };
+  const updateBundleForSelection = async (): Promise<boolean> => {
+    try {
+      return await installSelection();
+    } catch (error) {
+      reportUpdateError(error, "download", "artifact", errorScope);
+      throw error;
     }
-    return downloaded;
   };
 
+  const shouldForceUpdate =
+    transitionKind === "ADOPT_RELEASE"
+      ? false
+      : desired.status === "ROLLBACK"
+        ? true
+        : (release?.shouldForceUpdate ?? false);
+  emitAfterAppReady("onUpdateCheck", () => ({
+    status: "UPDATE_AVAILABLE",
+    channel: input.targetChannel,
+    fromBundleId: input.currentBundleId,
+    fromReleaseId,
+    toBundleId: desired.bundleId,
+    toReleaseId: desired.releaseId,
+    transitionKind,
+    updateStatus: desired.status,
+    shouldForceUpdate,
+    updateStrategy: options.updateStrategy,
+  }));
+
   return {
     id: desired.releaseId ?? desired.bundleId,
     message: release?.message ?? null,
     releaseId: desired.releaseId,
     rolloutCohortCount: release?.rolloutCohortCount ?? 1000,
-    shouldForceUpdate:
-      transitionKind === "ADOPT_RELEASE"
-        ? false
-        : desired.status === "ROLLBACK"
-          ? true
-          : (release?.shouldForceUpdate ?? false),
+    shouldForceUpdate,
     status: desired.status,
     targetCohorts: release?.targetCohorts ? [...release.targetCohorts] : [],
     transitionKind,
@@ -451,7 +488,7 @@ export async function checkForUpdate(
   const fingerprintHash = getFingerprintHash();
 
   try {
-    return await checkForReleaseCatalogUpdate({
+    const result = await checkForReleaseCatalogUpdate({
       cohort,
       currentAppVersion,
       currentBundleId,
@@ -465,7 +502,25 @@ export async function checkForUpdate(
       platform,
       targetChannel,
     });
+    if (result === null) {
+      emitAfterAppReady("onUpdateCheck", () => {
+        const releaseId = getRunningReleaseId(currentBundleId, currentChannel);
+        return {
+          status: "UNCHANGED",
+          channel: currentChannel,
+          bundleId: currentBundleId,
+          releaseId,
+          previousReleaseId: releaseId,
+        };
+      });
+    }
+    return result;
   } catch (error) {
+    reportUpdateError(error, "check", "catalog", {
+      bundleId: currentBundleId,
+      channel: targetChannel,
+      updateStrategy: options.updateStrategy,
+    });
     options.onError?.(error as Error);
     return null;
   }

package/src/clientPlugin.ts

@@ -0,0 +1,231 @@
+/**
+ * The client plugin contract. Built-in plugins, such as
+ * `@hot-updater/react-native/plugins/insights`, and third-party plugins use
+ * the same one, as server plugins do.
+ */
+
+export type UpdateStrategy = "fingerprint" | "appVersion";
+
+/** How an update moves the app's selection. */
+export type ReleaseTransitionKind =
+  | "INSTALL"
+  | "ADOPT_RELEASE"
+  | "USE_EMBEDDED"
+  | "USE_BUILTIN";
+
+/** The launch outcome native reports once per JavaScript runtime. */
+export type AppReadyResult = (
+  | {
+      /** No update was applied or recovered at this launch. */
+      readonly status: "UNCHANGED";
+      readonly channel: string;
+      /** The running bundle. */
+      readonly bundleId: string;
+      /** The Release the running bundle was selected as, when known. */
+      readonly releaseId: string | null;
+    }
+  | {
+      /**
+       * `UPDATE_APPLIED`: a staged update became active at this launch.
+       * `RECOVERED`: a failed update was rolled back to `toBundleId`.
+       */
+      readonly status: "UPDATE_APPLIED" | "RECOVERED";
+      readonly channel: string;
+      readonly fromBundleId: string;
+      readonly fromReleaseId: string | null;
+      readonly toBundleId: string;
+      readonly toReleaseId: string | null;
+      readonly updateStrategy: UpdateStrategy;
+    }
+) & {
+  /**
+   * Android 11+: why the app's previous main process exited, the
+   * `ApplicationExitInfo` reason without its `REASON_` prefix, such as
+   * `CRASH`, `ANR`, `LOW_MEMORY`, or `USER_REQUESTED`. Null on iOS and on
+   * older Android. It tells a crash from the system or the user closing the
+   * app.
+   */
+  readonly previousProcessExit: string | null;
+};
+
+/** What an update check found. */
+export type UpdateCheckResult =
+  | {
+      /**
+       * The app keeps running its bundle: the check found nothing to
+       * install, or the app adopted a newer Release of the running bundle.
+       */
+      readonly status: "UNCHANGED";
+      readonly channel: string;
+      readonly bundleId: string;
+      /** The Release the running bundle is selected as after the check. */
+      readonly releaseId: string | null;
+      /** The Release before the check; it differs after an adoption. */
+      readonly previousReleaseId: string | null;
+    }
+  | {
+      /** The check found a Release to install, adopt, or roll back to. */
+      readonly status: "UPDATE_AVAILABLE";
+      readonly channel: string;
+      readonly fromBundleId: string;
+      readonly fromReleaseId: string | null;
+      readonly toBundleId: string;
+      readonly toReleaseId: string | null;
+      readonly transitionKind: ReleaseTransitionKind;
+      readonly updateStatus: "UPDATE" | "ROLLBACK";
+      readonly shouldForceUpdate: boolean;
+      readonly updateStrategy: UpdateStrategy;
+    };
+
+/** A bundle the SDK downloaded, verified, and staged for the next launch. */
+export interface BundleDownloadedInfo {
+  readonly channel: string;
+  readonly fromBundleId: string;
+  readonly fromReleaseId: string | null;
+  readonly toBundleId: string;
+  readonly toReleaseId: string | null;
+  readonly updateStrategy: UpdateStrategy;
+  /**
+   * How the bundle arrived: `patch` when a bsdiff patch produced a file,
+   * `manifest` when only the changed files were downloaded, `archive` for
+   * the full archive.
+   */
+  readonly delivery: "patch" | "manifest" | "archive";
+  /** A patch was tried, but the file or the archive was downloaded instead. */
+  readonly patchFallback: boolean;
+}
+
+/**
+ * Where an update failed: `check` covers the Release catalog request,
+ * `download` the transfer and verification of the update's files, and
+ * `install` patching, extracting, and moving them into place.
+ */
+export type UpdateErrorStage = "check" | "download" | "install";
+
+/** What the SDK was fetching or applying when an update failed. */
+export type UpdateErrorResource =
+  | "catalog"
+  | "artifact"
+  | "manifest"
+  | "file"
+  | "patch"
+  | "archive";
+
+/** Why no response arrived, for a `network` failure. */
+export type UpdateErrorTransport =
+  | "timeout"
+  | "dns"
+  | "tls"
+  | "connection"
+  | "offline"
+  | "cancelled";
+
+export type UpdateErrorReason =
+  | "network"
+  | "http"
+  | "invalid_response"
+  | "hash_mismatch"
+  | "signature"
+  | "patch"
+  | "extract"
+  | "storage"
+  | "unknown";
+
+/** An update check, download, or install that failed. */
+export interface UpdateError {
+  readonly stage: UpdateErrorStage;
+  readonly reason: UpdateErrorReason;
+  /** What was being fetched or applied, when the SDK knows. */
+  readonly resource?: UpdateErrorResource;
+  /** The response status when `reason` is `"http"`. */
+  readonly httpStatus?: number;
+  /**
+   * The storage origin's XML error `<Code>`, such as `AccessDenied`,
+   * `NoSuchKey`, or `ExpiredToken`, when an `http` failure's body names one.
+   * It tells an expired signed URL from a missing file.
+   */
+  readonly originCode?: string;
+  /** Why no response arrived, for a `network` failure, when the SDK knows. */
+  readonly transport?: UpdateErrorTransport;
+  /** Android 11+: why the previous main process exited (see `AppReadyResult`). */
+  readonly previousProcessExit?: string;
+  /** The bundle the update targeted; absent for the check stage. */
+  readonly targetBundleId?: string;
+  /** The Release the update targeted, when it names one. */
+  readonly targetReleaseId?: string;
+  readonly channel: string;
+  /** The running bundle and the Release it was selected as. */
+  readonly bundleId: string;
+  readonly releaseId: string | null;
+  readonly updateStrategy: UpdateStrategy;
+  /** The error the SDK caught. */
+  readonly cause: unknown;
+}
+
+/**
+ * Lifecycle hooks a plugin returns from `setup`. Hooks observe: the SDK
+ * never waits for one and ignores what it returns, and a hook that throws or
+ * rejects is reported through `onError`, or a console warning without one,
+ * so a plugin can never delay or change an update.
+ */
+export interface HotUpdaterClientHooks {
+  /** Called once per JavaScript runtime, after native reports the launch. */
+  onAppReady?(result: AppReadyResult): void | Promise<void>;
+  /** Called after each update check, and after a Release adoption commits. */
+  onUpdateCheck?(result: UpdateCheckResult): void | Promise<void>;
+  /** Called after the SDK stages a downloaded bundle. */
+  onBundleDownloaded?(info: BundleDownloadedInfo): void | Promise<void>;
+  /** Called when an update check, download, or install fails. */
+  onUpdateError?(error: UpdateError): void | Promise<void>;
+}
+
+/**
+ * A plugin's persistent key-value store. Native keeps it on the device,
+ * outside device backups, and the SDK scopes its keys to the plugin's id.
+ * It is meant for small values, up to 64 KB each.
+ */
+export interface HotUpdaterClientStorage {
+  get(key: string): string | null;
+  /** Writes the value; `null` removes the key. */
+  set(key: string, value: string | null): void;
+}
+
+export interface HotUpdaterClientContext {
+  /**
+   * Requests a path relative to the configured `baseURL`, with the SDK's
+   * `requestHeaders` and `requestTimeout` applied. Rejects with
+   * `Request timed out` when the timeout passes before a response arrives.
+   */
+  fetch(path: string, init?: RequestInit): Promise<Response>;
+  /** A random id native creates once per installation. */
+  readonly installId: string;
+  readonly platform: "ios" | "android";
+  /** The native app version, or null when the native build has none. */
+  readonly appVersion: string | null;
+  readonly sdkVersion: string;
+  /** Whether this is a debug build (`__DEV__`). */
+  readonly isDebugBuild: boolean;
+  /** The bundle native reports as current. */
+  getBundleId(): string;
+  getChannel(): string;
+  getCohort(): string;
+  getFingerprintHash(): string | null;
+  readonly storage: HotUpdaterClientStorage;
+  /** The current time in milliseconds since the epoch. */
+  now(): number;
+}
+
+export interface HotUpdaterClientPlugin {
+  /** Unique among an app's plugins; two plugins with one id throw at init. */
+  readonly id: string;
+  /**
+   * Called once, when `HotUpdater.init` or `HotUpdater.wrap` first
+   * configures the runtime with this plugin.
+   */
+  setup(context: HotUpdaterClientContext): HotUpdaterClientHooks | void;
+}
+
+/** Declares a client plugin; built-in and third-party plugins use the same contract. */
+export const defineClientPlugin = <const P extends HotUpdaterClientPlugin>(
+  plugin: P,
+): P => plugin;

package/src/entryImportGraph.spec.ts

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const sourceRoot = dirname(fileURLToPath(import.meta.url));
+
+/** Every relative module a file imports, statically or dynamically. */
+const readImports = (file: string): string[] => {
+  const source = readFileSync(file, "utf8");
+  const specifiers = [
+    ...source.matchAll(/\b(?:import|export)\s[^;]*?\bfrom\s*["']([^"']+)["']/g),
+    ...source.matchAll(/\bimport\s*["']([^"']+)["']/g),
+    ...source.matchAll(/\bimport\(\s*["']([^"']+)["']\s*\)/g),
+  ].map((match) => match[1]!);
+  return specifiers.filter((specifier) => specifier.startsWith("."));
+};
+
+const resolveModule = (from: string, specifier: string): string => {
+  const base = resolve(dirname(from), specifier);
+  const file = [
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, "index.ts"),
+    join(base, "index.tsx"),
+  ].find((path) => existsSync(path));
+  if (file === undefined) {
+    throw new Error(`Cannot resolve ${specifier} from ${from}`);
+  }
+  return file;
+};
+
+const collectGraph = (entry: string): Set<string> => {
+  const seen = new Set<string>();
+  const pending = [entry];
+  while (pending.length > 0) {
+    const file = pending.pop()!;
+    if (seen.has(file)) continue;
+    seen.add(file);
+    for (const specifier of readImports(file)) {
+      pending.push(resolveModule(file, specifier));
+    }
+  }
+  return seen;
+};
+
+describe("@hot-updater/react-native root entry", () => {
+  const graph = [...collectGraph(join(sourceRoot, "index.ts"))].map((file) =>
+    relative(sourceRoot, file),
+  );
+
+  it("bundles no plugin, since Metro does not tree-shake", () => {
+    expect(graph).toContain("pluginHost.ts");
+    expect(graph.filter((file) => file.startsWith("plugins/"))).toEqual([]);
+  });
+
+  it("sends no Insights request", () => {
+    const insightsCode = graph.filter((file) => {
+      const source = readFileSync(join(sourceRoot, file), "utf8");
+      return /["'`/]events["'`]/.test(source);
+    });
+    expect(insightsCode).toEqual([]);
+  });
+});

package/src/fetchJSON.ts

@@ -1,13 +1,6 @@
-export class FetchJSONResponseError extends Error {
-  constructor(
-    readonly status: number,
-    statusText: string,
-  ) {
-    super(
-      `Request failed with HTTP ${status}${statusText ? ` ${statusText}` : ""}`,
-    );
-  }
-}
+import { UpdateHttpError } from "./updateError";
+
+export class FetchJSONResponseError extends UpdateHttpError {}
 
 export const fetchJSON = async <T>({
   url,