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

package/src/httpClient.ts

@@ -10,6 +10,7 @@ import { fetchJSON, FetchJSONResponseError } from "./fetchJSON";
 import { fetchReleaseCatalogWithCache } from "./releaseCatalogCache";
 import { HOT_UPDATER_SDK_VERSION } from "./sdkVersion";
 import type { HotUpdaterBaseURL } from "./types";
+import { createUUIDv7 } from "./uuidv7";
 
 export interface ReleaseCatalogRequest {
   readonly platform: "ios" | "android";
@@ -66,6 +67,12 @@ export interface HotUpdaterHttpSession {
     params: ReleaseCatalogRequest,
   ) => Promise<ReleaseCatalog>;
   resolveArtifact: (params: ArtifactRequest) => Promise<ArtifactInfo>;
+  /**
+   * Posts an Insights event under a client `eventId`, retrying a network
+   * error, timeout, 429 or 5xx for up to three attempts in all. Resolves once
+   * the event is delivered or left to background retries; rejects when its
+   * first attempt fails for good, such as with a 400.
+   */
   sendInsightsEvent: (params: InsightsEventParams) => Promise<void>;
 }
 
@@ -150,10 +157,53 @@ const requireArtifactProtocolV1 = (info: ArtifactInfo): ArtifactInfo => {
   return info;
 };
 
-const sendInsightsEvent = async (
+/** Attempts per Insights event, the first one included. */
+const INSIGHTS_MAX_ATTEMPTS = 3;
+/** Wait before the second attempt; it doubles for each later attempt. */
+const INSIGHTS_RETRY_BASE_DELAY_MS = 1000;
+/** Longest wait between attempts, a server's `Retry-After` included. */
+const INSIGHTS_RETRY_MAX_DELAY_MS = 30000;
+
+type InsightsAttemptFailure = {
+  readonly error: Error;
+  /** A network error, timeout, 429 or 5xx may pass on a later attempt. */
+  readonly retryable: boolean;
+  readonly retryAfterMs: number | null;
+};
+
+/**
+ * Reads `Retry-After` as delay-seconds, the form a server under load sends;
+ * an HTTP-date falls back to the backoff.
+ */
+const parseRetryAfterMs = (value: string | null): number | null => {
+  const seconds = value?.trim();
+  return seconds && /^\d+$/.test(seconds) ? Number(seconds) * 1000 : null;
+};
+
+const getRetryDelayMs = (
+  failedAttempt: number,
+  retryAfterMs: number | null,
+): number =>
+  Math.min(
+    retryAfterMs ??
+      // Jitter spreads the retries of installations that failed together.
+      INSIGHTS_RETRY_BASE_DELAY_MS *
+        2 ** (failedAttempt - 1) *
+        (0.5 + Math.random()),
+    INSIGHTS_RETRY_MAX_DELAY_MS,
+  );
+
+const wait = (ms: number) =>
+  new Promise<void>((resolve) => {
+    setTimeout(resolve, ms);
+  });
+
+/** Makes one POST, with its own timeout, and settles with its failure. */
+const postInsightsEvent = async (
   baseURL: string,
   params: InsightsEventParams,
-): Promise<void> => {
+  eventId: string,
+): Promise<InsightsAttemptFailure | null> => {
   const controller = new AbortController();
   const timeoutId = setTimeout(() => {
     controller.abort();
@@ -165,6 +215,7 @@ const sendInsightsEvent = async (
         appVersion: params.appVersion,
         channel: params.channel,
         cohort: params.cohort,
+        eventId,
         fingerprintHash: params.fingerprintHash,
         fromBundleId: params.fromBundleId,
         ...(params.fromReleaseId === undefined
@@ -190,22 +241,109 @@ const sendInsightsEvent = async (
       signal: controller.signal,
     });
 
-    if (response.status !== 204) {
-      throw new Error(
+    if (response.status === 204) return null;
+    return {
+      error: new Error(
         `Expected HTTP 204 from /events, received ${response.status}`,
-      );
-    }
+      ),
+      retryable: response.status === 429 || response.status >= 500,
+      retryAfterMs: parseRetryAfterMs(response.headers.get("Retry-After")),
+    };
   } catch (error: unknown) {
-    if (error instanceof Error && error.name === "AbortError") {
-      throw new Error("Request timed out");
-    }
-    throw error;
+    // fetch rejects only when no response arrived (a timeout or a network
+    // error), so a later attempt may still get through.
+    return {
+      error:
+        error instanceof Error && error.name === "AbortError"
+          ? new Error("Request timed out")
+          : error instanceof Error
+            ? error
+            : new Error(String(error)),
+      retryable: true,
+      retryAfterMs: null,
+    };
   } finally {
     clearTimeout(timeoutId);
   }
 };
 
-const createSession = (baseURL: string): HotUpdaterHttpSession => ({
+type InsightsEventSender = (
+  baseURL: string,
+  params: InsightsEventParams,
+) => Promise<void>;
+
+/**
+ * Sends Insights events one at a time and retries each in the background.
+ *
+ * The server keeps an installation's latest report by arrival, so a later
+ * event waits behind an earlier one's retries; otherwise a retried
+ * UPDATE_APPLIED could land after the UPDATE_DOWNLOADED that followed it.
+ * Callers still wait only for first attempts, as they did before retries, so
+ * startup, readiness and `updateBundle()` never wait out a backoff: once an
+ * event backs off, every waiting caller is released, and a failure after that
+ * only warns.
+ */
+const createInsightsEventSender = (): InsightsEventSender => {
+  let queue = Promise.resolve();
+  let retrying = false;
+  const waiting = new Set<() => void>();
+
+  return (baseURL, params) => {
+    // One ID for every attempt, so the server counts a retried POST once.
+    const eventId = createUUIDv7();
+
+    return new Promise<void>((resolve, reject) => {
+      let released = false;
+      const release = () => {
+        released = true;
+        waiting.delete(release);
+        resolve();
+      };
+      if (retrying) release();
+      else waiting.add(release);
+
+      queue = queue.then(async () => {
+        try {
+          for (let attempt = 1; ; attempt += 1) {
+            const failure = await postInsightsEvent(baseURL, params, eventId);
+            if (failure === null) {
+              release();
+              break;
+            }
+            if (!failure.retryable || attempt === INSIGHTS_MAX_ATTEMPTS) {
+              waiting.delete(release);
+              if (released) {
+                console.warn(
+                  `[HotUpdater] Insights ${params.type} event was not delivered:`,
+                  failure.error,
+                );
+              } else {
+                reject(failure.error);
+              }
+              break;
+            }
+            retrying = true;
+            for (const releaseWaiting of waiting) releaseWaiting();
+            await wait(getRetryDelayMs(attempt, failure.retryAfterMs));
+          }
+        } catch (error: unknown) {
+          // A failed request settles in postInsightsEvent, so only a bug gets
+          // here. A rejected queue would leave every later event, and a caller
+          // such as `updateBundle()` waiting on one, pending forever.
+          waiting.delete(release);
+          if (!released) reject(error);
+        } finally {
+          retrying = false;
+        }
+      });
+    });
+  };
+};
+
+const createSession = (
+  baseURL: string,
+  sendInsightsEvent: InsightsEventSender,
+): HotUpdaterHttpSession => ({
   fetchReleaseCatalog: async (params): Promise<ReleaseCatalog> => {
     const channelKey = encodeChannelKey(params.channel);
     let strategyValue: string;
@@ -270,6 +408,11 @@ const createSession = (baseURL: string): HotUpdaterHttpSession => ({
 /** Creates the private HTTP client used by HotUpdater.init and HotUpdater.wrap. */
 export const createHttpClient = (
   baseURL: HotUpdaterBaseURL,
-): HotUpdaterHttpClient => ({
-  createSession: async () => createSession(await resolveBaseURL(baseURL)),
-});
+): HotUpdaterHttpClient => {
+  // Shared by every session, since each report opens its own session.
+  const sendInsightsEvent = createInsightsEventSender();
+  return {
+    createSession: async () =>
+      createSession(await resolveBaseURL(baseURL), sendInsightsEvent),
+  };
+};

package/src/index.spec.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { HotUpdaterInitOptions, HotUpdaterOptions } from "./wrap";
 
@@ -31,6 +31,7 @@ const mocks = vi.hoisted(() => {
     getInstallId: vi.fn(() => "install-id"),
     getManifest: vi.fn(() => null),
     getMinBundleId: vi.fn(() => "min-bundle-id"),
+    getPersistedUserIdentity: vi.fn(() => ({})),
     init: vi.fn(),
     isChannelSwitched: vi.fn(() => false),
     notifyAppReady: vi.fn(() => ({ status: "UNCHANGED" as const })),
@@ -71,6 +72,7 @@ vi.mock("./native", () => ({
   getInstallId: mocks.getInstallId,
   getManifest: mocks.getManifest,
   getMinBundleId: mocks.getMinBundleId,
+  getPersistedUserIdentity: mocks.getPersistedUserIdentity,
   isChannelSwitched: mocks.isChannelSwitched,
   notifyAppReady: mocks.notifyAppReady,
   reload: mocks.reload,
@@ -99,6 +101,11 @@ describe("HotUpdater client initialization", () => {
     mocks.wrap.mockImplementation((Component: unknown) => Component);
   });
 
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
   it("exposes the console ID through the existing getter only", async () => {
     const HotUpdater = await importHotUpdater();
 
@@ -178,6 +185,68 @@ describe("HotUpdater client initialization", () => {
     );
   });
 
+  it.each([
+    { dev: true, insights: undefined, expected: false },
+    { dev: true, insights: true, expected: false },
+    { dev: true, insights: false, expected: false },
+    { dev: true, insights: { debug: true }, expected: true },
+    { dev: false, insights: { debug: true }, expected: true },
+    { dev: false, insights: { debug: false }, expected: true },
+    { dev: false, insights: false, expected: false },
+  ] as const)(
+    "resolves insights $insights to $expected when __DEV__ is $dev",
+    async ({ dev, insights, expected }) => {
+      vi.stubGlobal("__DEV__", dev);
+      vi.spyOn(console, "error").mockImplementation(() => undefined);
+      const HotUpdater = await importHotUpdater();
+
+      HotUpdater.init({ baseURL: "https://updates.example.com", insights });
+      HotUpdater.wrap({
+        baseURL: "https://updates.example.com",
+        insights,
+        updateStrategy: "appVersion",
+      });
+
+      expect(mocks.init).toHaveBeenCalledWith(
+        expect.objectContaining({ insights: expected }),
+      );
+      expect(mocks.wrap).toHaveBeenCalledWith(
+        expect.objectContaining({ insights: expected }),
+      );
+    },
+  );
+
+  it.each([
+    { dev: true, reports: false },
+    { dev: false, reports: true },
+  ])(
+    "gates manual checks and downloads on the build type (__DEV__: $dev)",
+    async ({ dev, reports }) => {
+      vi.stubGlobal("__DEV__", dev);
+      const sendInsightsEvent = vi.fn(async () => undefined);
+      mocks.createHttpClient.mockReturnValue({
+        createSession: vi.fn(async () => ({ sendInsightsEvent })),
+      } as never);
+      mocks.updateBundle.mockResolvedValueOnce(true);
+      const HotUpdater = await importHotUpdater();
+      HotUpdater.init({ baseURL: "https://updates.example.com" });
+
+      await HotUpdater.checkForUpdate({ updateStrategy: "appVersion" });
+      await HotUpdater.updateBundle({
+        assets: {},
+        bundleId: "next-bundle-id",
+        manifestFileHash: "manifest-hash",
+        manifestUrl: "https://updates.example.com/manifest.json",
+        status: "UPDATE",
+      });
+
+      expect(mocks.checkForUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({ insights: reports }),
+      );
+      expect(sendInsightsEvent).toHaveBeenCalledTimes(reports ? 1 : 0);
+    },
+  );
+
   it("requires baseURL and rejects the removed resolver shape", async () => {
     const HotUpdater = await importHotUpdater();
 

package/src/index.ts

@@ -93,6 +93,21 @@ type HotUpdaterWrap = {
   (options: HotUpdaterOptions): ReturnType<typeof wrap>;
 };
 
+/**
+ * Debug builds report only with `insights: { debug: true }`, so development
+ * sessions do not mix into production Insights. `__DEV__` is defined only in
+ * a React Native bundle; anywhere else, such as unit tests, counts as release.
+ */
+const resolveInsights = (
+  insights: HotUpdaterInitOptions["insights"],
+): boolean => {
+  if (insights === false) return false;
+  const isDebugBuild = typeof __DEV__ !== "undefined" && __DEV__;
+  return (
+    !isDebugBuild || (typeof insights === "object" && insights?.debug === true)
+  );
+};
+
 /**
  * Creates a HotUpdater client instance with all update management methods.
  * This function is called once on module initialization to create a singleton instance.
@@ -161,7 +176,7 @@ function createHotUpdaterClient() {
       const { baseURL, ...rest } = autoOptions;
       return {
         ...rest,
-        insights: rest.insights ?? true,
+        insights: resolveInsights(rest.insights),
         client: createHttpClient(baseURL),
       };
     }
@@ -181,7 +196,7 @@ function createHotUpdaterClient() {
       const { baseURL, ...baseURLRest } = rest;
       return {
         ...baseURLRest,
-        insights: baseURLRest.insights ?? true,
+        insights: resolveInsights(baseURLRest.insights),
         client: createHttpClient(baseURL),
       };
     }

package/src/notifyAppReadyInsights.transport.spec.ts

@@ -17,6 +17,9 @@ vi.mock("react-native", () => ({
 const failureCases = [
   { label: "400", responseStatus: 400 },
   { label: "404", responseStatus: 404 },
+] as const;
+
+const retryableFailureCases = [
   { label: "500", responseStatus: 500 },
   {
     error: Object.assign(new Error("request aborted"), { name: "AbortError" }),
@@ -135,4 +138,59 @@ describe("automatic notifyAppReady transport failures", () => {
       }
     },
   );
+
+  it.each(retryableFailureCases)(
+    "retries a $label failure in the background without delaying UNCHANGED readiness",
+    async (failureCase) => {
+      stubNotifyFrame();
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const onError = vi.fn();
+      const onNotifyAppReady = vi.fn();
+      const fetchMock = vi.fn<typeof fetch>(async () => {
+        if ("error" in failureCase) {
+          throw failureCase.error;
+        }
+
+        return new Response(null, { status: failureCase.responseStatus });
+      });
+      vi.stubGlobal("fetch", fetchMock);
+      Reflect.set(globalThis, "HotUpdater", {
+        SDK_VERSION: "test-sdk-version",
+      });
+
+      try {
+        const [{ createHttpClient }, { init }] = await Promise.all([
+          import("./httpClient"),
+          import("./wrap"),
+        ]);
+        const client = createHttpClient(
+          "https://updates.example.test/hot-updater",
+        );
+
+        init({ insights: true, client, onError, onNotifyAppReady });
+        await vi.runOnlyPendingTimersAsync();
+
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(onNotifyAppReady).toHaveBeenCalledWith({
+          status: "UNCHANGED",
+        });
+        expect(warn).not.toHaveBeenCalled();
+
+        await vi.runAllTimersAsync();
+
+        const eventIds = fetchMock.mock.calls.map(
+          ([, request]) => JSON.parse(String(request?.body)).eventId,
+        );
+        expect(eventIds).toHaveLength(3);
+        expect(new Set(eventIds).size).toBe(1);
+        expect(onError).not.toHaveBeenCalled();
+        expect(warn).toHaveBeenCalledExactlyOnceWith(
+          "[HotUpdater] Insights UNCHANGED event was not delivered:",
+          expect.any(Error),
+        );
+      } finally {
+        warn.mockRestore();
+      }
+    },
+  );
 });

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.16";

package/src/uuidv7.spec.ts

@@ -0,0 +1,25 @@
+import { isUUIDv7 } from "@hot-updater/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createUUIDv7 } from "./uuidv7";
+
+describe("createUUIDv7", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it.each([
+    { label: "Web Crypto", crypto: globalThis.crypto },
+    { label: "no Web Crypto, as in React Native", crypto: undefined },
+  ])("leads with the 48-bit millisecond time using $label", ({ crypto }) => {
+    vi.useFakeTimers({ now: 0x0192_3456_789a });
+    vi.stubGlobal("crypto", crypto);
+
+    const id = createUUIDv7();
+
+    expect(isUUIDv7(id)).toBe(true);
+    expect(id.startsWith("01923456-789a-7")).toBe(true);
+    expect(createUUIDv7()).not.toBe(id);
+  });
+});

package/src/uuidv7.ts

@@ -0,0 +1,38 @@
+type RandomValuesSource = {
+  readonly getRandomValues?: (array: Uint8Array) => Uint8Array;
+};
+
+/**
+ * Creates an RFC 9562 UUIDv7: a 48-bit millisecond timestamp, then random bits.
+ *
+ * `createUUIDv7` from `@hot-updater/plugin-core` calls `crypto.getRandomValues`
+ * unconditionally, but React Native has no Web Crypto unless the app installs a
+ * polyfill. An Insights event ID only has to tell one event from another so a
+ * retried POST is counted once, so `Math.random` is enough without one.
+ */
+export const createUUIDv7 = (): string => {
+  const bytes = new Uint8Array(16);
+  const { crypto } = globalThis as { crypto?: RandomValuesSource };
+  if (typeof crypto?.getRandomValues === "function") {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+
+  // Division, not bit shifts: shifts truncate to 32 bits, and a millisecond
+  // timestamp already needs 41.
+  let timestamp = Date.now();
+  for (let index = 5; index >= 0; index -= 1) {
+    bytes[index] = timestamp % 256;
+    timestamp = Math.floor(timestamp / 256);
+  }
+  bytes[6] = 0x70 | (bytes[6]! & 0x0f);
+  bytes[8] = 0x80 | (bytes[8]! & 0x3f);
+
+  const hex = Array.from(bytes, (byte) =>
+    byte.toString(16).padStart(2, "0"),
+  ).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+};

package/src/wrap.types.ts

@@ -30,9 +30,15 @@ interface CommonHotUpdaterOptions {
   /**
    * Sends app-ready transitions and same-Bundle Release adoptions to the
    * configured server. Defaults to `true`; set to `false` to disable client
-   * reporting.
+   * reporting. Debug builds (`__DEV__`) send nothing unless you pass
+   * `{ debug: true }`, so development sessions stay out of production data.
    */
-  insights?: boolean;
+  insights?:
+    | boolean
+    | {
+        /** Also report from debug builds. Defaults to `false`. */
+        debug?: boolean;
+      };
   /** Base URL of a server exposing the Hot Updater v1 client HTTP protocol. */
   baseURL: HotUpdaterBaseURL;
   requestHeaders?: Record<string, string>;
@@ -54,6 +60,7 @@ export type HotUpdaterInitOptions = CommonHotUpdaterOptions;
 export type HotUpdaterOptions = AutoUpdateOptions;
 
 type InternalCommonOptions = {
+  /** Whether this runtime reports, with the debug-build default applied. */
   insights?: boolean;
   client: HotUpdaterHttpClient;
   requestHeaders?: Record<string, string>;