@hot-updater/react-native 1.0.0-rc.2 → 1.0.0-rc.21

package/src/native.ts

@@ -1,12 +1,12 @@
 import {
-  type ChangedAsset,
+  type ArtifactAsset,
   type CatalogHighWater,
   INVALID_COHORT_ERROR_MESSAGE,
   isValidCohort,
   normalizeCohortValue,
   type UpdateStatus,
   type PersistedSelectionReceipt,
-} from "@hot-updater/core";
+} from "@hot-updater/protocol";
 import { NativeEventEmitter, Platform } from "react-native";
 
 import { HotUpdaterErrorCode, isHotUpdaterError } from "./error";
@@ -74,7 +74,10 @@ class HotUpdaterSessionState {
   private readonly defaultChannel: string;
   private currentChannel: string;
   private cachedCohort: string | undefined;
-  private readonly inflightUpdates = new Map<string, Promise<boolean>>();
+  private readonly inflightUpdates = new Map<
+    string,
+    Promise<BundleDelivery | null>
+  >();
   private lastInstalledBundleId: string | null = null;
   private readonly activeBundleSnapshotCache = new Map<
     ActiveBundleSnapshotCacheKey,
@@ -103,11 +106,16 @@ class HotUpdaterSessionState {
     return this.lastInstalledBundleId === bundleId;
   }
 
-  getInflightUpdate(bundleId: string): Promise<boolean> | undefined {
+  getInflightUpdate(
+    bundleId: string,
+  ): Promise<BundleDelivery | null> | undefined {
     return this.inflightUpdates.get(bundleId);
   }
 
-  trackInflightUpdate(bundleId: string, promise: Promise<boolean>) {
+  trackInflightUpdate(
+    bundleId: string,
+    promise: Promise<BundleDelivery | null>,
+  ) {
     this.inflightUpdates.set(bundleId, promise);
   }
 
@@ -234,7 +242,7 @@ const getReloadProcess = (): (() => Promise<void>) | null => {
     : null;
 };
 
-export type HotUpdaterProgressArtifactType = "archive" | "diff";
+export type HotUpdaterProgressArtifactType = "diff";
 
 export type HotUpdaterDiffFileStatus =
   | "pending"
@@ -286,18 +294,11 @@ export interface HotUpdaterDiffProgressDetails {
   files: HotUpdaterDiffFileSnapshot[];
 }
 
-export type HotUpdaterProgressEvent =
-  | {
-      progress: number;
-      artifactType: "archive";
-      downloadedBytes?: number;
-      totalBytes?: number;
-    }
-  | {
-      progress: number;
-      artifactType: "diff";
-      details: HotUpdaterDiffProgressDetails;
-    };
+export type HotUpdaterProgressEvent = {
+  progress: number;
+  artifactType: "diff";
+  details: HotUpdaterDiffProgressDetails;
+};
 
 export type HotUpdaterEvent = {
   onProgress: HotUpdaterProgressEvent;
@@ -424,18 +425,42 @@ export const commitReleaseSelection = async (input: {
   return ok;
 };
 
+/** How native delivered a staged bundle. */
+export type BundleDelivery = {
+  /**
+   * "patch" when a bsdiff patch produced a file, "manifest" when only the
+   * changed files were downloaded, "archive" for the full archive.
+   */
+  readonly delivery: "patch" | "manifest" | "archive";
+  /** A patch was tried, but the file or the archive was downloaded instead. */
+  readonly patchFallback: boolean;
+};
+
+const readBundleDelivery = (value: unknown): BundleDelivery | null => {
+  if (typeof value !== "object" || value === null) return null;
+  const { delivery, patchFallback } = value as Record<string, unknown>;
+  if (
+    delivery !== "patch" &&
+    delivery !== "manifest" &&
+    delivery !== "archive"
+  ) {
+    return null;
+  }
+  return { delivery, patchFallback: patchFallback === true };
+};
+
 /**
- * Downloads files and applies them to the app.
+ * Stages a bundle for the next launch. Resolves with how native delivered
+ * it, or with null when this runtime had already staged it and nothing was
+ * downloaded; rejects when the download or install fails.
  *
- * @param {UpdateParams} params - Parameters object required for bundle update
- * @returns {Promise<boolean>} Resolves with true if download was successful
  * @throws {Error} Rejects with error.code from HotUpdaterErrorCode enum and error.message
  */
-export async function updateBundle(params: UpdateParams): Promise<boolean> {
+export async function stageBundle(
+  params: UpdateParams,
+): Promise<BundleDelivery | null> {
   const updateBundleId = params.bundleId;
   const status = params.status;
-  const targetFileUrl = params.fileUrl;
-
   const currentBundleId = status === "UPDATE" ? getFreshBundleId() : undefined;
 
   // If native is still on the same bundle we installed in this session,
@@ -446,7 +471,7 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
     sessionState.hasInstalledBundle(updateBundleId) &&
     currentBundleId === updateBundleId
   ) {
-    return true;
+    return null;
   }
 
   const shouldSkipCurrentBundleIdCheck =
@@ -467,30 +492,25 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
   const existing = sessionState.getInflightUpdate(updateBundleId);
   if (existing) return existing;
 
-  const targetFileHash = params.fileHash;
   const targetChannel = params.channel;
   const targetManifestUrl = params.manifestUrl;
   const targetManifestFileHash = params.manifestFileHash;
-  const targetChangedAssets = params.changedAssets;
+  const targetAssets = params.assets;
 
   const promise = (async () => {
     try {
       const selection = params.selection;
-      const ok = await HotUpdaterNative.updateBundle({
+      const staged = await HotUpdaterNative.updateBundle({
         bundleId: updateBundleId,
         channel: targetChannel,
-        changedAssets:
-          (targetChangedAssets as Record<string, ChangedAsset> | null) ?? null,
-        fileUrl: targetFileUrl,
-        fileHash: targetFileHash ?? null,
-        manifestFileHash: targetManifestFileHash ?? null,
-        manifestUrl: targetManifestUrl ?? null,
+        assets: targetAssets as Record<string, ArtifactAsset>,
+        manifestFileHash: targetManifestFileHash,
+        manifestUrl: targetManifestUrl,
+        ...(params.archiveUrl ? { archiveUrl: params.archiveUrl } : {}),
         ...(selection === undefined ? {} : { selection }),
       });
-      if (ok) {
-        sessionState.markBundleInstalled(updateBundleId, targetChannel);
-      }
-      return ok;
+      sessionState.markBundleInstalled(updateBundleId, targetChannel);
+      return readBundleDelivery(staged);
     } finally {
       sessionState.clearInflightUpdate(updateBundleId);
     }
@@ -500,6 +520,18 @@ export async function updateBundle(params: UpdateParams): Promise<boolean> {
   return promise;
 }
 
+/**
+ * Downloads files and applies them to the app.
+ *
+ * @param {UpdateParams} params - Parameters object required for bundle update
+ * @returns {Promise<boolean>} Resolves with true if download was successful
+ * @throws {Error} Rejects with error.code from HotUpdaterErrorCode enum and error.message
+ */
+export async function updateBundle(params: UpdateParams): Promise<boolean> {
+  await stageBundle(params);
+  return true;
+}
+
 /**
  * Fetches the current app version.
  */
@@ -599,8 +631,9 @@ export const getMinBundleId = (): string => {
   return constants.MIN_BUNDLE_ID;
 };
 
-export const getReleaseId = async (): Promise<string | null> =>
-  getActiveUpdateState().activeSelection?.releaseId ?? null;
+/** Returns the selected update ID shown in the console, including staged updates. */
+export const getUpdateId = (): string =>
+  getActiveUpdateState().activeSelection?.releaseId ?? getBundleId();
 
 /**
  * Fetches the current bundle version id.
@@ -704,64 +737,31 @@ export const getInstallId = (): string => {
   return nativeModule.getInstallId();
 };
 
-export type PersistedUserIdentity = {
-  userId?: string;
-  username?: string;
-};
-
-export const getPersistedUserIdentity = (): PersistedUserIdentity => {
-  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
-    getUserId?: () => string | null;
-    getUsername?: () => string | null;
-  };
-
-  if (
-    typeof nativeModule.getUserId !== "function" ||
-    typeof nativeModule.getUsername !== "function"
-  ) {
+const requireStorageNativeMethod = <T extends (...args: any[]) => any>(
+  name: "getStorageItem" | "setStorageItem",
+): T => {
+  const method = (HotUpdaterNative as unknown as Record<string, unknown>)[name];
+  if (typeof method !== "function") {
     throw new Error(
-      "[HotUpdater] Native module is missing 'getUserId()' or 'getUsername()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.",
+      `[HotUpdater] Native module is missing '${name}()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.`,
     );
   }
-
-  const userId = nativeModule.getUserId();
-  const username = nativeModule.getUsername();
-
-  return {
-    ...(userId != null ? { userId } : {}),
-    ...(username != null ? { username } : {}),
-  };
+  return method.bind(HotUpdaterNative) as T;
 };
 
-export type SetUserParams = {
-  userId?: string | number | null;
-  username?: string | null;
+/** Reads a value from the SDK's native key-value store. */
+export const getStorageItem = (key: string): string | null => {
+  const value =
+    requireStorageNativeMethod<(key: string) => unknown>("getStorageItem")(key);
+  return typeof value === "string" ? value : null;
 };
 
-export function setUser(params: SetUserParams): void;
-export function setUser(params: null): void;
-export function setUser(params: SetUserParams | null): void {
-  const nativeModule = HotUpdaterNative as typeof HotUpdaterNative & {
-    setUser?: (userId: string | null, username: string | null) => void;
-  };
-
-  if (typeof nativeModule.setUser !== "function") {
-    throw new Error(
-      "[HotUpdater] Native module is missing 'setUser()'. This JS bundle requires a newer native @hot-updater/react-native SDK. Rebuild and release a new app version before delivering this OTA update.",
-    );
-  }
-
-  if (params === null) {
-    nativeModule.setUser(null, null);
-    return;
-  }
-
-  const normalizedUserId =
-    params.userId === null || params.userId === undefined
-      ? null
-      : String(params.userId);
-  nativeModule.setUser(normalizedUserId, params.username ?? null);
-}
+/** Writes a value to the SDK's native key-value store; null removes it. */
+export const setStorageItem = (key: string, value: string | null): void => {
+  requireStorageNativeMethod<(key: string, value: string | null) => void>(
+    "setStorageItem",
+  )(key, value);
+};
 
 /**
  * Result returned by notifyAppReady()
@@ -783,18 +783,20 @@ export type NotifyAppReadyResult =
       toReleaseId?: string;
     };
 
-export type NotifyAppReadyInsightsEvent = {
+/** An update applied or recovered at this launch, as native persisted it. */
+export type LaunchTransition = {
   type: "UPDATE_APPLIED" | "RECOVERED";
   fromBundleId: string;
   toBundleId: string;
-  fromReleaseId?: string | null;
-  toReleaseId?: string | null;
+  fromReleaseId: string | null;
+  toReleaseId: string | null;
   updateStrategy: PersistedUpdateStrategy;
 };
 
 type RawNotifyAppReadyResult = {
   status?: string;
   crashedBundleId?: string;
+  previousProcessExit?: string;
   fromReleaseId?: string;
   fromBundleId?: string;
   toReleaseId?: string;
@@ -891,9 +893,9 @@ const getNotifyAppReadyTransition = (
   return null;
 };
 
-const getNotifyAppReadyInsightsEvent = (
+const getLaunchTransition = (
   result: RawNotifyAppReadyResult,
-): NotifyAppReadyInsightsEvent | null => {
+): LaunchTransition | null => {
   const transition = getNotifyAppReadyTransition(result);
 
   if (!transition || !isPersistedUpdateStrategy(result.updateStrategy)) {
@@ -904,12 +906,8 @@ const getNotifyAppReadyInsightsEvent = (
     type: transition.status,
     fromBundleId: transition.fromBundleId,
     toBundleId: transition.toBundleId,
-    ...(transition.fromReleaseId === null
-      ? {}
-      : { fromReleaseId: transition.fromReleaseId }),
-    ...(transition.toReleaseId === null
-      ? {}
-      : { toReleaseId: transition.toReleaseId }),
+    fromReleaseId: transition.fromReleaseId,
+    toReleaseId: transition.toReleaseId,
     updateStrategy: result.updateStrategy,
   };
 };
@@ -938,14 +936,21 @@ const normalizeNotifyAppReadyResult = (
 
 export const readNotifyAppReady = (): {
   result: NotifyAppReadyResult;
-  insightsEvent: NotifyAppReadyInsightsEvent | null;
+  transition: LaunchTransition | null;
+  /** Android 11+: why the previous main process exited, when native knows. */
+  previousProcessExit: string | null;
   pending: boolean;
 } => {
   const rawResult = readRawNotifyAppReadyResult();
+  const { previousProcessExit } = rawResult;
 
   return {
     result: normalizeNotifyAppReadyResult(rawResult),
-    insightsEvent: getNotifyAppReadyInsightsEvent(rawResult),
+    transition: getLaunchTransition(rawResult),
+    previousProcessExit:
+      typeof previousProcessExit === "string" && previousProcessExit !== ""
+        ? previousProcessExit
+        : null,
     pending: rawResult.status === "PENDING",
   };
 };

package/src/pluginHost.ts

@@ -0,0 +1,45 @@
+import { createPluginHost } from "@hot-updater/protocol";
+import { Platform } from "react-native";
+
+import {
+  getAppVersion,
+  getBundleId,
+  getChannel,
+  getCohort,
+  getFingerprintHash,
+  getInstallId,
+  getStorageItem,
+  setStorageItem,
+} from "./native";
+import { HOT_UPDATER_SDK_VERSION } from "./sdkVersion";
+
+export type { PluginHostConfig } from "@hot-updater/protocol";
+
+/** The app's plugin host: plugins read the native module and fetch the configured server. */
+export const {
+  configurePlugins,
+  hasPluginHook,
+  buildPluginEvent,
+  dispatchPluginHook,
+  emitPluginHook,
+} = createPluginHost({
+  fetch: (url, init) => fetch(url, init),
+  get platform() {
+    return Platform.OS === "android" ? "android" : "ios";
+  },
+  get isDebugBuild() {
+    return typeof __DEV__ !== "undefined" && __DEV__;
+  },
+  get sdkVersion() {
+    return HOT_UPDATER_SDK_VERSION;
+  },
+  getInstallId: () => getInstallId(),
+  getAppVersion: () => getAppVersion(),
+  getBundleId: () => getBundleId(),
+  getChannel: () => getChannel(),
+  getCohort: () => getCohort(),
+  getFingerprintHash: () => getFingerprintHash(),
+  getStorageItem: (key) => getStorageItem(key),
+  setStorageItem: (key, value) => setStorageItem(key, value),
+  now: () => Date.now(),
+});

package/src/releaseCatalogCache.ts

@@ -1,17 +1,15 @@
 import {
-  MAX_TARGET_COHORTS_PER_RELEASE,
-  MAX_COMPILED_CATALOG_BYTES,
-  MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE,
-  NUMERIC_COHORT_SIZE,
-  isUUIDv7,
-  parseReleaseCatalogScopeKey,
+  type ExpectedReleaseCatalogScope,
+  getUtf8ByteLength,
+  MAX_RELEASE_CATALOG_WIRE_BYTES,
+  parseReleaseCatalog,
   type ReleaseCatalog,
-} from "@hot-updater/core";
+} from "@hot-updater/protocol";
+
+import { InvalidUpdateResponseError, UpdateHttpError } from "./updateError";
 
 const CACHE_FORMAT_VERSION = "1";
 const MAX_ETAG_BYTES = 1024;
-export const MAX_RELEASE_CATALOG_WIRE_BYTES =
-  MAX_COMPILED_CATALOG_BYTES * 2 + 4 * 1024;
 export const MAX_RELEASE_CATALOG_CACHE_ENTRY_BYTES =
   MAX_RELEASE_CATALOG_WIRE_BYTES + MAX_ETAG_BYTES + 3;
 
@@ -46,20 +44,6 @@ let lastParsedCache:
     })
   | null = null;
 
-export type ExpectedReleaseCatalogScope = {
-  readonly channelKey: string;
-  readonly platform: "ios" | "android";
-} & (
-  | {
-      readonly strategy: "APP_VERSION";
-      readonly fingerprintHash?: never;
-    }
-  | {
-      readonly strategy: "FINGERPRINT";
-      readonly fingerprintHash: string;
-    }
-);
-
 type FetchReleaseCatalogInput = {
   readonly baseURL: string;
   readonly expectedScope: ExpectedReleaseCatalogScope;
@@ -68,117 +52,6 @@ type FetchReleaseCatalogInput = {
   readonly url: string;
 };
 
-const getUtf8ByteLength = (value: string): number => {
-  let bytes = 0;
-  for (let index = 0; index < value.length; index += 1) {
-    const code = value.charCodeAt(index);
-    if (code <= 0x7f) {
-      bytes += 1;
-    } else if (code <= 0x7ff) {
-      bytes += 2;
-    } else if (
-      code >= 0xd800 &&
-      code <= 0xdbff &&
-      index + 1 < value.length &&
-      value.charCodeAt(index + 1) >= 0xdc00 &&
-      value.charCodeAt(index + 1) <= 0xdfff
-    ) {
-      bytes += 4;
-      index += 1;
-    } else {
-      bytes += 3;
-    }
-  }
-  return bytes;
-};
-
-const isStringArray = (value: unknown): value is readonly string[] =>
-  Array.isArray(value) && value.every((entry) => typeof entry === "string");
-
-const isValidReleaseDescriptor = (value: unknown): boolean => {
-  if (value === null || typeof value !== "object") return false;
-  const descriptor = value as Record<string, unknown>;
-
-  return (
-    isUUIDv7(descriptor.releaseId) &&
-    (descriptor.kind === "BUNDLE" || descriptor.kind === "EMBEDDED") &&
-    ((descriptor.kind === "BUNDLE" &&
-      typeof descriptor.bundleId === "string") ||
-      (descriptor.kind === "EMBEDDED" && descriptor.bundleId === null)) &&
-    Number.isSafeInteger(descriptor.rolloutCohortCount) &&
-    (descriptor.rolloutCohortCount as number) >= 0 &&
-    (descriptor.rolloutCohortCount as number) <= NUMERIC_COHORT_SIZE &&
-    isStringArray(descriptor.targetCohorts) &&
-    descriptor.targetCohorts.length <= MAX_TARGET_COHORTS_PER_RELEASE &&
-    typeof descriptor.shouldForceUpdate === "boolean" &&
-    (descriptor.message === null || typeof descriptor.message === "string")
-  );
-};
-
-export const hasExpectedReleaseCatalogScope = (
-  catalog: ReleaseCatalog,
-  expected: ExpectedReleaseCatalogScope,
-): boolean => {
-  try {
-    const parsed = parseReleaseCatalogScopeKey(catalog.scopeKey);
-    return (
-      parsed.channelKey === expected.channelKey &&
-      parsed.platform === expected.platform &&
-      parsed.strategy === expected.strategy &&
-      (parsed.strategy === "APP_VERSION" ||
-        (expected.strategy === "FINGERPRINT" &&
-          parsed.fingerprintHash === expected.fingerprintHash))
-    );
-  } catch {
-    return false;
-  }
-};
-
-const parseValidatedCatalog = (
-  value: string,
-  expectedScope: ExpectedReleaseCatalogScope,
-): ReleaseCatalog | null => {
-  if (getUtf8ByteLength(value) > MAX_RELEASE_CATALOG_WIRE_BYTES) return null;
-
-  try {
-    const catalog = JSON.parse(value) as Partial<ReleaseCatalog>;
-    if (
-      catalog.schemaVersion !== 1 ||
-      typeof catalog.catalogId !== "string" ||
-      catalog.catalogId.length === 0 ||
-      typeof catalog.scopeKey !== "string" ||
-      !Number.isSafeInteger(catalog.generation) ||
-      (catalog.generation ?? 0) < 1 ||
-      typeof catalog.catalogHash !== "string" ||
-      !/^sha256:[0-9a-f]{64}$/.test(catalog.catalogHash) ||
-      catalog.fallbackPolicy !== "BUILTIN_IF_ACTIVE_INELIGIBLE" ||
-      !Array.isArray(catalog.releases) ||
-      !catalog.releases.every(isValidReleaseDescriptor) ||
-      (catalog.rollbackReleases !== undefined &&
-        (!Array.isArray(catalog.rollbackReleases) ||
-          !catalog.rollbackReleases.every(isValidReleaseDescriptor)))
-    ) {
-      return null;
-    }
-    if (
-      !hasExpectedReleaseCatalogScope(catalog as ReleaseCatalog, expectedScope)
-    ) {
-      return null;
-    }
-    const distinctTargetCohorts = new Set(
-      [...catalog.releases, ...(catalog.rollbackReleases ?? [])].flatMap(
-        (release) => release.targetCohorts,
-      ),
-    );
-    if (distinctTargetCohorts.size > MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE) {
-      return null;
-    }
-    return catalog as ReleaseCatalog;
-  } catch {
-    return null;
-  }
-};
-
 const isValidETag = (value: string | null): value is string =>
   value !== null &&
   value.length > 0 &&
@@ -214,7 +87,7 @@ const parseCache = (
   const etag = value.slice(versionEnd + 1, etagEnd);
   const body = value.slice(etagEnd + 1);
   if (!isValidETag(etag)) return null;
-  const catalog = parseValidatedCatalog(body, expectedScope);
+  const catalog = parseReleaseCatalog(body, expectedScope);
   if (catalog === null) return null;
   const parsed = { catalog, etag, partition, serialized: value };
   lastParsedCache = parsed;
@@ -290,16 +163,25 @@ const consumeSuccessfulResponse = async (
   response: Response,
   input: FetchReleaseCatalogInput,
   partition: string,
-): Promise<ReleaseCatalog> => {
+): Promise<ReleaseCatalog | null> => {
+  // The server marks the 404 of a scope that has no catalog yet: no update,
+  // not a failure. Any other 404 is a wrong baseURL or route.
+  if (
+    response.status === 404 &&
+    response.headers.get("x-hot-updater-catalog")?.trim().toLowerCase() ===
+      "none"
+  ) {
+    return null;
+  }
   if (response.status !== 200) {
-    throw new Error(response.statusText);
+    throw new UpdateHttpError(response.status, response.statusText);
   }
 
   const body = await response.text();
-  const catalog = parseValidatedCatalog(body, input.expectedScope);
+  const catalog = parseReleaseCatalog(body, input.expectedScope);
   if (catalog === null) {
     await removeNativeReleaseCatalogCache(partition);
-    throw new Error("Received an invalid Release catalog");
+    throw new InvalidUpdateResponseError("Received an invalid Release catalog");
   }
 
   const etag = response.headers.get("etag");
@@ -323,9 +205,13 @@ const consumeSuccessfulResponse = async (
   return catalog;
 };
 
+/**
+ * Fetches a scope's catalog, or null when the server answers that the scope
+ * has none (a 404 with `x-hot-updater-catalog: none`).
+ */
 export const fetchReleaseCatalogWithCache = async (
   input: FetchReleaseCatalogInput,
-): Promise<ReleaseCatalog> => {
+): Promise<ReleaseCatalog | null> => {
   const partition = createReleaseCatalogCachePartition(input);
   const cached = await readValidatedCache(partition, input.expectedScope);
   const response = await fetchCatalogResponse(input, cached?.etag);

package/src/sdkVersion.ts

@@ -1 +1 @@
-export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.2";
+export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.21";