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

package/src/releaseCatalogCache.spec.ts

@@ -199,6 +199,28 @@ describe("Release Catalog persistent cache", () => {
     },
   );
 
+  it("reads a 404 the server marks x-hot-updater-catalog: none as no catalog", async () => {
+    const fetchMock = vi.fn().mockResolvedValueOnce(
+      new Response(null, {
+        headers: { "x-hot-updater-catalog": "none" },
+        status: 404,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(fetchReleaseCatalogWithCache(input())).resolves.toBeNull();
+    expect(nativeMocks.write).not.toHaveBeenCalled();
+  });
+
+  it("throws the HTTP status of any other 404", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValueOnce(response(404)));
+
+    await expect(fetchReleaseCatalogWithCache(input())).rejects.toMatchObject({
+      name: "UpdateHttpError",
+      status: 404,
+    });
+  });
+
   it("does not use cached data as a fallback on network failure", async () => {
     const fetchMock = vi
       .fn()

package/src/releaseCatalogCache.ts

@@ -8,6 +8,8 @@ import {
   type ReleaseCatalog,
 } from "@hot-updater/core";
 
+import { InvalidUpdateResponseError, UpdateHttpError } from "./updateError";
+
 const CACHE_FORMAT_VERSION = "1";
 const MAX_ETAG_BYTES = 1024;
 export const MAX_RELEASE_CATALOG_WIRE_BYTES =
@@ -290,16 +292,25 @@ const consumeSuccessfulResponse = async (
   response: Response,
   input: FetchReleaseCatalogInput,
   partition: string,
-): Promise<ReleaseCatalog> => {
+): Promise<ReleaseCatalog | null> => {
+  // The server marks the 404 of a scope that has no catalog yet: no update,
+  // not a failure. Any other 404 is a wrong baseURL or route.
+  if (
+    response.status === 404 &&
+    response.headers.get("x-hot-updater-catalog")?.trim().toLowerCase() ===
+      "none"
+  ) {
+    return null;
+  }
   if (response.status !== 200) {
-    throw new Error(response.statusText);
+    throw new UpdateHttpError(response.status, response.statusText);
   }
 
   const body = await response.text();
   const catalog = parseValidatedCatalog(body, input.expectedScope);
   if (catalog === null) {
     await removeNativeReleaseCatalogCache(partition);
-    throw new Error("Received an invalid Release catalog");
+    throw new InvalidUpdateResponseError("Received an invalid Release catalog");
   }
 
   const etag = response.headers.get("etag");
@@ -323,9 +334,13 @@ const consumeSuccessfulResponse = async (
   return catalog;
 };
 
+/**
+ * Fetches a scope's catalog, or null when the server answers that the scope
+ * has none (a 404 with `x-hot-updater-catalog: none`).
+ */
 export const fetchReleaseCatalogWithCache = async (
   input: FetchReleaseCatalogInput,
-): Promise<ReleaseCatalog> => {
+): Promise<ReleaseCatalog | null> => {
   const partition = createReleaseCatalogCachePartition(input);
   const cached = await readValidatedCache(partition, input.expectedScope);
   const response = await fetchCatalogResponse(input, cached?.etag);

package/src/sdkVersion.ts

@@ -1 +1 @@
-export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.15";
+export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.17";

package/src/specs/NativeHotUpdater.ts

@@ -34,7 +34,11 @@ export interface Spec extends TurboModule {
    * Downloads and applies a bundle update.
    *
    * @param params - Update bundle parameters
-   * @returns Promise that resolves to true if successful
+   * @returns Promise that resolves, once the bundle is staged, to how it
+   *   arrived: `{ delivery, patchFallback }`. `delivery` is "patch" when a
+   *   bsdiff patch produced a file, "manifest" when only changed files were
+   *   downloaded, or "archive" for the full archive; `patchFallback` is true
+   *   when a patch was tried but the file or archive was downloaded instead.
    * @throws {HotUpdaterErrorCode} Rejects with one of the following error codes:
    *
    *   Parameter validation:
@@ -59,8 +63,20 @@ export interface Spec extends TurboModule {
    *
    *   Note: iOS normalizes rare signature/storage errors to SIGNATURE_VERIFICATION_FAILED
    *   or UNKNOWN_ERROR to keep the JS error surface small.
-   */
-  updateBundle(params: UpdateBundleParams): Promise<boolean>;
+   *
+   *   A rejection from the download or install also carries `userInfo`
+   *   `{ stage, reason, resource?, httpStatus?, transport?, originCode? }`:
+   *   `stage` is "download" (transfer and verification) or "install" (patch,
+   *   extract, move into place); `reason` is one of "network", "http",
+   *   "invalid_response", "hash_mismatch", "signature", "patch", "extract",
+   *   "storage", or "unknown"; `resource` is what was being fetched or
+   *   applied: "manifest", "file", "patch", or "archive". `httpStatus` is
+   *   present when `reason` is "http", with `originCode`, the storage
+   *   origin's XML error `<Code>` when the body names one. `transport` is
+   *   present when no response arrived: "timeout", "dns", "tls",
+   *   "connection", "offline", or "cancelled".
+   */
+  updateBundle(params: UpdateBundleParams): Promise<UnsafeObject>;
 
   /** Accepts and durably advances the catalog high-water for a scope. */
   acceptReleaseCatalog(params: UnsafeObject): boolean;
@@ -98,6 +114,13 @@ export interface Spec extends TurboModule {
     toBundleId?: string;
     updateStrategy?: "fingerprint" | "appVersion";
     crashedBundleId?: string;
+    /**
+     * Android 11+: why the app's previous main process exited, the
+     * `ApplicationExitInfo` reason without its `REASON_` prefix (for
+     * example "CRASH", "ANR", "LOW_MEMORY", "USER_REQUESTED"), read once
+     * when the process starts. Absent on iOS and older Android.
+     */
+    previousProcessExit?: string;
   };
 
   /**
@@ -164,24 +187,22 @@ export interface Spec extends TurboModule {
   getCohort: () => string;
 
   /**
-   * Gets the persisted install id for this app installation.
+   * Gets the install id: a random id native creates once per app
+   * installation and keeps out of device backups.
    */
   getInstallId: () => string;
 
   /**
-   * Gets the persisted nullable user id associated with this installation.
-   */
-  getUserId: () => string | null;
-
-  /**
-   * Gets the persisted nullable username associated with this installation.
+   * Reads a value from the SDK's persistent key-value store, which native
+   * keeps out of device backups. Returns null when the key has no value.
    */
-  getUsername: () => string | null;
+  getStorageItem: (key: string) => string | null;
 
   /**
-   * Persists nullable user identity fields associated with this installation.
+   * Writes a value to the SDK's persistent key-value store; null removes the
+   * key.
    */
-  setUser: (userId: string | null, username: string | null) => void;
+  setStorageItem: (key: string, value: string | null) => void;
 
   // EventEmitter
   addListener(eventName: string): void;

package/src/updateError.spec.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+
+import { StaleReleaseCatalogError } from "./error";
+import { FetchJSONResponseError } from "./fetchJSON";
+import {
+  classifyUpdateError,
+  InvalidUpdateResponseError,
+  UpdateHttpError,
+} from "./updateError";
+
+const nativeRejection = (userInfo?: Record<string, unknown>) =>
+  Object.assign(new Error("native failure"), {
+    code: "DOWNLOAD_FAILED",
+    ...(userInfo === undefined ? {} : { userInfo }),
+  });
+
+describe("classifyUpdateError", () => {
+  it.each([
+    {
+      label: "an HTTP status",
+      error: new UpdateHttpError(503, "Service Unavailable"),
+      expected: { reason: "http", httpStatus: 503 },
+    },
+    {
+      label: "a JSON request's HTTP status",
+      error: new FetchJSONResponseError(404, "Not Found"),
+      expected: { reason: "http", httpStatus: 404 },
+    },
+    {
+      label: "fetch without a response",
+      error: new TypeError("Network request failed"),
+      expected: { reason: "network" },
+    },
+    {
+      label: "a timeout",
+      error: new Error("Request timed out"),
+      expected: { reason: "network", transport: "timeout" },
+    },
+    {
+      label: "a cancelled request",
+      error: Object.assign(new Error("aborted"), { name: "AbortError" }),
+      expected: { reason: "network", transport: "cancelled" },
+    },
+    {
+      label: "an invalid response",
+      error: new InvalidUpdateResponseError(
+        "Received an invalid Release catalog",
+      ),
+      expected: { reason: "invalid_response" },
+    },
+    {
+      label: "unparsable JSON",
+      error: new SyntaxError("Unexpected token"),
+      expected: { reason: "invalid_response" },
+    },
+    {
+      label: "anything else",
+      error: new Error("Fingerprint hash is required"),
+      expected: { reason: "unknown" },
+    },
+  ])("classifies $label in the stage it happened", ({ error, expected }) => {
+    expect(classifyUpdateError(error, "check", "catalog")).toEqual({
+      stage: "check",
+      resource: "catalog",
+      ...expected,
+    });
+  });
+
+  it("leaves out the resource when the caller names none", () => {
+    expect(classifyUpdateError(new Error("unexpected"), "download")).toEqual({
+      stage: "download",
+      reason: "unknown",
+    });
+  });
+
+  it("takes a native rejection's own classification", () => {
+    expect(
+      classifyUpdateError(
+        nativeRejection({
+          reason: "patch",
+          resource: "patch",
+          stage: "install",
+        }),
+        "download",
+        "artifact",
+      ),
+    ).toEqual({ stage: "install", reason: "patch", resource: "patch" });
+    expect(
+      classifyUpdateError(
+        nativeRejection({
+          httpStatus: 403,
+          originCode: "AccessDenied",
+          reason: "http",
+          resource: "file",
+          stage: "download",
+        }),
+        "download",
+      ),
+    ).toEqual({
+      stage: "download",
+      reason: "http",
+      resource: "file",
+      httpStatus: 403,
+      originCode: "AccessDenied",
+    });
+    expect(
+      classifyUpdateError(
+        nativeRejection({
+          reason: "network",
+          stage: "download",
+          transport: "dns",
+        }),
+        "download",
+      ),
+    ).toEqual({ stage: "download", reason: "network", transport: "dns" });
+  });
+
+  it("drops native details that do not fit their field", () => {
+    expect(
+      classifyUpdateError(
+        nativeRejection({
+          httpStatus: 403,
+          originCode: "Access Denied <Key>secret</Key>",
+          reason: "http",
+          resource: "bucket",
+          stage: "download",
+          transport: "timeout",
+        }),
+        "download",
+      ),
+    ).toEqual({ stage: "download", reason: "http", httpStatus: 403 });
+  });
+
+  it.each([
+    { label: "a stale selection", error: new StaleReleaseCatalogError() },
+    { label: "an unclassified native rejection", error: nativeRejection() },
+    {
+      label: "a native rejection with an unknown class",
+      error: nativeRejection({ reason: "cosmic", stage: "download" }),
+    },
+  ])("reports $label as no update failure", ({ error }) => {
+    expect(classifyUpdateError(error, "download")).toBeNull();
+  });
+});

package/src/updateError.ts

@@ -0,0 +1,153 @@
+import type {
+  UpdateError,
+  UpdateErrorReason,
+  UpdateErrorResource,
+  UpdateErrorStage,
+  UpdateErrorTransport,
+} from "./clientPlugin";
+import { HotUpdaterError } from "./error";
+
+/**
+ * A response the SDK cannot use: a malformed or stale catalog, an artifact
+ * in another protocol, or an invalid URL.
+ */
+export class InvalidUpdateResponseError extends HotUpdaterError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = "InvalidUpdateResponseError";
+    if (options?.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+/** A request the server answered with a status the SDK does not accept. */
+export class UpdateHttpError extends HotUpdaterError {
+  constructor(
+    readonly status: number,
+    statusText: string,
+  ) {
+    super(
+      `Request failed with HTTP ${status}${statusText ? ` ${statusText}` : ""}`,
+    );
+    this.name = "UpdateHttpError";
+  }
+}
+
+const STAGES: readonly UpdateErrorStage[] = ["check", "download", "install"];
+const REASONS: readonly UpdateErrorReason[] = [
+  "network",
+  "http",
+  "invalid_response",
+  "hash_mismatch",
+  "signature",
+  "patch",
+  "extract",
+  "storage",
+  "unknown",
+];
+const RESOURCES: readonly UpdateErrorResource[] = [
+  "catalog",
+  "artifact",
+  "manifest",
+  "file",
+  "patch",
+  "archive",
+];
+const TRANSPORTS: readonly UpdateErrorTransport[] = [
+  "timeout",
+  "dns",
+  "tls",
+  "connection",
+  "offline",
+  "cancelled",
+];
+/** An S3, R2, or GCS error code: letters, digits, and punctuation only. */
+const ORIGIN_CODE = /^[A-Za-z0-9._-]{1,64}$/;
+
+type Classification = Pick<
+  UpdateError,
+  "stage" | "reason" | "resource" | "httpStatus" | "originCode" | "transport"
+>;
+
+const oneOf = <T extends string>(
+  values: readonly T[],
+  value: unknown,
+): value is T => values.includes(value as T);
+
+const readNativeClassification = (
+  error: object,
+): Classification | null | undefined => {
+  if (!("code" in error) || typeof error.code !== "string") return undefined;
+  const userInfo =
+    "userInfo" in error && typeof error.userInfo === "object"
+      ? (error.userInfo as Record<string, unknown> | null)
+      : null;
+  const { stage, reason, resource, transport, originCode } = userInfo ?? {};
+  // Native classifies every failure of its download and install; a rejection
+  // without it, such as a stale selection, is not an update failure.
+  if (!oneOf(STAGES, stage) || !oneOf(REASONS, reason)) return null;
+  const httpStatus = Number(userInfo?.httpStatus);
+  return {
+    stage,
+    reason,
+    ...(oneOf(RESOURCES, resource) ? { resource } : {}),
+    ...(reason === "http" && Number.isSafeInteger(httpStatus)
+      ? { httpStatus }
+      : {}),
+    ...(reason === "http" &&
+    typeof originCode === "string" &&
+    ORIGIN_CODE.test(originCode)
+      ? { originCode }
+      : {}),
+    ...(reason === "network" && oneOf(TRANSPORTS, transport)
+      ? { transport }
+      : {}),
+  };
+};
+
+/**
+ * Where and why an update failed, or null when the error is not an update
+ * failure. Native rejections carry their own classification; an error the
+ * SDK's JavaScript raised happened in `stage`, fetching `resource` when one
+ * is given.
+ */
+export const classifyUpdateError = (
+  error: unknown,
+  stage: UpdateErrorStage,
+  resource?: UpdateErrorResource,
+): Classification | null => {
+  if (typeof error === "object" && error !== null) {
+    const native = readNativeClassification(error);
+    if (native !== undefined) return native;
+  }
+  const scope = {
+    stage,
+    ...(resource === undefined ? {} : { resource }),
+  };
+  // Names, not classes, so an error from another copy of a module still
+  // classifies, as it does across test module resets.
+  const name = error instanceof Error ? error.name : null;
+  // A selection that became stale is a race between checks, not a failure.
+  if (name === "StaleReleaseCatalogError") return null;
+  if (name === "UpdateHttpError") {
+    return {
+      ...scope,
+      reason: "http",
+      httpStatus: (error as UpdateHttpError).status,
+    };
+  }
+  if (name === "InvalidUpdateResponseError" || name === "SyntaxError") {
+    return { ...scope, reason: "invalid_response" };
+  }
+  if (error instanceof Error && error.message === "Request timed out") {
+    return { ...scope, reason: "network", transport: "timeout" };
+  }
+  if (name === "AbortError") {
+    return { ...scope, reason: "network", transport: "cancelled" };
+  }
+  if (name === "TypeError") {
+    // fetch rejects with a TypeError when no response arrives, without
+    // saying why.
+    return { ...scope, reason: "network" };
+  }
+  return { ...scope, reason: "unknown" };
+};

package/src/wrap.progress.spec.ts

@@ -0,0 +1,232 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { createElement } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { HotUpdaterProgressEvent } from "./native";
+import type {
+  HotUpdaterFallbackComponentProps,
+  InternalWrapOptions,
+} from "./wrap";
+
+const mocks = vi.hoisted(() => ({
+  listeners: new Map<string, (event: HotUpdaterProgressEvent) => void>(),
+  checkForUpdate: vi.fn(),
+  reload: vi.fn(),
+}));
+
+vi.mock("./checkForUpdate", () => ({
+  checkForUpdate: mocks.checkForUpdate,
+}));
+
+vi.mock("./appReady", () => ({
+  handleNotifyAppReady: vi.fn().mockResolvedValue({ status: "UNCHANGED" }),
+}));
+
+vi.mock("./native", () => ({
+  addListener: vi.fn(
+    (eventName: string, listener: (event: HotUpdaterProgressEvent) => void) => {
+      mocks.listeners.set(eventName, listener);
+      return () => {
+        mocks.listeners.delete(eventName);
+      };
+    },
+  ),
+  getUpdateId: vi.fn(() => "release-id"),
+  reload: mocks.reload,
+}));
+
+describe("HotUpdater wrap progress subscription", () => {
+  let frameCallbacks: ((timestamp: number) => void)[];
+
+  const flushFrames = async () => {
+    await act(async () => {
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      while (frameCallbacks.length > 0) {
+        frameCallbacks.shift()?.(0);
+      }
+    });
+  };
+
+  const emitProgress = async (progress: number) => {
+    const event: HotUpdaterProgressEvent = {
+      artifactType: "diff",
+      progress,
+      details: {
+        totalFilesCount: 1,
+        completedFilesCount: progress === 1 ? 1 : 0,
+        files: [
+          {
+            order: 0,
+            path: "index.bundle",
+            downloadPath: "index.bundle",
+            downloadedBytes: progress * 1_000,
+            totalBytes: 1_000,
+            progress,
+            status: progress === 1 ? "downloaded" : "downloading",
+          },
+        ],
+      },
+    };
+    await act(async () => {
+      mocks.listeners.get("onProgress")?.(event);
+    });
+    await flushFrames();
+    return event;
+  };
+
+  const renderWrapped = async (
+    options: Pick<
+      InternalWrapOptions,
+      "fallbackComponent" | "onProgress" | "onUpdateProcessCompleted"
+    >,
+    onRender: () => void,
+  ) => {
+    const { wrap } = await import("./wrap");
+    const App = () => {
+      onRender();
+      return createElement("div", null, "app");
+    };
+    const Wrapped = wrap({
+      client: { createSession: vi.fn() },
+      updateStrategy: "appVersion",
+      ...options,
+    })(App);
+
+    render(createElement(Wrapped));
+    await flushFrames();
+  };
+
+  beforeEach(() => {
+    vi.resetModules();
+    mocks.listeners.clear();
+    mocks.checkForUpdate.mockReset();
+    mocks.checkForUpdate.mockResolvedValue(null);
+    mocks.reload.mockReset();
+    frameCallbacks = [];
+    vi.stubGlobal(
+      "requestAnimationFrame",
+      (callback: (timestamp: number) => void) => {
+        frameCallbacks.push(callback);
+        return frameCallbacks.length;
+      },
+    );
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("does not re-render the wrapped app on progress updates without fallbackComponent or onProgress", async () => {
+    const onRender = vi.fn();
+    await renderWrapped({}, onRender);
+    const rendersBeforeDownload = onRender.mock.calls.length;
+
+    for (const progress of [0.1, 0.2, 0.3, 0.4, 0.5]) {
+      await emitProgress(progress);
+    }
+
+    expect(onRender).toHaveBeenCalledTimes(rendersBeforeDownload);
+  });
+
+  it("keeps reporting progress to onProgress without re-rendering the wrapped app", async () => {
+    const onRender = vi.fn();
+    const onProgress = vi.fn();
+    await renderWrapped({ onProgress }, onRender);
+    const rendersBeforeDownload = onRender.mock.calls.length;
+
+    await emitProgress(0.25);
+    await emitProgress(0.75);
+
+    expect(onProgress.mock.calls).toEqual([[0], [0.25], [0.75]]);
+    expect(onRender).toHaveBeenCalledTimes(rendersBeforeDownload);
+  });
+
+  it("keeps passing progress details to fallbackComponent during an update check", async () => {
+    mocks.checkForUpdate.mockReturnValue(new Promise(() => {}));
+    const fallbackProps = vi.fn();
+    const Fallback = (props: HotUpdaterFallbackComponentProps) => {
+      fallbackProps(props);
+      return createElement("div", null, `progress:${props.progress}`);
+    };
+    await renderWrapped({ fallbackComponent: Fallback }, vi.fn());
+
+    const event = await emitProgress(0.5);
+
+    expect(screen.getByText("progress:0.5")).toBeTruthy();
+    expect(fallbackProps).toHaveBeenLastCalledWith({
+      ...event,
+      status: "CHECK_FOR_UPDATE",
+      message: null,
+    });
+  });
+
+  it.each([false, true])(
+    "preserves progress reporting across the fallback transition with shouldForceUpdate=%s",
+    async (shouldForceUpdate) => {
+      let resolveCheck!: (update: unknown) => void;
+      mocks.checkForUpdate.mockReturnValue(
+        new Promise((resolve) => {
+          resolveCheck = resolve;
+        }),
+      );
+      let finishDownload!: (success: boolean) => void;
+      const download = new Promise<boolean>((resolve) => {
+        finishDownload = resolve;
+      });
+      const updateBundle = vi.fn(() => download);
+      const onProgress = vi.fn();
+      const onRender = vi.fn();
+      const onUpdateProcessCompleted = vi.fn();
+      const Fallback = ({
+        status,
+        progress,
+      }: HotUpdaterFallbackComponentProps) =>
+        createElement("div", null, `${status}:${progress}`);
+      await renderWrapped(
+        { fallbackComponent: Fallback, onProgress, onUpdateProcessCompleted },
+        onRender,
+      );
+      expect(screen.getByText("CHECK_FOR_UPDATE:0")).toBeTruthy();
+      expect(onRender).not.toHaveBeenCalled();
+
+      const update = {
+        id: "new-release",
+        status: "UPDATE",
+        shouldForceUpdate,
+        message: "New release",
+      };
+      await act(async () => {
+        resolveCheck({ ...update, updateBundle });
+      });
+      expect(updateBundle).toHaveBeenCalledOnce();
+      expect(onUpdateProcessCompleted).toHaveBeenCalledTimes(
+        shouldForceUpdate ? 0 : 1,
+      );
+      expect(
+        screen.getByText(shouldForceUpdate ? "UPDATING:0" : "app"),
+      ).toBeTruthy();
+      const rendersDuringDownload = onRender.mock.calls.length;
+
+      for (const progress of [0.25, 0.75, 1]) {
+        await emitProgress(progress);
+      }
+      expect(onRender).toHaveBeenCalledTimes(rendersDuringDownload);
+      if (shouldForceUpdate) {
+        expect(screen.getByText("UPDATING:1")).toBeTruthy();
+      }
+
+      await act(async () => {
+        finishDownload(true);
+      });
+      expect(screen.getByText("app")).toBeTruthy();
+      expect(onRender).toHaveBeenCalledOnce();
+      expect(onUpdateProcessCompleted).toHaveBeenCalledOnce();
+      expect(onUpdateProcessCompleted).toHaveBeenCalledWith(update);
+      expect(mocks.reload).toHaveBeenCalledTimes(shouldForceUpdate ? 1 : 0);
+      expect(onProgress.mock.calls).toEqual([[0], [0.25], [0.75], [1]]);
+    },
+  );
+});