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

package/src/releaseCatalogCache.ts

@@ -0,0 +1,341 @@
+import {
+  MAX_TARGET_COHORTS_PER_RELEASE,
+  MAX_COMPILED_CATALOG_BYTES,
+  MAX_DISTINCT_TARGET_COHORTS_PER_SCOPE,
+  NUMERIC_COHORT_SIZE,
+  isUUIDv7,
+  parseReleaseCatalogScopeKey,
+  type ReleaseCatalog,
+} from "@hot-updater/core";
+
+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;
+
+const readNativeReleaseCatalogCache = async (partition: string) =>
+  (await import("./catalogCacheNative")).readNativeReleaseCatalogCache(
+    partition,
+  );
+
+const writeNativeReleaseCatalogCache = async (
+  partition: string,
+  payload: string,
+) =>
+  (await import("./catalogCacheNative")).writeNativeReleaseCatalogCache(
+    partition,
+    payload,
+  );
+
+const removeNativeReleaseCatalogCache = async (partition: string) =>
+  (await import("./catalogCacheNative")).removeNativeReleaseCatalogCache(
+    partition,
+  );
+
+type CachedCatalog = {
+  readonly catalog: ReleaseCatalog;
+  readonly etag: string;
+};
+
+let lastParsedCache:
+  | (CachedCatalog & {
+      readonly partition: string;
+      readonly serialized: string;
+    })
+  | 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;
+  readonly requestHeaders?: Record<string, string>;
+  readonly requestTimeout?: number;
+  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 &&
+  !value.includes("\r") &&
+  !value.includes("\n") &&
+  getUtf8ByteLength(value) <= MAX_ETAG_BYTES;
+
+const serializeCache = (etag: string, body: string): string =>
+  `${CACHE_FORMAT_VERSION}\n${etag}\n${body}`;
+
+const parseCache = (
+  value: string,
+  expectedScope: ExpectedReleaseCatalogScope,
+  partition: string,
+): CachedCatalog | null => {
+  if (
+    lastParsedCache !== null &&
+    lastParsedCache.serialized === value &&
+    lastParsedCache.partition === partition
+  ) {
+    return lastParsedCache;
+  }
+  const versionEnd = value.indexOf("\n");
+  const etagEnd = value.indexOf("\n", versionEnd + 1);
+  if (
+    versionEnd === -1 ||
+    etagEnd === -1 ||
+    value.slice(0, versionEnd) !== CACHE_FORMAT_VERSION
+  ) {
+    return null;
+  }
+
+  const etag = value.slice(versionEnd + 1, etagEnd);
+  const body = value.slice(etagEnd + 1);
+  if (!isValidETag(etag)) return null;
+  const catalog = parseValidatedCatalog(body, expectedScope);
+  if (catalog === null) return null;
+  const parsed = { catalog, etag, partition, serialized: value };
+  lastParsedCache = parsed;
+  return parsed;
+};
+
+const normalizedHeaders = (
+  requestHeaders: Record<string, string> | undefined,
+): readonly (readonly [string, string])[] => {
+  const headers = new Headers(requestHeaders);
+  return [...headers.entries()]
+    .map(([name, value]) => [name.toLowerCase(), value] as const)
+    .sort(([firstName], [secondName]) => firstName.localeCompare(secondName));
+};
+
+export const createReleaseCatalogCachePartition = (
+  input: Pick<FetchReleaseCatalogInput, "baseURL" | "requestHeaders" | "url">,
+): string =>
+  JSON.stringify({
+    baseURL: input.baseURL,
+    headers: normalizedHeaders(input.requestHeaders),
+    url: input.url,
+    version: 2,
+  });
+
+const fetchCatalogResponse = async (
+  input: FetchReleaseCatalogInput,
+  etag?: string,
+): Promise<Response> => {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(
+    () => controller.abort(),
+    input.requestTimeout ?? 5000,
+  );
+
+  try {
+    const headers = new Headers(input.requestHeaders);
+    headers.set("Accept", "application/json");
+    if (etag === undefined) {
+      headers.delete("If-None-Match");
+    } else {
+      headers.set("If-None-Match", etag);
+    }
+    return await fetch(input.url, {
+      headers,
+      signal: controller.signal,
+    });
+  } catch (error: unknown) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error("Request timed out");
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+};
+
+const readValidatedCache = async (
+  partition: string,
+  expectedScope: ExpectedReleaseCatalogScope,
+): Promise<CachedCatalog | null> => {
+  const value = await readNativeReleaseCatalogCache(partition);
+  if (value === null) return null;
+
+  const cached = parseCache(value, expectedScope, partition);
+  if (cached === null) {
+    await removeNativeReleaseCatalogCache(partition);
+  }
+  return cached;
+};
+
+const consumeSuccessfulResponse = async (
+  response: Response,
+  input: FetchReleaseCatalogInput,
+  partition: string,
+): Promise<ReleaseCatalog> => {
+  if (response.status !== 200) {
+    throw new Error(response.statusText);
+  }
+
+  const body = await response.text();
+  const catalog = parseValidatedCatalog(body, input.expectedScope);
+  if (catalog === null) {
+    await removeNativeReleaseCatalogCache(partition);
+    throw new Error("Received an invalid Release catalog");
+  }
+
+  const etag = response.headers.get("etag");
+  if (isValidETag(etag)) {
+    const serialized = serializeCache(etag, body);
+    if (getUtf8ByteLength(serialized) > MAX_RELEASE_CATALOG_CACHE_ENTRY_BYTES) {
+      await removeNativeReleaseCatalogCache(partition);
+      return catalog;
+    }
+    if (await writeNativeReleaseCatalogCache(partition, serialized)) {
+      lastParsedCache = {
+        catalog,
+        etag,
+        partition,
+        serialized,
+      };
+    }
+  } else {
+    await removeNativeReleaseCatalogCache(partition);
+  }
+  return catalog;
+};
+
+export const fetchReleaseCatalogWithCache = async (
+  input: FetchReleaseCatalogInput,
+): Promise<ReleaseCatalog> => {
+  const partition = createReleaseCatalogCachePartition(input);
+  const cached = await readValidatedCache(partition, input.expectedScope);
+  const response = await fetchCatalogResponse(input, cached?.etag);
+
+  if (response.status === 304) {
+    if (cached !== null) return cached.catalog;
+
+    const repairResponse = await fetchCatalogResponse(input);
+    return consumeSuccessfulResponse(repairResponse, input, partition);
+  }
+
+  return consumeSuccessfulResponse(response, input, partition);
+};

package/src/releaseCatalogCacheNativeContract.spec.ts

@@ -0,0 +1,80 @@
+import {
+  createReleaseCatalogScopeKey,
+  encodeChannelKey,
+  type ReleaseCatalog,
+} from "@hot-updater/core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const nativeModule = vi.hoisted(
+  () => ({}) as Record<string, ReturnType<typeof vi.fn>>,
+);
+
+vi.mock("./specs/NativeHotUpdater", () => ({ default: nativeModule }));
+
+import { fetchReleaseCatalogWithCache } from "./releaseCatalogCache";
+
+const catalogId = "project-a";
+const scopeKey = createReleaseCatalogScopeKey({
+  channelKey: encodeChannelKey("production"),
+  platform: "ios",
+  strategy: "APP_VERSION",
+});
+const input = {
+  baseURL: "https://updates.example.com",
+  expectedScope: {
+    channelKey: encodeChannelKey("production"),
+    platform: "ios",
+    strategy: "APP_VERSION",
+  } as const,
+  requestHeaders: { "x-api-key": "key" },
+  url: "https://updates.example.com/catalog",
+};
+const catalog: ReleaseCatalog = {
+  catalogId,
+  catalogHash: `sha256:${"a".repeat(64)}`,
+  fallbackPolicy: "BUILTIN_IF_ACTIVE_INELIGIBLE",
+  generation: 1,
+  releases: [],
+  schemaVersion: 1,
+  scopeKey,
+};
+
+describe("Release Catalog native cache contract", () => {
+  beforeEach(() => {
+    for (const key of Object.keys(nativeModule)) delete nativeModule[key];
+  });
+
+  it("fails before fetching when the v1 native cache API is missing", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(fetchReleaseCatalogWithCache(input)).rejects.toThrow(
+      "Native module is missing 'getReleaseCatalogCache()'. Rebuild the native app before using Release catalogs.",
+    );
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("uses the network when native cache I/O fails", async () => {
+    nativeModule.getReleaseCatalogCache = vi
+      .fn()
+      .mockRejectedValue(new Error("read"));
+    nativeModule.setReleaseCatalogCache = vi
+      .fn()
+      .mockRejectedValue(new Error("write"));
+    nativeModule.removeReleaseCatalogCache = vi
+      .fn()
+      .mockRejectedValue(new Error("remove"));
+    const fetchMock = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(catalog), {
+        headers: { ETag: '"v1"' },
+        status: 200,
+      }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(fetchReleaseCatalogWithCache(input)).resolves.toEqual(catalog);
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(nativeModule.getReleaseCatalogCache).toHaveBeenCalledOnce();
+    expect(nativeModule.setReleaseCatalogCache).toHaveBeenCalledOnce();
+  });
+});

package/src/sdkVersion.ts

@@ -1 +1 @@
-export const HOT_UPDATER_SDK_VERSION = "0.36.6";
+export const HOT_UPDATER_SDK_VERSION = "1.0.0-rc.0";

package/src/specs/NativeHotUpdater.ts

@@ -44,6 +44,8 @@ export interface UpdateBundleParams {
    * the currently active bundle.
    */
   changedAssets?: UnsafeObject | null;
+  /** Full Release Catalog selection receipt committed with the staged Bundle. */
+  selection?: UnsafeObject | null;
 }
 
 export interface Spec extends TurboModule {
@@ -88,17 +90,41 @@ export interface Spec extends TurboModule {
    */
   updateBundle(params: UpdateBundleParams): Promise<boolean>;
 
+  /** Accepts and durably advances the catalog high-water for a scope. */
+  acceptReleaseCatalog(params: UnsafeObject): boolean;
+
+  /** Reads active/stable selection receipts and catalog high-water state. */
+  getActiveUpdateState(): UnsafeObject;
+
+  /** Reads a checksum-verified Release Catalog cache entry. */
+  getReleaseCatalogCache(partition: string): Promise<string | null>;
+
+  /** Atomically stores a bounded Release Catalog cache entry. */
+  setReleaseCatalogCache(partition: string, payload: string): Promise<boolean>;
+
+  /** Removes an incompatible Release Catalog cache entry. */
+  removeReleaseCatalogCache(partition: string): Promise<boolean>;
+
+  /** Rechecks generation/context immediately before a catalog side effect. */
+  isReleaseSelectionCurrent(params: UnsafeObject): boolean;
+
+  /** Atomically commits a metadata-only, EMBEDDED, or BUILTIN selection. */
+  commitReleaseSelection(params: UnsafeObject): Promise<boolean>;
+
   /**
    * Reads the launch report for the current process.
    * This is a read-only API; native launch state has already been finalized.
    *
-   * @returns Object with status and optional crashedBundleId
-   * - `status: "RECOVERED"` - App recovered from crash, rollback occurred (ROLLBACK event)
-   * - `status: "STABLE"` - No changes, already stable
-   * - `crashedBundleId` - Present only when status is "RECOVERED"
+   * @returns Object describing whether launch state changed and, for qualifying
+   * transitions, the relevant bundle ids plus persisted transition metadata.
    */
   notifyAppReady(): {
-    status: "RECOVERED" | "STABLE";
+    status: "PENDING" | "UNCHANGED" | "UPDATE_APPLIED" | "RECOVERED";
+    fromReleaseId?: string;
+    fromBundleId?: string;
+    toReleaseId?: string;
+    toBundleId?: string;
+    updateStrategy?: "fingerprint" | "appVersion";
     crashedBundleId?: string;
   };
 
@@ -165,6 +191,26 @@ export interface Spec extends TurboModule {
    */
   getCohort: () => string;
 
+  /**
+   * Gets the persisted install id for this app installation.
+   */
+  getInstallId: () => string;
+
+  /**
+   * Gets the persisted nullable user id associated with this installation.
+   */
+  getUserId: () => string | null;
+
+  /**
+   * Gets the persisted nullable username associated with this installation.
+   */
+  getUsername: () => string | null;
+
+  /**
+   * Persists nullable user identity fields associated with this installation.
+   */
+  setUser: (userId: string | null, username: string | null) => void;
+
   // EventEmitter
   addListener(eventName: string): void;
   removeListeners(count: number): void;

package/src/types.ts

@@ -1,145 +1,5 @@
-import type { AppUpdateInfo } from "@hot-updater/core";
-
-import type { NotifyAppReadyResult } from "./native";
-
 export type HotUpdaterBaseURL = string | (() => string | Promise<string>);
 
-/**
- * Parameters passed to resolver.checkUpdate method
- */
-export interface ResolverCheckUpdateParams {
-  /**
-   * The platform the app is running on
-   */
-  platform: "ios" | "android";
-
-  /**
-   * The current app version
-   */
-  appVersion: string;
-
-  /**
-   * The current bundle ID
-   */
-  bundleId: string;
-
-  /**
-   * Minimum bundle ID from build time
-   */
-  minBundleId: string;
-
-  /**
-   * The channel name (e.g., "production", "staging")
-   */
-  channel: string;
-
-  /**
-   * Cohort identifier used for server-side rollout decisions.
-   */
-  cohort: string;
-
-  /**
-   * Update strategy being used
-   */
-  updateStrategy: "fingerprint" | "appVersion";
-
-  /**
-   * The fingerprint hash (only present when using fingerprint strategy)
-   */
-  fingerprintHash: string | null;
-
-  /**
-   * Request headers from global config (for optional use)
-   */
-  requestHeaders?: Record<string, string>;
-
-  /**
-   * Request timeout from global config (for optional use)
-   */
-  requestTimeout?: number;
-}
-
-/**
- * Parameters passed to resolver.notifyAppReady method
- */
-export interface ResolverNotifyAppReadyParams {
-  /**
-   * The bundle state from native notifyAppReady
-   * - "RECOVERED": App recovered from crash, rollback occurred
-   * - "STABLE": No changes, bundle is stable
-   */
-  status: "RECOVERED" | "STABLE";
-
-  /**
-   * Present only when status is "RECOVERED"
-   */
-  crashedBundleId?: string;
-
-  /**
-   * Request headers from global config (for optional use)
-   */
-  requestHeaders?: Record<string, string>;
-
-  /**
-   * Request timeout from global config (for optional use)
-   */
-  requestTimeout?: number;
-}
-
-/**
- * Resolver interface for custom network operations
- */
-export interface HotUpdaterResolver {
-  /**
-   * Custom implementation for checking updates.
-   * When provided, this completely replaces the default fetchUpdateInfo flow.
-   *
-   * @param params - All parameters needed to check for updates
-   * @returns Update information or null if up to date
-   *
-   * @example
-   * ```typescript
-   * checkUpdate: async (params) => {
-   *   const response = await fetch(`https://api.custom.com/check`, {
-   *     method: 'POST',
-   *     body: JSON.stringify(params),
-   *     headers: params.requestHeaders,
-   *   });
-   *
-   *   if (!response.ok) return null;
-   *   return response.json();
-   * }
-   * ```
-   */
-  checkUpdate?: (
-    params: ResolverCheckUpdateParams,
-  ) => Promise<AppUpdateInfo | null>;
-
-  /**
-   * Custom implementation for notifying app ready.
-   * When provided, this completely replaces the default notifyAppReady network flow.
-   * Note: Native rollback/promotion semantics are already finalized before this callback runs.
-   *
-   * @param params - All parameters about the current app state
-   * @returns Notification result
-   *
-   * @example
-   * ```typescript
-   * notifyAppReady: async (params) => {
-   *   await fetch(`https://api.custom.com/notify`, {
-   *     method: 'POST',
-   *     body: JSON.stringify(params),
-   *   });
-   *
-   *   return { status: "STABLE" };
-   * }
-   * ```
-   */
-  notifyAppReady?: (
-    params: ResolverNotifyAppReadyParams,
-  ) => Promise<NotifyAppReadyResult | undefined>;
-}
-
 /**
  * Information about a signature verification failure.
  * This is a security-critical event that indicates the bundle