@hot-updater/react-native 0.36.7 → 1.0.0-rc.0

package/src/checkForUpdate.ts

@@ -1,23 +1,40 @@
-import type { AppUpdateAvailableInfo, AppUpdateInfo } from "@hot-updater/core";
+import {
+  authorizeReleaseTransition,
+  createReleaseSelectionContextHash,
+  encodeChannelKey,
+  selectDesiredRelease,
+  type ArtifactInfo,
+  type PersistedSelectionReceipt,
+  type ReleaseCatalog,
+} from "@hot-updater/core";
+import { canonicalizeAppVersion } from "@hot-updater/plugin-core";
 import { Platform } from "react-native";
 
-import { HotUpdaterError } from "./error";
+import { HotUpdaterError, StaleReleaseCatalogError } from "./error";
+import type { HotUpdaterHttpClient, HotUpdaterHttpSession } from "./httpClient";
 import {
+  acceptReleaseCatalog,
+  commitReleaseSelection,
+  getActiveUpdateState,
   getAppVersion,
   getBundleId,
   getChannel,
   getCohort,
   getDefaultChannel,
   getFingerprintHash,
-  getMinBundleId,
+  getInstallId,
+  getMinimumReleaseId,
+  getCrashHistory,
+  getPersistedUserIdentity,
+  isReleaseSelectionCurrent,
   isChannelSwitched,
-  resetChannel,
   updateBundle,
 } from "./native";
+import {
+  hasExpectedReleaseCatalogScope,
+  type ExpectedReleaseCatalogScope,
+} from "./releaseCatalogCache";
 import { hotUpdaterStore } from "./store";
-import type { HotUpdaterResolver } from "./types";
-
-const NIL_UUID = "00000000-0000-0000-0000-000000000000";
 
 export interface CheckForUpdateOptions {
   /**
@@ -43,7 +60,15 @@ export interface CheckForUpdateOptions {
   requestTimeout?: number;
 }
 
-export type CheckForUpdateResult = AppUpdateAvailableInfo & {
+export type CheckForUpdateResult = ArtifactInfo & {
+  readonly id: string;
+  readonly message: string | null;
+  readonly rolloutCohortCount: number;
+  readonly shouldForceUpdate: boolean;
+  readonly status: "ROLLBACK" | "UPDATE";
+  readonly targetCohorts: string[];
+  readonly releaseId?: string | null;
+  readonly transitionKind?: ReleaseTransitionKind;
   /**
    * Updates the bundle.
    * This method is equivalent to `HotUpdater.updateBundle()` but with all required arguments pre-filled.
@@ -51,19 +76,334 @@ export type CheckForUpdateResult = AppUpdateAvailableInfo & {
   updateBundle: () => Promise<boolean>;
 };
 
-// Internal type that includes resolver for use within index.ts
+export type ReleaseTransitionKind =
+  | "INSTALL"
+  | "ADOPT_RELEASE"
+  | "USE_EMBEDDED"
+  | "USE_BUILTIN";
+
 export interface InternalCheckForUpdateOptions extends CheckForUpdateOptions {
-  resolver: HotUpdaterResolver;
+  analytics?: boolean;
+  client: HotUpdaterHttpClient;
 }
 
-const isResetToBuiltInResponse = (updateInfo: AppUpdateInfo): boolean => {
-  return (
-    updateInfo.status === "ROLLBACK" &&
-    updateInfo.id === NIL_UUID &&
-    updateInfo.fileUrl === null
-  );
+const sameReceipt = (
+  first: PersistedSelectionReceipt | null,
+  second: PersistedSelectionReceipt,
+): boolean =>
+  first !== null &&
+  first.kind === second.kind &&
+  first.releaseId === second.releaseId &&
+  first.bundleId === second.bundleId &&
+  first.catalogId === second.catalogId &&
+  first.scopeKey === second.scopeKey &&
+  first.generation === second.generation &&
+  first.catalogHash === second.catalogHash &&
+  first.channel === second.channel &&
+  first.selectionContextHash === second.selectionContextHash;
+
+const validateCatalog = (
+  catalog: ReleaseCatalog,
+  expectedScope: ExpectedReleaseCatalogScope,
+) => {
+  if (
+    catalog.schemaVersion !== 1 ||
+    !Number.isSafeInteger(catalog.generation) ||
+    catalog.generation < 1 ||
+    !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) ||
+    !hasExpectedReleaseCatalogScope(catalog, expectedScope)
+  ) {
+    throw new HotUpdaterError("Received an invalid Release catalog");
+  }
+};
+
+const resetProgress = () => {
+  hotUpdaterStore.setState({
+    artifactType: null,
+    details: null,
+    downloadedBytes: undefined,
+    isUpdateDownloaded: false,
+    progress: 0,
+    totalBytes: undefined,
+  });
+};
+
+const notifyReleaseAdoption = async (input: {
+  readonly active: PersistedSelectionReceipt | null;
+  readonly desired: PersistedSelectionReceipt;
+  readonly appVersion: string;
+  readonly cohort: string;
+  readonly fingerprintHash: string | null;
+  readonly platform: "ios" | "android";
+  readonly session: HotUpdaterHttpSession;
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  readonly updateStrategy: "appVersion" | "fingerprint";
+}): Promise<void> => {
+  const { userId, username } = getPersistedUserIdentity();
+  try {
+    await input.session.sendAnalyticsEvent({
+      appVersion: input.appVersion,
+      channel: input.desired.channel,
+      cohort: input.cohort,
+      fingerprintHash: input.fingerprintHash,
+      fromBundleId: input.desired.bundleId,
+      fromReleaseId: input.active?.releaseId ?? null,
+      installId: getInstallId(),
+      platform: input.platform,
+      requestHeaders: input.requestHeaders,
+      requestTimeout: input.requestTimeout,
+      toBundleId: input.desired.bundleId,
+      toReleaseId: input.desired.releaseId,
+      type: "RELEASE_ADOPTED",
+      updateStrategy: input.updateStrategy,
+      ...(userId === undefined ? {} : { userId }),
+      ...(username === undefined ? {} : { username }),
+    });
+  } catch (error) {
+    console.warn("[HotUpdater] Release adoption analytics failed:", error);
+  }
 };
 
+async function checkForReleaseCatalogUpdate(input: {
+  readonly options: InternalCheckForUpdateOptions;
+  readonly platform: "ios" | "android";
+  readonly currentAppVersion: string;
+  readonly currentBundleId: string;
+  readonly minimumReleaseId: string;
+  readonly defaultChannel: string;
+  readonly currentChannel: string;
+  readonly targetChannel: string;
+  readonly explicitChannel: string | undefined;
+  readonly isSwitched: boolean;
+  readonly cohort: string;
+  readonly fingerprintHash: string | null;
+}): Promise<CheckForUpdateResult | null> {
+  const { options } = input;
+  const session = await options.client.createSession();
+  const channelKey = encodeChannelKey(input.targetChannel);
+  const strategy =
+    options.updateStrategy === "appVersion" ? "APP_VERSION" : "FINGERPRINT";
+  const canonicalAppVersion = canonicalizeAppVersion(input.currentAppVersion);
+  if (strategy === "APP_VERSION" && canonicalAppVersion === null) {
+    throw new HotUpdaterError("Failed to canonicalize app version");
+  }
+  if (strategy === "FINGERPRINT" && !input.fingerprintHash) {
+    throw new HotUpdaterError("Fingerprint hash is required");
+  }
+  const expectedScope: ExpectedReleaseCatalogScope =
+    strategy === "APP_VERSION"
+      ? {
+          channelKey,
+          platform: input.platform,
+          strategy,
+        }
+      : {
+          channelKey,
+          fingerprintHash: input.fingerprintHash!,
+          platform: input.platform,
+          strategy,
+        };
+  const catalog = await session.fetchReleaseCatalog({
+    appVersion: canonicalAppVersion ?? input.currentAppVersion,
+    channel: input.targetChannel,
+    fingerprintHash: input.fingerprintHash,
+    platform: input.platform,
+    requestHeaders: options.requestHeaders,
+    requestTimeout: options.requestTimeout,
+    updateStrategy: options.updateStrategy,
+  });
+  validateCatalog(catalog, expectedScope);
+  const catalogId = catalog.catalogId;
+  const scopeKey = catalog.scopeKey;
+
+  const crashedBundleIds = getCrashHistory();
+  const active = getActiveUpdateState().activeSelection;
+  const explicitScopeSwitch =
+    input.explicitChannel !== undefined &&
+    input.explicitChannel !== input.currentChannel;
+  const activeInTargetScope =
+    active?.catalogId === catalogId && active.scopeKey === scopeKey
+      ? active
+      : null;
+  const hasAuthenticatedActive =
+    active !== null &&
+    active.catalogId !== null &&
+    active.scopeKey !== null &&
+    active.generation !== null;
+  if (
+    hasAuthenticatedActive &&
+    activeInTargetScope === null &&
+    !explicitScopeSwitch
+  ) {
+    throw new HotUpdaterError("Release transition rejected: UNSOLICITED_SCOPE");
+  }
+  const selectorCurrentBundleId =
+    activeInTargetScope !== null ||
+    (!hasAuthenticatedActive && !explicitScopeSwitch)
+      ? input.currentBundleId
+      : input.minimumReleaseId;
+  const selectionContextHash = createReleaseSelectionContextHash({
+    activeBundleId: selectorCurrentBundleId,
+    activeReleaseId: activeInTargetScope?.releaseId ?? null,
+    cohort: input.cohort,
+    crashedBundleIds,
+    minimumReleaseId: input.minimumReleaseId,
+    strategy,
+    strategyValue:
+      strategy === "APP_VERSION"
+        ? canonicalAppVersion!
+        : input.fingerprintHash!,
+  });
+  if (
+    !acceptReleaseCatalog({
+      catalogId,
+      catalogHash: catalog.catalogHash,
+      channel: input.targetChannel,
+      generation: catalog.generation,
+      selectionContextHash,
+      scopeKey,
+    })
+  ) {
+    throw new HotUpdaterError(
+      "Rejected a stale or inconsistent Release catalog",
+    );
+  }
+  const desired = selectDesiredRelease(catalog, {
+    activeReleaseId: activeInTargetScope?.releaseId ?? null,
+    builtInBundleId: input.minimumReleaseId,
+    cohort: input.cohort,
+    crashedBundleIds,
+    currentBundleId: selectorCurrentBundleId,
+    minimumReleaseId: input.minimumReleaseId,
+  });
+  if (desired === null) return null;
+
+  if (
+    desired.kind === "BUILTIN" &&
+    input.currentBundleId === input.minimumReleaseId &&
+    (active === null || active.kind === "BUILTIN")
+  ) {
+    return null;
+  }
+
+  const receipt: PersistedSelectionReceipt = {
+    catalogId,
+    bundleId: desired.bundleId,
+    catalogHash: catalog.catalogHash,
+    channel: input.targetChannel,
+    generation: catalog.generation,
+    kind: desired.kind,
+    releaseId: desired.releaseId,
+    scopeKey,
+    selectionContextHash,
+  };
+  if (sameReceipt(active, receipt)) return null;
+
+  const authorization = authorizeReleaseTransition({
+    active,
+    desired: receipt,
+    explicitScopeSwitch,
+  });
+  if (!authorization.authorized) {
+    if (authorization.reason === "EMPTY_TARGET_SCOPE") return null;
+    throw new HotUpdaterError(
+      `Release transition rejected: ${authorization.reason}`,
+    );
+  }
+
+  const release = desired.release;
+  const transitionKind: ReleaseTransitionKind =
+    desired.kind === "BUILTIN"
+      ? "USE_BUILTIN"
+      : desired.kind === "EMBEDDED"
+        ? "USE_EMBEDDED"
+        : active?.bundleId === desired.bundleId
+          ? "ADOPT_RELEASE"
+          : "INSTALL";
+  const guard = {
+    catalogId,
+    catalogHash: catalog.catalogHash,
+    channel: input.targetChannel,
+    generation: catalog.generation,
+    scopeKey,
+    selectionContextHash,
+  };
+  const updateBundleForSelection = async (): Promise<boolean> => {
+    resetProgress();
+    if (!isReleaseSelectionCurrent(guard)) {
+      throw new StaleReleaseCatalogError();
+    }
+
+    if (transitionKind !== "INSTALL") {
+      const committed = await commitReleaseSelection({
+        guard,
+        selection: receipt,
+      });
+      if (
+        committed &&
+        transitionKind === "ADOPT_RELEASE" &&
+        options.analytics
+      ) {
+        await notifyReleaseAdoption({
+          active,
+          appVersion: input.currentAppVersion,
+          cohort: input.cohort,
+          desired: receipt,
+          fingerprintHash: input.fingerprintHash,
+          platform: input.platform,
+          requestHeaders: options.requestHeaders,
+          requestTimeout: options.requestTimeout,
+          session,
+          updateStrategy: options.updateStrategy,
+        });
+      }
+      return committed;
+    }
+
+    const artifact = await session.resolveArtifact({
+      currentBundleId: input.currentBundleId,
+      requestHeaders: options.requestHeaders,
+      requestTimeout: options.requestTimeout,
+      targetBundleId: desired.bundleId,
+    });
+    if (!isReleaseSelectionCurrent(guard)) {
+      throw new StaleReleaseCatalogError();
+    }
+    return updateBundle({
+      bundleId: desired.bundleId,
+      changedAssets: artifact.changedAssets ?? null,
+      channel: input.targetChannel,
+      fileHash: artifact.fileHash,
+      fileUrl: artifact.fileUrl,
+      manifestFileHash: artifact.manifestFileHash ?? null,
+      manifestUrl: artifact.manifestUrl ?? null,
+      selection: receipt,
+      shouldSkipCurrentBundleIdCheck: true,
+      status: desired.status,
+    });
+  };
+
+  return {
+    fileHash: null,
+    fileUrl: null,
+    id: desired.bundleId,
+    message: release?.message ?? null,
+    releaseId: desired.releaseId,
+    rolloutCohortCount: release?.rolloutCohortCount ?? 1000,
+    shouldForceUpdate:
+      transitionKind === "ADOPT_RELEASE"
+        ? false
+        : desired.status === "ROLLBACK"
+          ? true
+          : (release?.shouldForceUpdate ?? false),
+    status: desired.status,
+    targetCohorts: release?.targetCohorts ? [...release.targetCohorts] : [],
+    transitionKind,
+    updateBundle: updateBundleForSelection,
+  };
+}
+
 export async function checkForUpdate(
   options: InternalCheckForUpdateOptions,
 ): Promise<CheckForUpdateResult | null> {
@@ -81,20 +421,12 @@ export async function checkForUpdate(
   const currentAppVersion = getAppVersion();
   const platform = Platform.OS as "ios" | "android";
   const currentBundleId = getBundleId();
-  const minBundleId = getMinBundleId();
+  const minimumReleaseId = getMinimumReleaseId();
   const defaultChannel = getDefaultChannel();
   const isSwitched = isChannelSwitched();
   const currentChannel = isSwitched ? getChannel() : defaultChannel;
   const explicitChannel = options.channel || undefined;
   const targetChannel = explicitChannel || currentChannel;
-  const isFirstRuntimeChannelSwitchAttempt =
-    !isSwitched &&
-    explicitChannel !== undefined &&
-    explicitChannel !== defaultChannel;
-  const requestBundleId = isFirstRuntimeChannelSwitchAttempt
-    ? minBundleId
-    : currentBundleId;
-
   const cohort = getCohort();
 
   if (!currentAppVersion) {
@@ -112,84 +444,23 @@ export async function checkForUpdate(
 
   const fingerprintHash = getFingerprintHash();
 
-  if (!options.resolver?.checkUpdate) {
-    options.onError?.(
-      new HotUpdaterError("Resolver is required but not configured"),
-    );
-    return null;
-  }
-
-  let updateInfo: AppUpdateInfo | null = null;
-
   try {
-    updateInfo = await options.resolver.checkUpdate({
-      platform,
-      appVersion: currentAppVersion,
-      bundleId: requestBundleId,
-      minBundleId,
+    return await checkForReleaseCatalogUpdate({
       cohort,
-      channel: targetChannel,
-      updateStrategy: options.updateStrategy,
+      currentAppVersion,
+      currentBundleId,
+      currentChannel,
+      defaultChannel,
+      explicitChannel,
       fingerprintHash,
-      requestHeaders: options.requestHeaders,
-      requestTimeout: options.requestTimeout,
+      isSwitched,
+      minimumReleaseId,
+      options,
+      platform,
+      targetChannel,
     });
   } catch (error) {
     options.onError?.(error as Error);
     return null;
   }
-
-  if (!updateInfo) {
-    return null;
-  }
-
-  if (updateInfo.status === "UP_TO_DATE") {
-    return null;
-  }
-
-  if (
-    explicitChannel &&
-    explicitChannel !== defaultChannel &&
-    !isSwitched &&
-    updateInfo.status === "ROLLBACK"
-  ) {
-    return null;
-  }
-
-  return {
-    ...updateInfo,
-    updateBundle: async () => {
-      if (
-        explicitChannel &&
-        isSwitched &&
-        isResetToBuiltInResponse(updateInfo)
-      ) {
-        return resetChannel();
-      }
-
-      const runtimeChannel =
-        updateInfo.fileUrl !== null ? targetChannel : undefined;
-
-      hotUpdaterStore.setState({
-        artifactType: null,
-        details: null,
-        downloadedBytes: undefined,
-        isUpdateDownloaded: false,
-        progress: 0,
-        totalBytes: undefined,
-      });
-
-      return updateBundle({
-        bundleId: updateInfo.id,
-        channel: runtimeChannel,
-        changedAssets: updateInfo.changedAssets ?? null,
-        fileUrl: updateInfo.fileUrl,
-        fileHash: updateInfo.fileHash,
-        manifestFileHash: updateInfo.manifestFileHash ?? null,
-        manifestUrl: updateInfo.manifestUrl ?? null,
-        status: updateInfo.status,
-        shouldSkipCurrentBundleIdCheck: isFirstRuntimeChannelSwitchAttempt,
-      });
-    },
-  };
 }

package/src/error.ts

@@ -157,3 +157,10 @@ export class HotUpdaterError extends Error {
     this.name = "HotUpdaterError";
   }
 }
+
+export class StaleReleaseCatalogError extends HotUpdaterError {
+  constructor() {
+    super("Release catalog selection became stale before it was committed");
+    this.name = "StaleReleaseCatalogError";
+  }
+}

package/src/{fetchUpdateInfo.ts → fetchJSON.ts}

@@ -1,6 +1,4 @@
-import type { AppUpdateInfo } from "@hot-updater/core";
-
-export const fetchUpdateInfo = async ({
+export const fetchJSON = async <T>({
   url,
   requestHeaders,
   requestTimeout = 5000,
@@ -8,27 +6,22 @@ export const fetchUpdateInfo = async ({
   url: string;
   requestHeaders?: Record<string, string>;
   requestTimeout?: number;
-}): Promise<AppUpdateInfo | null> => {
+}): Promise<T> => {
   const controller = new AbortController();
-  const timeoutId = setTimeout(() => {
-    controller.abort();
-  }, requestTimeout);
+  const timeoutId = setTimeout(() => controller.abort(), requestTimeout);
 
   try {
-    const headers = {
-      "Content-Type": "application/json",
-      ...requestHeaders,
-    };
-
     const response = await fetch(url, {
+      headers: {
+        Accept: "application/json",
+        ...requestHeaders,
+      },
       signal: controller.signal,
-      headers,
     });
-
     if (response.status !== 200) {
       throw new Error(response.statusText);
     }
-    return response.json();
+    return (await response.json()) as T;
   } catch (error: unknown) {
     if (error instanceof Error && error.name === "AbortError") {
       throw new Error("Request timed out");

package/src/httpClient.spec.ts

@@ -0,0 +1,132 @@
+import type { ArtifactInfo, ReleaseCatalog } from "@hot-updater/core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createHttpClient } from "./httpClient";
+
+const mocks = vi.hoisted(() => {
+  Reflect.set(globalThis, "HotUpdater", {
+    SDK_VERSION: "test-sdk-version",
+  });
+  return {
+    fetchCatalog: vi.fn(),
+    fetchJSON: vi.fn(),
+  };
+});
+
+vi.mock("./releaseCatalogCache", () => ({
+  fetchReleaseCatalogWithCache: mocks.fetchCatalog,
+}));
+
+vi.mock("./fetchJSON", () => ({
+  fetchJSON: mocks.fetchJSON,
+}));
+
+const artifact: ArtifactInfo = {
+  fileHash: "bundle-hash",
+  fileUrl: "/storage/bundle.zip",
+};
+
+const catalog: ReleaseCatalog = {
+  catalogId: "server-owned-project",
+  catalogHash: `sha256:${"a".repeat(64)}`,
+  fallbackPolicy: "BUILTIN_IF_ACTIVE_INELIGIBLE",
+  generation: 1,
+  releases: [],
+  schemaVersion: 1,
+  scopeKey: "v1:app-version:server-owned-project:ios:cHJvZHVjdGlvbg",
+};
+
+describe("private HotUpdater HTTP client", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.fetchCatalog.mockResolvedValue(catalog);
+    mocks.fetchJSON.mockResolvedValue(artifact);
+  });
+
+  it("fetches a catalog without putting its internal identity in the route", async () => {
+    const session = await createHttpClient(
+      "https://updates.example.com/hot-updater/",
+    ).createSession();
+
+    await expect(
+      session.fetchReleaseCatalog({
+        appVersion: "1.2.0",
+        channel: "production",
+        fingerprintHash: null,
+        platform: "ios",
+        updateStrategy: "appVersion",
+      }),
+    ).resolves.toBe(catalog);
+
+    expect(mocks.fetchCatalog).toHaveBeenCalledWith({
+      baseURL: "https://updates.example.com/hot-updater",
+      expectedScope: {
+        channelKey: "cHJvZHVjdGlvbg",
+        platform: "ios",
+        strategy: "APP_VERSION",
+      },
+      requestHeaders: undefined,
+      requestTimeout: undefined,
+      url: "https://updates.example.com/hot-updater/release-catalogs/app-version/ios/cHJvZHVjdGlvbg/1.2.0",
+    });
+  });
+
+  it("resolves a functional baseURL once per session and captures it for a deferred artifact", async () => {
+    const resolveBaseURL = vi
+      .fn()
+      .mockResolvedValueOnce("https://first.example.com/hot-updater")
+      .mockResolvedValueOnce("https://second.example.com/hot-updater");
+    const client = createHttpClient(resolveBaseURL);
+    const firstSession = await client.createSession();
+
+    await firstSession.fetchReleaseCatalog({
+      appVersion: "1.2.0",
+      channel: "production",
+      fingerprintHash: null,
+      platform: "ios",
+      updateStrategy: "appVersion",
+    });
+    await expect(
+      firstSession.resolveArtifact({
+        currentBundleId: "current",
+        targetBundleId: "target",
+      }),
+    ).resolves.toEqual({
+      ...artifact,
+      fileUrl: "https://first.example.com/hot-updater/storage/bundle.zip",
+    });
+
+    expect(resolveBaseURL).toHaveBeenCalledOnce();
+    expect(mocks.fetchJSON).toHaveBeenCalledWith({
+      requestHeaders: undefined,
+      requestTimeout: undefined,
+      url: "https://first.example.com/hot-updater/artifacts/target/from/current",
+    });
+
+    await client.createSession();
+    expect(resolveBaseURL).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects non-storage relative artifact URLs", async () => {
+    mocks.fetchJSON.mockResolvedValue({
+      ...artifact,
+      fileUrl: "/private/bundle.zip",
+    });
+    const session = await createHttpClient(
+      "https://updates.example.com",
+    ).createSession();
+
+    await expect(
+      session.resolveArtifact({
+        currentBundleId: "current",
+        targetBundleId: "target",
+      }),
+    ).rejects.toThrow("client-relative storage paths");
+  });
+
+  it("requires a functional baseURL to resolve to a non-empty string", async () => {
+    await expect(createHttpClient(() => "").createSession()).rejects.toThrow(
+      "baseURL function must return a non-empty string",
+    );
+  });
+});