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

package/src/plugins/insights/sender.spec.ts

@@ -0,0 +1,287 @@
+import { isUUIDv7 } from "@hot-updater/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createUUIDv7 } from "./eventId";
+import {
+  createInsightsEventSender,
+  type InsightsEventBody,
+  type InsightsEventGate,
+} from "./sender";
+
+const unchangedEvent = (): InsightsEventBody => ({
+  appVersion: "1.0.0",
+  channel: "production",
+  cohort: "123",
+  eventId: createUUIDv7(),
+  fingerprintHash: null,
+  fromBundleId: null,
+  fromReleaseId: null,
+  installId: "install-id",
+  platform: "ios",
+  sdkVersion: "test-sdk-version",
+  toBundleId: "bundle-id",
+  toReleaseId: null,
+  type: "UNCHANGED",
+  updateStrategy: null,
+});
+
+const downloadedEvent = (): InsightsEventBody => ({
+  ...unchangedEvent(),
+  fromBundleId: "bundle-id",
+  toBundleId: "next-bundle-id",
+  type: "UPDATE_DOWNLOADED",
+  updateStrategy: "appVersion",
+});
+
+/** Answers each POST /events with the next response, then 204. */
+const stubEventsEndpoint = (...responses: (number | Response | Error)[]) => {
+  const fetchMock = vi.fn(
+    async (_path: string, _init?: RequestInit): Promise<Response> => {
+      const next = responses.shift() ?? 204;
+      if (next instanceof Error) throw next;
+      return typeof next === "number"
+        ? new Response(null, { status: next })
+        : next;
+    },
+  );
+  const sentEvents = () =>
+    fetchMock.mock.calls.map(
+      ([, init]) => JSON.parse(String(init?.body)) as InsightsEventBody,
+    );
+  return { fetchMock, sentEvents };
+};
+
+const openGate = () => ({
+  admit: () => true,
+  settle: vi.fn<InsightsEventGate["settle"]>(),
+});
+
+describe("Insights event delivery", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // No jitter: the first retry waits exactly 1 s and the second 2 s.
+    vi.spyOn(Math, "random").mockReturnValue(0.5);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("posts to events and retries a 503 in the background under the same UUIDv7 eventId", async () => {
+    const { fetchMock, sentEvents } = stubEventsEndpoint(503, 204);
+    const gate = openGate();
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    // Settles after the failed first attempt, without waiting for the retry.
+    await send(unchangedEvent());
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock.mock.calls[0]?.[0]).toBe("events");
+    expect(fetchMock.mock.calls[0]?.[1]?.method).toBe("POST");
+
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    const [first, second] = sentEvents();
+    expect(isUUIDv7(first?.eventId)).toBe(true);
+    expect(second?.eventId).toBe(first?.eventId);
+    expect(gate.settle).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ type: "UNCHANGED" }),
+      "delivered",
+    );
+  });
+
+  it("waits for a 429's Retry-After before the next attempt", async () => {
+    const { fetchMock } = stubEventsEndpoint(
+      new Response(null, { headers: { "Retry-After": "7" }, status: 429 }),
+    );
+    const send = createInsightsEventSender(fetchMock, openGate());
+
+    await send(unchangedEvent());
+    await vi.advanceTimersByTimeAsync(6_999);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("caps a server's Retry-After at 30 seconds", async () => {
+    const { fetchMock } = stubEventsEndpoint(
+      new Response(null, { headers: { "Retry-After": "3600" }, status: 503 }),
+    );
+    const send = createInsightsEventSender(fetchMock, openGate());
+
+    await send(unchangedEvent());
+    await vi.advanceTimersByTimeAsync(29_999);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not retry a 400", async () => {
+    const { fetchMock } = stubEventsEndpoint(400);
+    const gate = openGate();
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await expect(send(unchangedEvent())).rejects.toThrow(
+      "Expected HTTP 204 from /events, received 400",
+    );
+    await vi.runAllTimersAsync();
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(gate.settle).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "UNCHANGED" }),
+      "failed",
+    );
+  });
+
+  it("settles an UPDATE_FAILED event an older server refuses with 400, without retrying", async () => {
+    const { fetchMock } = stubEventsEndpoint(400);
+    const gate = openGate();
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await send({ ...unchangedEvent(), type: "UPDATE_FAILED" });
+    await vi.runAllTimersAsync();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(gate.settle).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "UPDATE_FAILED" }),
+      "refused",
+    );
+  });
+
+  it("settles a 404, from a server without Insights, as Insights off without retrying", async () => {
+    const { fetchMock } = stubEventsEndpoint(404);
+    const gate = openGate();
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await send(unchangedEvent());
+    await vi.runAllTimersAsync();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(gate.settle).toHaveBeenCalledWith(
+      expect.objectContaining({ type: "UNCHANGED" }),
+      "disabled",
+    );
+  });
+
+  it("skips an event the gate does not admit", async () => {
+    const { fetchMock } = stubEventsEndpoint();
+    const gate = { admit: vi.fn(() => false), settle: vi.fn() };
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await send(unchangedEvent());
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(gate.settle).not.toHaveBeenCalled();
+  });
+
+  it("asks the gate before every attempt, after earlier events settled", async () => {
+    const { fetchMock } = stubEventsEndpoint(503, 204);
+    const order: string[] = [];
+    const gate: InsightsEventGate = {
+      admit: (event) => {
+        order.push(`admit ${event.type}`);
+        return true;
+      },
+      settle: (event, delivery) => {
+        order.push(`${delivery} ${event.type}`);
+      },
+    };
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await send(unchangedEvent());
+    await send(downloadedEvent());
+    await vi.runAllTimersAsync();
+
+    expect(order).toEqual([
+      "admit UNCHANGED",
+      "admit UNCHANGED",
+      "delivered UNCHANGED",
+      "admit UPDATE_DOWNLOADED",
+      "delivered UPDATE_DOWNLOADED",
+    ]);
+  });
+
+  it("drops an event the gate stops admitting during its backoff", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { fetchMock, sentEvents } = stubEventsEndpoint(503);
+    let wanted = true;
+    const gate = { admit: vi.fn(() => wanted), settle: vi.fn() };
+    const send = createInsightsEventSender(fetchMock, gate);
+
+    await send({ ...unchangedEvent(), type: "UPDATE_FAILED" });
+    wanted = false;
+    await vi.runAllTimersAsync();
+    wanted = true;
+    await send(downloadedEvent());
+
+    expect(sentEvents().map(({ type }) => type)).toEqual([
+      "UPDATE_FAILED",
+      "UPDATE_DOWNLOADED",
+    ]);
+    expect(gate.settle).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ type: "UPDATE_DOWNLOADED" }),
+      "delivered",
+    );
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("stops after three attempts and warns once", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { fetchMock } = stubEventsEndpoint(
+      500,
+      new Error("network unavailable"),
+      503,
+    );
+    const send = createInsightsEventSender(fetchMock, openGate());
+
+    await send(unchangedEvent());
+    await vi.runAllTimersAsync();
+
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(warn).toHaveBeenCalledExactlyOnceWith(
+      "[HotUpdater] Insights UNCHANGED event was not delivered:",
+      expect.objectContaining({
+        message: "Expected HTTP 204 from /events, received 503",
+      }),
+    );
+  });
+
+  it("sends a later event after an earlier event's retries without holding its caller", async () => {
+    const { fetchMock, sentEvents } = stubEventsEndpoint(503);
+    const send = createInsightsEventSender(fetchMock, openGate());
+
+    await send(unchangedEvent());
+    await send(downloadedEvent());
+    expect(fetchMock).toHaveBeenCalledOnce();
+
+    await vi.runAllTimersAsync();
+    const [first, retry, later] = sentEvents();
+    expect([first?.type, retry?.type, later?.type]).toEqual([
+      "UNCHANGED",
+      "UNCHANGED",
+      "UPDATE_DOWNLOADED",
+    ]);
+    expect(retry?.eventId).toBe(first?.eventId);
+    expect(later?.eventId).not.toBe(first?.eventId);
+  });
+
+  it("keeps sending events after one fails outside its requests", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {
+      throw new Error("console unavailable");
+    });
+    const { fetchMock, sentEvents } = stubEventsEndpoint(500, 500, 500);
+    const send = createInsightsEventSender(fetchMock, openGate());
+
+    await send(unchangedEvent());
+    await vi.runAllTimersAsync();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    // A queue left rejected would never send this event or settle its caller.
+    await send(downloadedEvent());
+    expect(sentEvents().map(({ type }) => type)).toEqual([
+      "UNCHANGED",
+      "UNCHANGED",
+      "UNCHANGED",
+      "UPDATE_DOWNLOADED",
+    ]);
+  });
+});

package/src/plugins/insights/sender.ts

@@ -0,0 +1,221 @@
+import type { HotUpdaterClientContext } from "../../clientPlugin";
+
+export type InsightsEventType =
+  | "UNCHANGED"
+  | "UPDATE_DOWNLOADED"
+  | "UPDATE_APPLIED"
+  | "RECOVERED"
+  | "UPDATE_FAILED";
+
+/** A `POST /events` body. */
+export interface InsightsEventBody {
+  readonly eventId: string;
+  readonly type: InsightsEventType;
+  readonly installId: string;
+  readonly userId?: string;
+  readonly platform: "ios" | "android";
+  readonly appVersion: string;
+  readonly channel: string;
+  readonly cohort: string;
+  readonly fingerprintHash: string | null;
+  readonly sdkVersion: string;
+  readonly fromBundleId: string | null;
+  readonly fromReleaseId: string | null;
+  readonly toBundleId: string;
+  readonly toReleaseId: string | null;
+  readonly updateStrategy: "fingerprint" | "appVersion" | null;
+  readonly metadata?: InsightsEventMetadata;
+}
+
+/** Details beside an event's fields, by event type. */
+export interface InsightsEventMetadata {
+  /** UPDATE_FAILED: where and why the update failed. */
+  readonly failure?: {
+    readonly stage: "check" | "download" | "install";
+    readonly reason: string;
+    readonly resource?: string;
+    readonly httpStatus?: number;
+    readonly transport?: string;
+    readonly originCode?: string;
+    readonly previousProcessExit?: string;
+  };
+  /** UPDATE_DOWNLOADED: how the bundle arrived. */
+  readonly delivery?: "patch" | "manifest" | "archive";
+  /** UPDATE_DOWNLOADED: a patch was tried, but a file or the archive came instead. */
+  readonly patchFallback?: true;
+  /** RECOVERED: why the previous main process exited, on Android 11+. */
+  readonly previousProcessExit?: string;
+}
+
+/** How the server answered one event. */
+export type InsightsDelivery =
+  /** The server stored the event, or already had it under its id. */
+  | "delivered"
+  /** The server runs without Insights: a 404, since it mounts no `/events`. */
+  | "disabled"
+  /** A 400 for an `UPDATE_FAILED` event, from a server that does not know it. */
+  | "refused"
+  /** No attempt got an answer the SDK accepts. */
+  | "failed";
+
+export interface InsightsEventGate {
+  /**
+   * Whether to send the event now. It is asked before every attempt, so an
+   * event superseded while it waits out a backoff is dropped.
+   */
+  admit(event: InsightsEventBody): boolean;
+  /** Records how an admitted event ended, once per event. */
+  settle(event: InsightsEventBody, delivery: InsightsDelivery): void;
+}
+
+/** 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 the context's timeout, and settles with its outcome. */
+const postInsightsEvent = async (
+  fetch: HotUpdaterClientContext["fetch"],
+  event: InsightsEventBody,
+): Promise<Exclude<InsightsDelivery, "failed"> | InsightsAttemptFailure> => {
+  try {
+    const response = await fetch("events", {
+      body: JSON.stringify(event),
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+    });
+
+    if (response.status === 204) return "delivered";
+    if (response.status === 404) return "disabled";
+    if (response.status === 400 && event.type === "UPDATE_FAILED") {
+      return "refused";
+    }
+    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) {
+    // 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 : new Error(String(error)),
+      retryable: true,
+      retryAfterMs: null,
+    };
+  }
+};
+
+export type InsightsEventSender = (event: InsightsEventBody) => 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 wait only for first attempts, so a report never waits out a
+ * backoff: once an event backs off, every waiting caller is released, and a
+ * failure after that only warns. The gate sees each event before each
+ * attempt, after every earlier event settled, so it decides with what the
+ * server already answered.
+ */
+export const createInsightsEventSender = (
+  fetch: HotUpdaterClientContext["fetch"],
+  gate: InsightsEventGate,
+): InsightsEventSender => {
+  let queue = Promise.resolve();
+  let retrying = false;
+  const waiting = new Set<() => void>();
+
+  return (event) =>
+    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) {
+            if (!gate.admit(event)) {
+              release();
+              break;
+            }
+            const outcome = await postInsightsEvent(fetch, event);
+            if (typeof outcome === "string") {
+              gate.settle(event, outcome);
+              release();
+              break;
+            }
+            if (!outcome.retryable || attempt === INSIGHTS_MAX_ATTEMPTS) {
+              gate.settle(event, "failed");
+              waiting.delete(release);
+              if (released) {
+                console.warn(
+                  `[HotUpdater] Insights ${event.type} event was not delivered:`,
+                  outcome.error,
+                );
+              } else {
+                reject(outcome.error);
+              }
+              break;
+            }
+            retrying = true;
+            for (const releaseWaiting of waiting) releaseWaiting();
+            await wait(getRetryDelayMs(attempt, outcome.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 waiting on one, pending forever.
+          waiting.delete(release);
+          if (!released) reject(error);
+        } finally {
+          retrying = false;
+        }
+      });
+    });
+};

package/src/plugins/insights/state.ts

@@ -0,0 +1,184 @@
+import type { HotUpdaterClientStorage } from "../../clientPlugin";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** A day's failure keys kept, so a failing app cannot grow its storage. */
+const MAX_FAILURE_KEYS = 32;
+
+/** The UTC day of a time, as `YYYY-MM-DD`. */
+export const utcDay = (time: number): string =>
+  new Date(time).toISOString().slice(0, 10);
+
+/** The start of a time's UTC day, in milliseconds. */
+export const utcDayStart = (time: number): number =>
+  Math.floor(time / DAY_MS) * DAY_MS;
+
+/** What a report says runs: the fields the server compares to skip a same-day launch. */
+export interface RunningReport {
+  readonly day: string;
+  readonly channel: string;
+  readonly appVersion: string;
+  readonly bundleId: string;
+  readonly releaseId: string | null;
+  readonly userId: string | null;
+}
+
+const sameReport = (left: RunningReport, right: RunningReport): boolean =>
+  left.day === right.day &&
+  left.channel === right.channel &&
+  left.appVersion === right.appVersion &&
+  left.bundleId === right.bundleId &&
+  left.releaseId === right.releaseId &&
+  left.userId === right.userId;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isNullableString = (value: unknown): value is string | null =>
+  value === null || typeof value === "string";
+
+const parseReport = (value: string | null): RunningReport | null => {
+  if (value === null) return null;
+  try {
+    const report: unknown = JSON.parse(value);
+    if (
+      isRecord(report) &&
+      typeof report.day === "string" &&
+      typeof report.channel === "string" &&
+      typeof report.appVersion === "string" &&
+      typeof report.bundleId === "string" &&
+      isNullableString(report.releaseId) &&
+      isNullableString(report.userId)
+    ) {
+      return {
+        day: report.day,
+        channel: report.channel,
+        appVersion: report.appVersion,
+        bundleId: report.bundleId,
+        releaseId: report.releaseId,
+        userId: report.userId,
+      };
+    }
+  } catch {
+    // An unreadable value counts as none.
+  }
+  return null;
+};
+
+const parseFailures = (
+  value: string | null,
+): { readonly day: string; readonly keys: readonly string[] } | null => {
+  if (value === null) return null;
+  try {
+    const failures: unknown = JSON.parse(value);
+    if (
+      isRecord(failures) &&
+      typeof failures.day === "string" &&
+      Array.isArray(failures.keys) &&
+      failures.keys.every((key) => typeof key === "string")
+    ) {
+      return { day: failures.day, keys: failures.keys as string[] };
+    }
+  } catch {
+    // An unreadable value counts as none.
+  }
+  return null;
+};
+
+/**
+ * The Insights plugin's memory across launches, in its plugin storage. Every
+ * read tolerates a missing or unreadable value, and a storage failure only
+ * costs a report that would otherwise have been skipped.
+ */
+export const createInsightsState = (storage: HotUpdaterClientStorage) => {
+  /** The server said Insights is off during this runtime. */
+  let pausedThisRuntime = false;
+
+  const read = (key: string): string | null => {
+    try {
+      return storage.get(key);
+    } catch {
+      return null;
+    }
+  };
+  const write = (key: string, value: string | null) => {
+    try {
+      storage.set(key, value);
+    } catch {
+      // Losing the state costs a report, never an update.
+    }
+  };
+
+  return {
+    /**
+     * Whether reporting pauses: the server answered that Insights is off
+     * during this runtime or in the 24 hours before `now`. A pause that
+     * starts after `now`, from a clock that went back, has ended.
+     */
+    isPaused(now: number): boolean {
+      if (pausedThisRuntime) return true;
+      const pausedAt = Number(read("pausedAt"));
+      return (
+        Number.isFinite(pausedAt) &&
+        pausedAt > 0 &&
+        pausedAt <= now &&
+        now < pausedAt + DAY_MS
+      );
+    },
+    pause(now: number) {
+      pausedThisRuntime = true;
+      write("pausedAt", String(now));
+    },
+    /** The server stored a report, so Insights is on. */
+    resume() {
+      if (read("pausedAt") !== null) write("pausedAt", null);
+    },
+
+    /** Whether a launch report repeats what the installation reported that day. */
+    repeatsReport(report: RunningReport): boolean {
+      const last = parseReport(read("report"));
+      return last !== null && sameReport(last, report);
+    },
+    /** Records a delivered report that says what runs. */
+    recordReport(report: RunningReport) {
+      write("report", JSON.stringify(report));
+    },
+    /**
+     * Forgets the last report after a delivered download or failure, so the
+     * next launch reports again, as the server records it after one.
+     */
+    forgetReport() {
+      if (read("report") !== null) write("report", null);
+    },
+
+    /** Whether a failure was already reported, or refused, that day. */
+    hasFailure(day: string, key: string): boolean {
+      const failures = parseFailures(read("failures"));
+      return failures?.day === day && failures.keys.includes(key);
+    },
+    recordFailure(day: string, key: string) {
+      const failures = parseFailures(read("failures"));
+      const keys = failures?.day === day ? failures.keys : [];
+      if (keys.includes(key)) return;
+      write(
+        "failures",
+        JSON.stringify({ day, keys: [...keys, key].slice(-MAX_FAILURE_KEYS) }),
+      );
+    },
+
+    readUserId(): string | null {
+      try {
+        const user: unknown = JSON.parse(read("user") ?? "null");
+        return isRecord(user) && typeof user.userId === "string"
+          ? user.userId
+          : null;
+      } catch {
+        return null;
+      }
+    },
+    writeUserId(userId: string | null) {
+      write("user", userId === null ? null : JSON.stringify({ userId }));
+    },
+  };
+};
+
+export type InsightsState = ReturnType<typeof createInsightsState>;