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

package/src/plugins/insights/eventId.ts

@@ -0,0 +1,171 @@
+type RandomValuesSource = {
+  readonly getRandomValues?: (array: Uint8Array) => Uint8Array;
+};
+
+const formatUUIDv7 = (bytes: Uint8Array, timestamp: number): string => {
+  // Division, not bit shifts: shifts truncate to 32 bits, and a millisecond
+  // timestamp already needs 41.
+  let time = timestamp;
+  for (let index = 5; index >= 0; index -= 1) {
+    bytes[index] = time % 256;
+    time = Math.floor(time / 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)}`;
+};
+
+/**
+ * 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);
+    }
+  }
+  return formatUUIDv7(bytes, Date.now());
+};
+
+const SHA256_K = [
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+  0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+  0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+  0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+  0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+  0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+  0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+  0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+  0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+];
+
+const encodeUtf8 = (value: string): number[] => {
+  const bytes: number[] = [];
+  for (const character of value) {
+    const code = character.codePointAt(0)!;
+    if (code < 0x80) {
+      bytes.push(code);
+    } else if (code < 0x800) {
+      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else if (code < 0x10000) {
+      bytes.push(
+        0xe0 | (code >> 12),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    } else {
+      bytes.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    }
+  }
+  return bytes;
+};
+
+/** SHA-256 of a string's UTF-8 bytes, since React Native has no Web Crypto. */
+export const sha256 = (value: string): Uint8Array => {
+  const bytes = encodeUtf8(value);
+  const bitLength = bytes.length * 8;
+  bytes.push(0x80);
+  while (bytes.length % 64 !== 56) bytes.push(0);
+  for (let shift = 56; shift >= 0; shift -= 8) {
+    // The length's high word, as division, since shifts truncate to 32 bits.
+    bytes.push(
+      shift >= 32
+        ? Math.floor(bitLength / 2 ** shift) & 0xff
+        : (bitLength >>> shift) & 0xff,
+    );
+  }
+
+  const hash = [
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+    0x1f83d9ab, 0x5be0cd19,
+  ];
+  const words: number[] = Array.from({ length: 64 }, () => 0);
+  const rotate = (word: number, bits: number) =>
+    (word >>> bits) | (word << (32 - bits));
+
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let index = 0; index < 16; index += 1) {
+      const at = offset + index * 4;
+      words[index] =
+        (bytes[at]! << 24) |
+        (bytes[at + 1]! << 16) |
+        (bytes[at + 2]! << 8) |
+        bytes[at + 3]!;
+    }
+    for (let index = 16; index < 64; index += 1) {
+      const low = words[index - 15]!;
+      const high = words[index - 2]!;
+      const s0 = rotate(low, 7) ^ rotate(low, 18) ^ (low >>> 3);
+      const s1 = rotate(high, 17) ^ rotate(high, 19) ^ (high >>> 10);
+      words[index] = (words[index - 16]! + s0 + words[index - 7]! + s1) | 0;
+    }
+
+    let [a, b, c, d, e, f, g, h] = hash as [
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+      number,
+    ];
+    for (let index = 0; index < 64; index += 1) {
+      const s1 = rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25);
+      const choose = (e & f) ^ (~e & g);
+      const temp1 = (h + s1 + choose + SHA256_K[index]! + words[index]!) | 0;
+      const s0 = rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + majority) | 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) | 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) | 0;
+    }
+    const results = [a, b, c, d, e, f, g, h];
+    for (let index = 0; index < 8; index += 1) {
+      hash[index] = (hash[index]! + results[index]!) | 0;
+    }
+  }
+
+  const digest = new Uint8Array(32);
+  hash.forEach((word, index) => {
+    digest[index * 4] = (word >>> 24) & 0xff;
+    digest[index * 4 + 1] = (word >>> 16) & 0xff;
+    digest[index * 4 + 2] = (word >>> 8) & 0xff;
+    digest[index * 4 + 3] = word & 0xff;
+  });
+  return digest;
+};
+
+/**
+ * A UUIDv7 derived from a key: its time field is `timestamp` and its random
+ * bits are the key's SHA-256, so the same key and time always give the same
+ * id, and a server that stores reports by id counts it once.
+ */
+export const createKeyedUUIDv7 = (key: string, timestamp: number): string =>
+  formatUUIDv7(sha256(key).slice(0, 16), timestamp);

package/src/plugins/insights/index.ts

@@ -0,0 +1,367 @@
+import {
+  defineClientPlugin,
+  type AppReadyResult,
+  type BundleDownloadedInfo,
+  type HotUpdaterClientContext,
+  type HotUpdaterClientPlugin,
+  type UpdateCheckResult,
+  type UpdateError,
+} from "../../clientPlugin";
+import { createKeyedUUIDv7, createUUIDv7 } from "./eventId";
+import {
+  createInsightsEventSender,
+  type InsightsDelivery,
+  type InsightsEventBody,
+  type InsightsEventSender,
+} from "./sender";
+import {
+  createInsightsState,
+  type InsightsState,
+  type RunningReport,
+  utcDay,
+  utcDayStart,
+} from "./state";
+
+export interface InsightsOptions {
+  /**
+   * Also report from debug builds (`__DEV__`). Defaults to `false`, so
+   * development sessions stay out of production Insights.
+   */
+  readonly debug?: boolean;
+}
+
+/** The app's own id for the signed-in user, attached to later reports. */
+export interface InsightsUser {
+  readonly userId: string | number;
+}
+
+export interface InsightsPlugin extends HotUpdaterClientPlugin {
+  readonly id: "insights";
+  /**
+   * Attaches the signed-in user's id to later reports, or clears it with
+   * `null`. It persists on the device, sends nothing by itself, and can be
+   * called before `HotUpdater.init`.
+   */
+  setUser(user: InsightsUser | null): void;
+}
+
+type Movement = Pick<
+  InsightsEventBody,
+  | "type"
+  | "channel"
+  | "fromBundleId"
+  | "fromReleaseId"
+  | "toBundleId"
+  | "toReleaseId"
+  | "updateStrategy"
+  | "metadata"
+>;
+
+/** A report the plugin built, with what the gate needs to decide on it. */
+type PendingEvent = {
+  readonly body: InsightsEventBody;
+  readonly day: string;
+  /** For UNCHANGED, UPDATE_APPLIED and RECOVERED: what the report says runs. */
+  readonly report: RunningReport | null;
+  /** For UPDATE_FAILED: the day's key the failure is reported under. */
+  readonly failureKey: string | null;
+  /** For UPDATE_FAILED: a later success for its target made it moot. */
+  superseded?: boolean;
+};
+
+const normalizeUserId = (user: InsightsUser | null): string | null => {
+  if (user === null) return null;
+  const userId = String(user.userId).trim();
+  return userId.length === 0 ? null : userId;
+};
+
+/**
+ * Reports update adoption to a server that runs the `insights()` server
+ * plugin: launches (at most once a UTC day while nothing changes), downloads,
+ * applies, recoveries, and update failures. After the server answers that
+ * Insights is off, the plugin sends nothing for 24 hours, and for the rest
+ * of that runtime.
+ *
+ * @example
+ * ```ts
+ * import { HotUpdater } from "@hot-updater/react-native";
+ * import { insights } from "@hot-updater/react-native/plugins/insights";
+ *
+ * const analytics = insights();
+ * HotUpdater.init({ baseURL, plugins: [analytics] });
+ * analytics.setUser({ userId: "user-123" });
+ * ```
+ */
+export const insights = (options: InsightsOptions = {}): InsightsPlugin => {
+  let context: HotUpdaterClientContext | null = null;
+  let state: InsightsState | null = null;
+  /** A user set before setup, applied once the plugin has storage. */
+  let pendingUser: { readonly userId: string | null } | null = null;
+  /** A download in this runtime: a later no-change report would hide it. */
+  let didDownload = false;
+  let lastDownloadedSelection: string | null = null;
+  const pending = new Map<InsightsEventBody, PendingEvent>();
+  let send: InsightsEventSender | null = null;
+
+  const createEvent = (
+    movement: Movement,
+    eventId?: (now: number, installId: string) => string,
+  ): PendingEvent | null => {
+    if (context === null || state === null) return null;
+    const appVersion = context.appVersion;
+    if (appVersion === null) {
+      console.warn(
+        `[HotUpdater] Insights needs the native app version; the ${movement.type} event was not sent.`,
+      );
+      return null;
+    }
+    const now = context.now();
+    const installId = context.installId;
+    const userId = state.readUserId();
+    const body: InsightsEventBody = {
+      ...movement,
+      eventId: eventId?.(now, installId) ?? createUUIDv7(),
+      installId,
+      ...(userId === null ? {} : { userId }),
+      platform: context.platform,
+      appVersion,
+      cohort: context.getCohort(),
+      fingerprintHash: context.getFingerprintHash(),
+      sdkVersion: context.sdkVersion,
+    };
+    const day = utcDay(now);
+    return {
+      body,
+      day,
+      report:
+        movement.type === "UNCHANGED" ||
+        movement.type === "UPDATE_APPLIED" ||
+        movement.type === "RECOVERED"
+          ? {
+              day,
+              channel: movement.channel,
+              appVersion,
+              bundleId: movement.toBundleId,
+              releaseId: movement.toReleaseId,
+              userId,
+            }
+          : null,
+      failureKey: null,
+    };
+  };
+
+  const enqueue = (event: PendingEvent | null) => {
+    if (event === null || send === null) return;
+    const { type, toBundleId } = event.body;
+    if (type === "UPDATE_DOWNLOADED" || type === "UPDATE_APPLIED") {
+      // A failure for a target that then arrived no longer describes it.
+      for (const queued of pending.values()) {
+        if (
+          queued.body.type === "UPDATE_FAILED" &&
+          queued.body.toBundleId === toBundleId
+        ) {
+          queued.superseded = true;
+        }
+      }
+    }
+    pending.set(event.body, event);
+    void send(event.body).catch((error: unknown) => {
+      console.warn(
+        `[HotUpdater] Insights ${event.body.type} event was not delivered:`,
+        error,
+      );
+    });
+  };
+
+  const reportLaunch = (
+    channel: string,
+    bundleId: string,
+    releaseId: string | null,
+    fromReleaseId: string | null,
+  ) => {
+    // After a download the server shows the update as waiting; a later
+    // no-change report from this runtime would hide it.
+    if (didDownload) return;
+    enqueue(
+      createEvent({
+        type: "UNCHANGED",
+        channel,
+        fromBundleId: null,
+        fromReleaseId,
+        toBundleId: bundleId,
+        toReleaseId: releaseId,
+        updateStrategy: null,
+      }),
+    );
+  };
+
+  const onAppReady = (result: AppReadyResult) => {
+    if (result.status === "UNCHANGED") {
+      reportLaunch(result.channel, result.bundleId, result.releaseId, null);
+      return;
+    }
+    enqueue(
+      createEvent({
+        type: result.status,
+        channel: result.channel,
+        fromBundleId: result.fromBundleId,
+        fromReleaseId: result.fromReleaseId,
+        toBundleId: result.toBundleId,
+        toReleaseId: result.toReleaseId,
+        updateStrategy: result.updateStrategy,
+        // Tells a crash from the system or the user closing the app.
+        ...(result.status === "RECOVERED" && result.previousProcessExit !== null
+          ? { metadata: { previousProcessExit: result.previousProcessExit } }
+          : {}),
+      }),
+    );
+  };
+
+  const onUpdateCheck = (result: UpdateCheckResult) => {
+    if (result.status !== "UNCHANGED") return;
+    reportLaunch(
+      result.channel,
+      result.bundleId,
+      result.releaseId,
+      result.previousReleaseId === result.releaseId
+        ? null
+        : result.previousReleaseId,
+    );
+  };
+
+  const onBundleDownloaded = (info: BundleDownloadedInfo) => {
+    const selection = JSON.stringify([
+      info.channel,
+      info.toReleaseId,
+      info.toBundleId,
+    ]);
+    if (lastDownloadedSelection === selection) return;
+    lastDownloadedSelection = selection;
+    didDownload = true;
+    enqueue(
+      createEvent({
+        type: "UPDATE_DOWNLOADED",
+        channel: info.channel,
+        fromBundleId: info.fromBundleId,
+        fromReleaseId: info.fromReleaseId,
+        toBundleId: info.toBundleId,
+        toReleaseId: info.toReleaseId,
+        updateStrategy: info.updateStrategy,
+        metadata: {
+          delivery: info.delivery,
+          ...(info.patchFallback ? { patchFallback: true } : {}),
+        },
+      }),
+    );
+  };
+
+  const onUpdateError = (error: UpdateError) => {
+    // A check that could not reach the server means the device is offline,
+    // and its report would not arrive either.
+    if (error.stage === "check" && error.reason === "network") return;
+    const targetBundleId = error.targetBundleId ?? error.bundleId;
+    const failureKey = [error.stage, error.reason, targetBundleId].join(" ");
+    const event = createEvent(
+      {
+        type: "UPDATE_FAILED",
+        channel: error.channel,
+        fromBundleId: error.bundleId,
+        fromReleaseId: error.releaseId,
+        toBundleId: targetBundleId,
+        toReleaseId: error.targetReleaseId ?? null,
+        updateStrategy: error.updateStrategy,
+        metadata: {
+          failure: {
+            stage: error.stage,
+            reason: error.reason,
+            ...(error.resource === undefined
+              ? {}
+              : { resource: error.resource }),
+            ...(error.httpStatus === undefined
+              ? {}
+              : { httpStatus: error.httpStatus }),
+            ...(error.transport === undefined
+              ? {}
+              : { transport: error.transport }),
+            ...(error.originCode === undefined
+              ? {}
+              : { originCode: error.originCode }),
+            ...(error.previousProcessExit === undefined
+              ? {}
+              : { previousProcessExit: error.previousProcessExit }),
+          },
+        },
+      },
+      // One id per installation, UTC day, and failure, so the server
+      // stores a repeated failure once.
+      (now, installId) =>
+        createKeyedUUIDv7(
+          [installId, utcDay(now), failureKey].join("\n"),
+          utcDayStart(now),
+        ),
+    );
+    enqueue(event === null ? null : { ...event, failureKey });
+  };
+
+  const admit = (body: InsightsEventBody): boolean => {
+    const event = pending.get(body);
+    if (event === undefined || state === null || context === null) {
+      return false;
+    }
+    if (event.superseded === true || state.isPaused(context.now())) {
+      pending.delete(body);
+      return false;
+    }
+    const admitted =
+      body.type === "UNCHANGED"
+        ? event.report === null || !state.repeatsReport(event.report)
+        : body.type === "UPDATE_FAILED"
+          ? event.failureKey === null ||
+            !state.hasFailure(event.day, event.failureKey)
+          : true;
+    if (!admitted) pending.delete(body);
+    return admitted;
+  };
+
+  const settle = (body: InsightsEventBody, delivery: InsightsDelivery) => {
+    const event = pending.get(body);
+    pending.delete(body);
+    if (event === undefined || state === null || context === null) return;
+    if (delivery === "failed") return;
+    if (delivery === "disabled") {
+      state.pause(context.now());
+      return;
+    }
+    if (event.failureKey !== null) {
+      state.recordFailure(event.day, event.failureKey);
+    }
+    if (delivery === "refused") return;
+    state.resume();
+    if (event.report !== null) state.recordReport(event.report);
+    else state.forgetReport();
+  };
+
+  return defineClientPlugin({
+    id: "insights",
+    setup(pluginContext) {
+      context = pluginContext;
+      state = createInsightsState(pluginContext.storage);
+      if (pendingUser !== null) {
+        state.writeUserId(pendingUser.userId);
+        pendingUser = null;
+      }
+      if (pluginContext.isDebugBuild && options.debug !== true) return;
+
+      send = createInsightsEventSender(pluginContext.fetch, { admit, settle });
+      return { onAppReady, onUpdateCheck, onBundleDownloaded, onUpdateError };
+    },
+    setUser(user) {
+      const userId = normalizeUserId(user);
+      if (state === null) {
+        pendingUser = { userId };
+        return;
+      }
+      state.writeUserId(userId);
+    },
+  });
+};