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

package/src/pluginHost.spec.ts

@@ -0,0 +1,297 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type {
+  HotUpdaterClientContext,
+  HotUpdaterClientPlugin,
+} from "./clientPlugin";
+
+vi.mock("react-native", () => ({
+  Platform: { OS: "android" },
+}));
+
+const mocks = vi.hoisted(() => {
+  Reflect.set(globalThis, "HotUpdater", { SDK_VERSION: "test-sdk-version" });
+  return {
+    getAppVersion: vi.fn<() => string | null>(() => "1.2.3"),
+    getBundleId: vi.fn(() => "bundle-id"),
+    getChannel: vi.fn(() => "production"),
+    getCohort: vi.fn(() => "123"),
+    getFingerprintHash: vi.fn<() => string | null>(() => null),
+    getInstallId: vi.fn(() => "install-id"),
+    getStorageItem: vi.fn<(key: string) => string | null>(() => null),
+    setStorageItem: vi.fn<(key: string, value: string | null) => void>(),
+  };
+});
+
+vi.mock("./native", () => mocks);
+
+const importHost = () => import("./pluginHost");
+
+const capture = (id = "example") => {
+  let context!: HotUpdaterClientContext;
+  const setup = vi.fn((pluginContext: HotUpdaterClientContext) => {
+    context = pluginContext;
+  });
+  const plugin: HotUpdaterClientPlugin = { id, setup };
+  return { plugin, setup, context: () => context };
+};
+
+describe("client plugin host", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    for (const mock of Object.values(mocks)) mock.mockClear();
+    mocks.getStorageItem.mockReturnValue(null);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("throws at configuration for two plugins with one id", async () => {
+    const { configurePlugins } = await importHost();
+
+    expect(() =>
+      configurePlugins([capture("same").plugin, capture("same").plugin], {
+        baseURL: "https://updates.example.com",
+      }),
+    ).toThrow('Two plugins use the id "same"');
+  });
+
+  it("sets a plugin up once and stops calling a plugin left out", async () => {
+    const { configurePlugins, emitPluginHook } = await importHost();
+    const onAppReady = vi.fn();
+    const plugin: HotUpdaterClientPlugin = {
+      id: "example",
+      setup: vi.fn(() => ({ onAppReady })),
+    };
+    const config = { baseURL: "https://updates.example.com" };
+
+    configurePlugins([plugin], config);
+    configurePlugins([plugin], config);
+    emitPluginHook("onAppReady", () => ({
+      status: "UNCHANGED",
+      channel: "production",
+      bundleId: "bundle-id",
+      releaseId: null,
+      previousProcessExit: null,
+    }));
+    configurePlugins([], config);
+    emitPluginHook("onAppReady", () => ({
+      status: "UNCHANGED",
+      channel: "production",
+      bundleId: "bundle-id",
+      releaseId: null,
+      previousProcessExit: null,
+    }));
+
+    expect(plugin.setup).toHaveBeenCalledOnce();
+    expect(onAppReady).toHaveBeenCalledOnce();
+  });
+
+  it("warns without onError when setup throws, and keeps other plugins", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { configurePlugins } = await importHost();
+    const healthy = capture("healthy");
+
+    configurePlugins(
+      [
+        {
+          id: "broken",
+          setup: () => {
+            throw new Error("setup failed");
+          },
+        },
+        healthy.plugin,
+      ],
+      { baseURL: "https://updates.example.com" },
+    );
+
+    expect(healthy.setup).toHaveBeenCalledOnce();
+    expect(warn).toHaveBeenCalledWith(
+      '[HotUpdater] Plugin "broken" failed in setup',
+      expect.objectContaining({ message: "setup failed" }),
+    );
+  });
+
+  it("never waits for a hook", async () => {
+    const { configurePlugins, emitPluginHook } = await importHost();
+    const onUpdateCheck = vi.fn(() => new Promise<void>(() => {}));
+    configurePlugins([{ id: "slow", setup: () => ({ onUpdateCheck }) }], {
+      baseURL: "https://updates.example.com",
+    });
+
+    const result = emitPluginHook("onUpdateCheck", () => ({
+      status: "UNCHANGED",
+      channel: "production",
+      bundleId: "bundle-id",
+      releaseId: null,
+      previousReleaseId: null,
+    }));
+
+    expect(result).toBeUndefined();
+    expect(onUpdateCheck).toHaveBeenCalledOnce();
+  });
+
+  it("builds an event only when a plugin listens", async () => {
+    const { configurePlugins, emitPluginHook } = await importHost();
+    configurePlugins([capture().plugin], {
+      baseURL: "https://updates.example.com",
+    });
+    const createPayload = vi.fn(() => null);
+
+    emitPluginHook("onUpdateError", createPayload);
+
+    expect(createPayload).not.toHaveBeenCalled();
+  });
+
+  it("exposes the app's identity and environment", async () => {
+    vi.stubGlobal("__DEV__", true);
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    const { configurePlugins } = await importHost();
+    const plugin = capture();
+    configurePlugins([plugin.plugin], {
+      baseURL: "https://updates.example.com",
+    });
+    const context = plugin.context();
+
+    expect({
+      appVersion: context.appVersion,
+      bundleId: context.getBundleId(),
+      channel: context.getChannel(),
+      cohort: context.getCohort(),
+      fingerprintHash: context.getFingerprintHash(),
+      installId: context.installId,
+      isDebugBuild: context.isDebugBuild,
+      now: context.now(),
+      platform: context.platform,
+      sdkVersion: context.sdkVersion,
+    }).toEqual({
+      appVersion: "1.2.3",
+      bundleId: "bundle-id",
+      channel: "production",
+      cohort: "123",
+      fingerprintHash: null,
+      installId: "install-id",
+      isDebugBuild: true,
+      now: 1_700_000_000_000,
+      platform: "android",
+      sdkVersion: "test-sdk-version",
+    });
+  });
+
+  describe("fetch", () => {
+    it("requests a path under the resolved baseURL with the SDK's headers", async () => {
+      const fetchMock = vi.fn<typeof fetch>(
+        async () => new Response(null, { status: 204 }),
+      );
+      vi.stubGlobal("fetch", fetchMock);
+      const { configurePlugins } = await importHost();
+      const plugin = capture();
+      configurePlugins([plugin.plugin], {
+        baseURL: async () => "https://updates.example.com/hot-updater/",
+        requestHeaders: { "x-api-key": "client-key", "X-Shared": "sdk" },
+      });
+
+      await plugin.context().fetch("/events", {
+        headers: { "Content-Type": "application/json", "X-Shared": "plugin" },
+        method: "POST",
+      });
+
+      const [url, init] = fetchMock.mock.calls[0]!;
+      expect(url).toBe("https://updates.example.com/hot-updater/events");
+      expect(init?.method).toBe("POST");
+      const headers = new Headers(init?.headers);
+      expect(headers.get("x-api-key")).toBe("client-key");
+      expect(headers.get("content-type")).toBe("application/json");
+      expect(headers.get("x-shared")).toBe("plugin");
+    });
+
+    it("rejects with Request timed out after the SDK's timeout", async () => {
+      vi.useFakeTimers();
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          (_input: unknown, init?: RequestInit) =>
+            new Promise((_resolve, reject) => {
+              init?.signal?.addEventListener("abort", () => {
+                reject(
+                  Object.assign(new Error("aborted"), { name: "AbortError" }),
+                );
+              });
+            }),
+        ),
+      );
+      const { configurePlugins } = await importHost();
+      const plugin = capture();
+      configurePlugins([plugin.plugin], {
+        baseURL: "https://updates.example.com",
+        requestTimeout: 2_000,
+      });
+
+      const request = plugin.context().fetch("events");
+      const settled = expect(request).rejects.toThrow("Request timed out");
+      await vi.advanceTimersByTimeAsync(2_000);
+      await settled;
+    });
+
+    it("refuses a URL outside baseURL", async () => {
+      const { configurePlugins } = await importHost();
+      const plugin = capture();
+      configurePlugins([plugin.plugin], {
+        baseURL: "https://updates.example.com",
+      });
+
+      await expect(
+        plugin.context().fetch("https://elsewhere.example.com/events"),
+      ).rejects.toThrow("relative to baseURL");
+    });
+  });
+
+  describe("storage", () => {
+    it("scopes keys to the plugin and reads its own writes", async () => {
+      mocks.getStorageItem.mockReturnValue("from-native");
+      const { configurePlugins } = await importHost();
+      const plugin = capture("example");
+      configurePlugins([plugin.plugin], {
+        baseURL: "https://updates.example.com",
+      });
+      const { storage } = plugin.context();
+
+      expect(storage.get("state")).toBe("from-native");
+      expect(storage.get("state")).toBe("from-native");
+      storage.set("state", "next");
+      expect(storage.get("state")).toBe("next");
+      storage.set("state", null);
+      expect(storage.get("state")).toBeNull();
+
+      expect(mocks.getStorageItem).toHaveBeenCalledOnce();
+      expect(mocks.getStorageItem).toHaveBeenCalledWith(
+        "plugins/example/state",
+      );
+      expect(mocks.setStorageItem.mock.calls).toEqual([
+        ["plugins/example/state", "next"],
+        ["plugins/example/state", null],
+      ]);
+    });
+
+    it("refuses empty keys, non-string values, and values over 64 KB", async () => {
+      const { configurePlugins } = await importHost();
+      const plugin = capture();
+      configurePlugins([plugin.plugin], {
+        baseURL: "https://updates.example.com",
+      });
+      const { storage } = plugin.context();
+
+      expect(() => storage.get("")).toThrow("non-empty strings");
+      expect(() => storage.set("key", 1 as unknown as string)).toThrow(
+        "strings or null",
+      );
+      expect(() => storage.set("key", "x".repeat(64 * 1024 + 1))).toThrow(
+        "at most 64 KB",
+      );
+      expect(mocks.setStorageItem).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/pluginHost.ts

@@ -0,0 +1,262 @@
+import { Platform } from "react-native";
+
+import { resolveBaseURL } from "./baseURL";
+import type {
+  HotUpdaterClientContext,
+  HotUpdaterClientHooks,
+  HotUpdaterClientPlugin,
+  HotUpdaterClientStorage,
+} from "./clientPlugin";
+import {
+  getAppVersion,
+  getBundleId,
+  getChannel,
+  getCohort,
+  getFingerprintHash,
+  getInstallId,
+  getStorageItem,
+  setStorageItem,
+} from "./native";
+import { HOT_UPDATER_SDK_VERSION } from "./sdkVersion";
+import type { HotUpdaterBaseURL } from "./types";
+
+type HookName = keyof HotUpdaterClientHooks;
+type HookPayload<K extends HookName> = Parameters<
+  NonNullable<HotUpdaterClientHooks[K]>
+>[0];
+
+/** The init or wrap settings plugins see through their context. */
+export interface PluginHostConfig {
+  readonly baseURL: HotUpdaterBaseURL;
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  readonly onError?: (error: unknown) => void;
+}
+
+/** Storage values stay small, since native reads them on the JS thread. */
+const MAX_STORAGE_VALUE_LENGTH = 64 * 1024;
+
+let config: PluginHostConfig | null = null;
+/** Hooks by plugin, so a plugin configured again is not set up twice. */
+const setUpPlugins = new WeakMap<
+  HotUpdaterClientPlugin,
+  HotUpdaterClientHooks
+>();
+let activePlugins: readonly {
+  readonly plugin: HotUpdaterClientPlugin;
+  readonly hooks: HotUpdaterClientHooks;
+}[] = [];
+/** What plugins read and wrote, so a read follows a write before native does. */
+const storageValues = new Map<string, string | null>();
+
+const reportHookError = (message: string, error: unknown) => {
+  const report = new Error(`[HotUpdater] ${message}`, { cause: error });
+  try {
+    if (config?.onError) {
+      config.onError(report);
+      return;
+    }
+  } catch {
+    // A throwing onError must not break the update path either.
+  }
+  console.warn(report.message, error);
+};
+
+const fetchFromServer = async (
+  path: string,
+  init: RequestInit = {},
+): Promise<Response> => {
+  if (config === null) {
+    throw new Error("[HotUpdater] Plugins can fetch only after init or wrap.");
+  }
+  if (/^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith("//")) {
+    throw new TypeError(
+      "[HotUpdater] Plugin fetch takes a path relative to baseURL.",
+    );
+  }
+  const { requestHeaders, requestTimeout } = config;
+  const url = `${await resolveBaseURL(config.baseURL)}/${path.replace(/^\/+/, "")}`;
+  const headers = new Headers(requestHeaders);
+  new Headers(init.headers).forEach((value, name) => {
+    headers.set(name, value);
+  });
+
+  const controller = new AbortController();
+  const callerSignal = init.signal;
+  const abortFromCaller = () => controller.abort();
+  if (callerSignal?.aborted) controller.abort();
+  callerSignal?.addEventListener("abort", abortFromCaller);
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    requestTimeout ?? 5000,
+  );
+
+  try {
+    return await fetch(url, { ...init, headers, signal: controller.signal });
+  } catch (error: unknown) {
+    if (
+      error instanceof Error &&
+      error.name === "AbortError" &&
+      !callerSignal?.aborted
+    ) {
+      throw new Error("Request timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+    callerSignal?.removeEventListener("abort", abortFromCaller);
+  }
+};
+
+const createStorage = (pluginId: string): HotUpdaterClientStorage => {
+  const scopedKey = (key: string) => {
+    if (typeof key !== "string" || key.length === 0) {
+      throw new TypeError(
+        "[HotUpdater] Plugin storage keys are non-empty strings.",
+      );
+    }
+    // Encoded, so no id and key pair can name another plugin's key.
+    return `plugins/${encodeURIComponent(pluginId)}/${key}`;
+  };
+
+  return {
+    get: (key) => {
+      const storageKey = scopedKey(key);
+      const cached = storageValues.get(storageKey);
+      if (cached !== undefined) return cached;
+      const value = getStorageItem(storageKey);
+      storageValues.set(storageKey, value);
+      return value;
+    },
+    set: (key, value) => {
+      const storageKey = scopedKey(key);
+      if (value !== null && typeof value !== "string") {
+        throw new TypeError(
+          "[HotUpdater] Plugin storage values are strings or null.",
+        );
+      }
+      if (value !== null && value.length > MAX_STORAGE_VALUE_LENGTH) {
+        throw new RangeError(
+          "[HotUpdater] Plugin storage values are at most 64 KB.",
+        );
+      }
+      setStorageItem(storageKey, value);
+      storageValues.set(storageKey, value);
+    },
+  };
+};
+
+const createContext = (pluginId: string): HotUpdaterClientContext => ({
+  fetch: fetchFromServer,
+  get installId() {
+    return getInstallId();
+  },
+  platform: Platform.OS === "android" ? "android" : "ios",
+  get appVersion() {
+    return getAppVersion();
+  },
+  get sdkVersion() {
+    return HOT_UPDATER_SDK_VERSION;
+  },
+  isDebugBuild: typeof __DEV__ !== "undefined" && __DEV__,
+  getBundleId,
+  getChannel,
+  getCohort,
+  getFingerprintHash,
+  storage: createStorage(pluginId),
+  now: () => Date.now(),
+});
+
+/**
+ * Sets up the plugins of an init or wrap call. A plugin passed to an earlier
+ * call keeps its hooks, and a plugin left out stops receiving events.
+ */
+export const configurePlugins = (
+  plugins: readonly HotUpdaterClientPlugin[] | undefined,
+  nextConfig: PluginHostConfig,
+): void => {
+  const ids = new Set<string>();
+  for (const plugin of plugins ?? []) {
+    if (typeof plugin.id !== "string" || plugin.id.length === 0) {
+      throw new Error("[HotUpdater] A plugin id must be a non-empty string.");
+    }
+    if (ids.has(plugin.id)) {
+      throw new Error(
+        `[HotUpdater] Two plugins use the id "${plugin.id}". Plugin ids must be unique.`,
+      );
+    }
+    ids.add(plugin.id);
+  }
+
+  config = nextConfig;
+  activePlugins = (plugins ?? []).map((plugin) => {
+    let hooks = setUpPlugins.get(plugin);
+    if (hooks === undefined) {
+      try {
+        hooks = plugin.setup(createContext(plugin.id)) ?? {};
+      } catch (error) {
+        reportHookError(`Plugin "${plugin.id}" failed in setup`, error);
+        hooks = {};
+      }
+      setUpPlugins.set(plugin, hooks);
+    }
+    return { plugin, hooks };
+  });
+};
+
+/** Whether any plugin listens to this hook, so callers build events only when one does. */
+export const hasPluginHook = (name: HookName): boolean =>
+  activePlugins.some(({ hooks }) => typeof hooks[name] === "function");
+
+/**
+ * Builds a hook's event when a plugin listens. A failure to build it is
+ * reported, not thrown, since reporting never changes an update.
+ */
+export const buildPluginEvent = <K extends HookName>(
+  name: K,
+  createPayload: () => HookPayload<K> | null,
+): HookPayload<K> | null => {
+  if (!hasPluginHook(name)) return null;
+  try {
+    return createPayload();
+  } catch (error) {
+    reportHookError(`Failed to build the ${name} event for plugins`, error);
+    return null;
+  }
+};
+
+/** Calls a hook on every plugin that listens, without waiting for any. */
+export const dispatchPluginHook = <K extends HookName>(
+  name: K,
+  payload: HookPayload<K>,
+): void => {
+  for (const { plugin, hooks } of activePlugins) {
+    const hook = hooks[name] as
+      | ((payload: HookPayload<K>) => unknown)
+      | undefined;
+    if (typeof hook !== "function") continue;
+    try {
+      const result = hook.call(hooks, payload);
+      if (
+        result !== null &&
+        typeof result === "object" &&
+        typeof (result as PromiseLike<unknown>).then === "function"
+      ) {
+        void Promise.resolve(result).catch((error: unknown) => {
+          reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+        });
+      }
+    } catch (error) {
+      reportHookError(`Plugin "${plugin.id}" failed in ${name}`, error);
+    }
+  }
+};
+
+/** Builds a hook's event when a plugin listens and calls the hook right away. */
+export const emitPluginHook = <K extends HookName>(
+  name: K,
+  createPayload: () => HookPayload<K> | null,
+): void => {
+  const payload = buildPluginEvent(name, createPayload);
+  if (payload !== null) dispatchPluginHook(name, payload);
+};

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

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+
+import { isUUIDv7 } from "@hot-updater/core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createKeyedUUIDv7, createUUIDv7, sha256 } from "./eventId";
+
+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);
+  });
+});
+
+describe("sha256", () => {
+  it.each([
+    "",
+    "abc",
+    "a".repeat(55),
+    "a".repeat(56),
+    "a".repeat(64),
+    "a".repeat(1_000),
+    "install-id\n2026-09-30\ndownload hash_mismatch bundle-id",
+    "한글 및 이모지 😀",
+  ])("matches Node's SHA-256 for %j", (value) => {
+    expect(Buffer.from(sha256(value)).toString("hex")).toBe(
+      createHash("sha256").update(value, "utf8").digest("hex"),
+    );
+  });
+});
+
+describe("createKeyedUUIDv7", () => {
+  it("gives one UUIDv7 per key and time, led by that time", () => {
+    const midnight = Date.UTC(2026, 8, 30);
+
+    const id = createKeyedUUIDv7("install-id\nfailure", midnight);
+
+    expect(isUUIDv7(id)).toBe(true);
+    expect(parseInt(id.replace(/-/g, "").slice(0, 12), 16)).toBe(midnight);
+    expect(createKeyedUUIDv7("install-id\nfailure", midnight)).toBe(id);
+    expect(createKeyedUUIDv7("install-id\nother", midnight)).not.toBe(id);
+    expect(
+      createKeyedUUIDv7("install-id\nfailure", midnight + 86_400_000),
+    ).not.toBe(id);
+  });
+});