react-native-update 10.60.0 → 10.61.0

package/src/clientReporter.ts

@@ -0,0 +1,398 @@
+import {
+  buildTime,
+  cInfo,
+  currentVersion,
+  currentVersionInfo,
+  packageVersion,
+} from './core';
+import { toUpdateError, type UpdateError, type UpdateErrorCode } from './error';
+import {
+  type ErrorReportContext,
+  type ErrorReportingOptions,
+  installGlobalErrorHandler,
+  type SerializedException,
+  serializeException,
+} from './errorReporting';
+import {
+  resolveServerEventHash,
+  resolveServerEventType,
+  truncateDetail,
+} from './telemetry';
+import type { ClientOptions, EventType, UpdateCheckState } from './type';
+import { fetchWithTimeout, log, noop } from './utils';
+
+/** One report() event: the logger payload and the source of server telemetry. */
+export interface ReportEvent {
+  type: EventType;
+  message?: string;
+  code?: UpdateErrorCode;
+  data?: Record<string, string | number>;
+}
+
+/**
+ * Receives every error the client reports, alongside the report event type.
+ * The UpdateProvider subscribes to surface errors as lastError/Alert; user
+ * code can subscribe too. Listeners run before any throwError rethrow.
+ */
+export type UpdateErrorListener = (
+  error: UpdateError,
+  eventType: EventType
+) => void;
+
+/** What reporting needs from the client. */
+export interface ReporterHost {
+  readonly options: ClientOptions;
+  getEffectivePackageVersion(): string;
+  /**
+   * The client's report: events raised here go through it, so a caller that
+   * replaces client.report sees them too.
+   */
+  report(event: ReportEvent): Promise<void>;
+  /** The endpoint telemetry posts to: the last one that served a check. */
+  telemetryEndpoint(): string | undefined;
+}
+
+/**
+ * Everything that leaves the client as a signal: the user logger, server
+ * telemetry, JS exception reports and the onError listeners. Never throws
+ * into the update flow.
+ */
+export class Reporter {
+  constructor(private readonly host: ReporterHost) {}
+
+  private reportedInvalidUpdates = new Set<string>();
+  private reportedExceptions = new WeakSet<object>();
+  private globalErrorCleanup?: () => void;
+  private errorListeners = new Set<UpdateErrorListener>();
+  private emittedErrors = new WeakSet<Error>();
+
+  /** Resolved once a logger is configured (see report). */
+  loggerPromise = (() => {
+    let resolve: (value?: unknown) => void = () => {};
+    const promise = new Promise((res) => {
+      resolve = res;
+    });
+    return {
+      promise,
+      resolve,
+    };
+  })();
+
+  syncAutomaticErrorReporting = (): void => {
+    const { options } = this.host;
+    if (options.disableTelemetry || options.disableErrorReporting) {
+      this.globalErrorCleanup?.();
+      return;
+    }
+    this.enableErrorReporting();
+  };
+
+  reportInvalidUpdateOnce = (
+    reason: 'missingHash' | 'noArtifact',
+    hash = ''
+  ) => {
+    const key = `${this.host.options.appKey}:${reason}:${hash}`;
+    if (this.reportedInvalidUpdates.has(key)) {
+      return;
+    }
+    this.reportedInvalidUpdates.add(key);
+    this.host.report({
+      type: 'errorUpdate',
+      message:
+        reason === 'missingHash'
+          ? 'update response is missing a version hash'
+          : 'update response contains no downloadable artifact',
+      ...(hash ? { data: { newVersion: hash } } : {}),
+    });
+  };
+
+  /**
+   * Best-effort JS exception reporting for the currently running OTA release.
+   * It is intentionally synchronous to call and never throws; the transport
+   * runs in the background and preserves the app's existing error flow.
+   */
+  captureException = (
+    error: unknown,
+    context: ErrorReportContext = {}
+  ): void => {
+    try {
+      const { options } = this.host;
+      if (
+        __DEV__ ||
+        options.disableTelemetry ||
+        options.disableErrorReporting ||
+        !currentVersion
+      ) {
+        return;
+      }
+      if (
+        error !== null &&
+        (typeof error === 'object' || typeof error === 'function')
+      ) {
+        const object = error as object;
+        if (this.reportedExceptions.has(object)) {
+          return;
+        }
+        this.reportedExceptions.add(object);
+      }
+      this.postReport({
+        type: 'js_exception',
+        hash: currentVersion,
+        error: serializeException(error, context),
+      });
+    } catch (e: any) {
+      log('exception telemetry error:', e?.message || e);
+    }
+  };
+
+  /**
+   * Ensure uncaught JS exception capture is installed and return a runtime
+   * cleanup function. Capture is installed automatically by default; this
+   * method remains an idempotent compatibility hook. The wrapper always
+   * chains the handler that was installed before it and only restores that
+   * handler when no later integration has replaced ours.
+   */
+  enableErrorReporting = (
+    options: ErrorReportingOptions = {}
+  ): (() => void) => {
+    if (
+      options.captureGlobal === false ||
+      this.host.options.disableTelemetry ||
+      this.host.options.disableErrorReporting
+    ) {
+      return () => {};
+    }
+    if (this.globalErrorCleanup) {
+      return this.globalErrorCleanup;
+    }
+    const uninstall = installGlobalErrorHandler((error, isFatal) => {
+      this.captureException(error, { fatal: isFatal === true });
+    });
+    let active = true;
+    const cleanup = () => {
+      if (!active) {
+        return;
+      }
+      active = false;
+      uninstall();
+      if (this.globalErrorCleanup === cleanup) {
+        this.globalErrorCleanup = undefined;
+      }
+    };
+    this.globalErrorCleanup = cleanup;
+    return cleanup;
+  };
+
+  report = async ({ type, message = '', code, data = {} }: ReportEvent) => {
+    log(`${type} ${code ? `[${code}] ` : ''}${message}`);
+    // Fire-and-forget server telemetry; must not wait for the logger below.
+    this.reportToServer({ type, message, code, data });
+    if (this.host.options.logger === noop) {
+      // Wait briefly for a logger to arrive via setOptions (e.g. the rollback
+      // report fires in the constructor before the user configures one), but
+      // give up after a bound instead of retaining the closure forever when
+      // no logger is ever provided.
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([
+        this.loggerPromise.promise,
+        new Promise<void>((resolve) => {
+          timer = setTimeout(() => resolve(), 10 * 1000);
+        }),
+      ]);
+      clearTimeout(timer);
+    }
+    const { logger = noop, appKey } = this.host.options;
+    const overridePackageVersion = this.host.options.overridePackageVersion;
+    try {
+      logger({
+        type,
+        data: {
+          appKey,
+          currentVersion,
+          cInfo,
+          packageVersion,
+          overridePackageVersion,
+          buildTime,
+          message,
+          code,
+          ...currentVersionInfo,
+          ...data,
+        },
+      });
+    } catch (e: any) {
+      // A user-provided logger must never break the update flow, and report()
+      // calls are fire-and-forget so a throw here would be an unhandled
+      // rejection.
+      log('logger error:', e?.message || e);
+    }
+  };
+
+  /**
+   * Best-effort lifecycle event reporting to the update server (aggregate
+   * counts + sampled failure details power the version health view and the
+   * rollback safety net server-side). Single POST to the last known working
+   * endpoint, no retry, no fallback race; any failure is swallowed — telemetry
+   * must never affect the update flow. Opt out with disableTelemetry.
+   */
+  private reportToServer = ({
+    type,
+    message,
+    code,
+    data = {},
+  }: ReportEvent) => {
+    try {
+      if (__DEV__ || this.host.options.disableTelemetry) {
+        return;
+      }
+      const serverType = resolveServerEventType(type, code);
+      if (!serverType) {
+        return;
+      }
+      const hash = resolveServerEventHash({ serverType, data, currentVersion });
+      if (!hash) {
+        return;
+      }
+      // A download rescued by a later strategy reports its patch-health
+      // signal through downloadFallback, which only counts patch-apply
+      // failures; downloadSuccess's data.error (any earlier failure, network
+      // errors included) stays local.
+      this.postReport({
+        type: serverType,
+        hash,
+        detail: truncateDetail(message),
+      });
+    } catch (e: any) {
+      log('telemetry error:', e?.message || e);
+    }
+  };
+
+  /**
+   * The single telemetry POST ({endpoint}/report/{appKey}) to the last known
+   * working endpoint; no retry, failures only logged.
+   */
+  private postReport = ({
+    type,
+    hash,
+    ...payload
+  }: {
+    type: string;
+    hash: string;
+    detail?: string;
+    error?: SerializedException;
+  }) => {
+    const { appKey } = this.host.options;
+    const endpoint = this.host.telemetryEndpoint();
+    if (!appKey || !endpoint) {
+      return;
+    }
+    fetchWithTimeout(`${endpoint}/report/${appKey}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        type,
+        hash,
+        packageVersion: this.host.getEffectivePackageVersion(),
+        cInfo,
+        ...payload,
+      }),
+    }).catch((e: any) => {
+      log('telemetry report failed:', e?.message || e);
+    });
+  };
+
+  throwIfEnabled = (e: Error) => {
+    if (this.host.options.throwError) {
+      throw e;
+    }
+  };
+
+  /**
+   * Subscribe to every error the client reports (regardless of throwError).
+   * Returns an unsubscribe function.
+   */
+  onError = (listener: UpdateErrorListener) => {
+    this.errorListeners.add(listener);
+    return () => {
+      this.errorListeners.delete(listener);
+    };
+  };
+
+  /**
+   * Whether this exact error object already went through emitError (and was
+   * therefore delivered to onError subscribers). Lets UI layers decide if a
+   * caught error still needs surfacing — checking `e.code` is not enough,
+   * since axios/system errors carry their own code without ever entering the
+   * pipeline.
+   */
+  wasEmitted = (e: unknown): boolean =>
+    e instanceof Error && this.emittedErrors.has(e);
+
+  /**
+   * Single exit point for errors: reports to the logger (with the stable
+   * code) and notifies onError listeners. Whether to also throw stays with
+   * the caller (throwIfEnabled or an unconditional rethrow).
+   */
+  emitError = (
+    error: UpdateError,
+    type: EventType,
+    {
+      message = error.message,
+      data,
+    }: { message?: string; data?: Record<string, string | number> } = {}
+  ) => {
+    this.emittedErrors.add(error);
+    this.host.report({
+      type,
+      message,
+      code: error.code,
+      // Structured context from the error (e.g. HTTP status) reaches the
+      // logger; explicit data wins on key conflicts.
+      data: error.extra ? { ...error.extra, ...data } : data,
+    });
+    for (const listener of this.errorListeners) {
+      try {
+        listener(error, type);
+      } catch (e: any) {
+        log('onError listener error:', e?.message || e);
+      }
+    }
+  };
+
+  /**
+   * toUpdateError + emitError: how a caught failure leaves the client.
+   * Returns the error for the caller to throw or pass to throwIfEnabled.
+   * `fallbackMessage` is reported when the error has no message of its own.
+   */
+  fail = (
+    e: unknown,
+    code: UpdateErrorCode,
+    type: EventType,
+    {
+      message,
+      fallbackMessage,
+      data,
+    }: {
+      message?: string;
+      fallbackMessage?: string;
+      data?: Record<string, string | number>;
+    } = {}
+  ): UpdateError => {
+    const err = toUpdateError(e, code);
+    this.emitError(err, type, {
+      message: message ?? (err.message || fallbackMessage),
+      data,
+    });
+    return err;
+  };
+
+  notifyAfterCheckUpdate = (state: UpdateCheckState) => {
+    const { afterCheckUpdate } = this.host.options;
+    if (!afterCheckUpdate) {
+      return;
+    }
+    // 这里仅做状态通知，不阻塞原有检查流程
+    Promise.resolve(afterCheckUpdate(state)).catch((error: any) => {
+      log('afterCheckUpdate failed:', error?.message || error);
+    });
+  };
+}

package/src/clientState.ts

@@ -0,0 +1,51 @@
+import type { ProgressData } from './type';
+
+export interface SharedState {
+  downloadingTasks: Record<string, Promise<string | undefined>>;
+  // Progress callbacks per hash: concurrent downloadUpdate callers of the
+  // same hash each register theirs here instead of the second one being
+  // silently dropped by the in-flight dedup.
+  progressCallbacks: Record<string, Set<(data: ProgressData) => void>>;
+  downloadedHash?: string;
+  toHash?: string;
+  apkStatus: 'downloading' | 'downloaded' | null;
+  marked: boolean;
+  applyingUpdate: boolean;
+}
+
+/**
+ * Process-wide state of the update flow. The SDK is a process-level
+ * singleton (one client, see Pushy's constructor); client.ts creates this
+ * once, when it is evaluated, and hands it to each part of the client.
+ */
+export interface ProcessState {
+  shared: SharedState;
+  // The native cold-start check writes its response cache at most once per
+  // launch (and skips it once JS has checked), so once this process has seen
+  // it absent or expired, later reads are near-certain misses: skip the
+  // bridge call from then on. The rare miss costs one network check. A fresh
+  // entry that only mismatches the request or config does not set this: a
+  // later check with the original options (e.g. after `extra` reverts) can
+  // still reuse it.
+  nativeCheckCacheExhausted: boolean;
+  // In-flight native markSuccess shared by concurrent callers, so the native
+  // call and its telemetry happen once. Cleared once settled.
+  markingPromise?: Promise<void>;
+  // A reset/new switch invalidates ownership of older async completions and
+  // watchdogs before the process-wide applyingUpdate flag can be reused.
+  applyingUpdateGeneration: number;
+  reloadWatchdogTimer?: ReturnType<typeof setTimeout>;
+}
+
+export const createProcessState = (): ProcessState => ({
+  shared: {
+    downloadingTasks: {},
+    progressCallbacks: {},
+    downloadedHash: undefined,
+    apkStatus: null,
+    marked: false,
+    applyingUpdate: false,
+  },
+  nativeCheckCacheExhausted: false,
+  applyingUpdateGeneration: 0,
+});

package/src/core.ts

@@ -126,8 +126,10 @@ export const currentBundleSha256: string =
     ? PushyConstants.currentBundleSha256
     : '';
 
-export const isFirstTime: boolean = PushyConstants.isFirstTime;
-export const rolledBackVersion: string = PushyConstants.rolledBackVersion;
+// The platforms report an absent value differently (iOS nil, Android
+// false/null, Harmony false/''): normalize at the boundary.
+export const isFirstTime: boolean = !!PushyConstants.isFirstTime;
+export const rolledBackVersion: string = PushyConstants.rolledBackVersion || '';
 export const isRolledBack: boolean = !!rolledBackVersion;
 
 export const buildTime: string = PushyConstants.buildTime;

package/src/endpoint.ts

@@ -20,6 +20,7 @@ export interface ExecuteEndpointFallbackOptions<T> {
   random?: () => number;
   now?: () => number;
   hedgeDelayMs?: number;
+  maxRequests?: number;
   onFirstFailure?: (failure: EndpointAttemptFailure) => void | Promise<void>;
 }
 
@@ -32,6 +33,17 @@ const normalizeError = (error: unknown) => {
 
 export const DEFAULT_HEDGE_DELAY_MS = 250;
 
+/**
+ * Endpoint requests one check may issue in total, as the native round's
+ * flowcore::kMaxQueryRequests (cpp/update_flow_core/native_round.h). The
+ * remote list comes from a public mirror: without a bound, a long (or
+ * hostile) list would make every device fan out to all of its entries on
+ * each failed check.
+ */
+// <generated:query-budget> (scripts/contract.ts; bun scripts/generate-contract.ts)
+export const MAX_ENDPOINT_REQUESTS = 8;
+// </generated:query-budget>
+
 /**
  * Hedged race over the candidate endpoints: the first candidate starts
  * immediately, each following one is only started after `hedgeDelayMs` of
@@ -137,6 +149,7 @@ export async function executeEndpointFallback<T>({
   random = Math.random,
   now = Date.now,
   hedgeDelayMs = DEFAULT_HEDGE_DELAY_MS,
+  maxRequests = MAX_ENDPOINT_REQUESTS,
   onFirstFailure,
 }: ExecuteEndpointFallbackOptions<T>): Promise<EndpointAttemptSuccess<T>> {
   const excludedEndpoints = new Set<string>();
@@ -144,7 +157,8 @@ export async function executeEndpointFallback<T>({
   // is pure policy; this side only executes it.
   let candidates = orderEndpointCandidates(configuredEndpoints, random());
 
-  if (!candidates.length) {
+  // No budget means no request at all, like no endpoint.
+  if (!candidates.length || maxRequests < 1) {
     throw new UpdateError(i18n.t('error_no_endpoints'), 'NO_ENDPOINTS');
   }
 
@@ -164,14 +178,15 @@ export async function executeEndpointFallback<T>({
     excludedEndpoints.add(firstEndpoint);
     await onFirstFailure?.(firstFailure);
     let lastError = firstFailure.error;
-
-    while (true) {
+    // Every endpoint is asked at most once, so the excluded set counts the
+    // requests issued so far.
+    while (excludedEndpoints.size < maxRequests) {
       const remoteEndpoints = getRemoteEndpoints
         ? await getRemoteEndpoints().catch(() => [])
         : [];
-      candidates = dedupeEndpoints([...candidates, ...remoteEndpoints]).filter(
-        (endpoint) => !excludedEndpoints.has(endpoint)
-      );
+      candidates = dedupeEndpoints([...candidates, ...remoteEndpoints])
+        .filter((endpoint) => !excludedEndpoints.has(endpoint))
+        .slice(0, maxRequests - excludedEndpoints.size);
 
       if (!candidates.length) {
         throw lastError;
@@ -193,5 +208,6 @@ export async function executeEndpointFallback<T>({
         lastError = failure.error;
       }
     }
+    throw lastError;
   }
 }

package/src/error.ts

@@ -16,9 +16,6 @@ const UPDATE_ERROR_CODES = [
   // A 2xx check response that is not a check verdict (schema gate).
   'INVALID_RESPONSE',
   'CHECK_FAILED',
-  'DOWNLOAD_FAILED',
-  'SWITCH_VERSION_FAILED',
-  'MARK_SUCCESS_FAILED',
   'APK_INSTALL_PENDING',
   'APK_DOWNLOAD_FAILED',
   // A throw from a user-provided hook (e.g. beforeReload) — not an update
@@ -27,16 +24,21 @@ const UPDATE_ERROR_CODES = [
   // A second client/provider in the same process — a hard integration error;
   // the SDK is a process-level singleton.
   'SINGLETON_VIOLATION',
-  // Native codes (see cpp/patch_core/error_codes.h)
+  // Native codes (cpp/patch_core/error_codes.h)
+  // <generated:native-error-codes> (scripts/contract.ts; bun scripts/generate-contract.ts)
   'INVALID_OPTIONS',
+  'DOWNLOAD_FAILED',
   'PATCH_FAILED',
   'FILE_OPERATION_FAILED',
+  'SWITCH_VERSION_FAILED',
+  'MARK_SUCCESS_FAILED',
   'RESTART_FAILED',
   'RESET_FAILED',
   'INVALID_HASH_INFO',
   'UNSUPPORTED_PLATFORM',
   'APK_INSTALL_PERMISSION_REQUIRED',
   'APK_INSTALL_FAILED',
+  // </generated:native-error-codes>
 ] as const;
 
 /** A stable error code (see UPDATE_ERROR_CODES). */

package/src/locales/en.ts

@@ -25,7 +25,7 @@ export default {
     'A second UpdateProvider was mounted: make sure the app renders exactly one UpdateProvider',
   error_parse_version_info: 'Failed to parse currentVersionInfo: {{info}}',
   warn_unknown_bundle:
-    'The bundle embedded in this binary is not registered on the update platform; incremental updates are degraded to full downloads. Upload the package with pushy uploadIpa / uploadApk / uploadApp.',
+    'The bundle embedded in this binary is not registered on the update platform; incremental updates are degraded to full downloads. Upload the package with {{cli}} uploadIpa / uploadApk / uploadApp.',
   error_update_check_failed: 'Update check failed',
   error_cannot_connect_server:
     'Can not connect to update server. Please check your network.',

package/src/locales/zh.ts

@@ -23,7 +23,7 @@ export default {
     '检测到同时挂载多个 UpdateProvider：请确保应用中只有一个 UpdateProvider',
   error_parse_version_info: '解析 currentVersionInfo 失败: {{info}}',
   warn_unknown_bundle:
-    '当前二进制内嵌 bundle 未在更新平台注册，增量更新已降级为全量。请使用 pushy uploadIpa / uploadApk / uploadApp 上传对应安装包。',
+    '当前二进制内嵌 bundle 未在更新平台注册，增量更新已降级为全量。请使用 {{cli}} uploadIpa / uploadApk / uploadApp 上传对应安装包。',
   error_update_check_failed: '更新检查失败',
   error_cannot_connect_server: '无法连接到更新服务器。请检查网络连接。',
   error_cannot_connect_backup:

package/src/provider.tsx

@@ -11,7 +11,6 @@ import { Alert, AppState, Linking, Platform } from 'react-native';
 import { type Cresc, type Pushy, sharedState } from './client';
 import { ProgressContext, UpdateContext } from './context';
 import {
-  cInfo,
   currentVersion,
   currentVersionInfo,
   getCurrentVersionInfo,
@@ -19,18 +18,28 @@ import {
   rolledBackVersion,
 } from './core';
 import type { CheckResult, ProgressData, UpdateTestPayload } from './type';
-import { decideDownload, resolveCheckResult } from './updateFlowCore';
+import { decideDownload } from './updateFlowCore';
 import { assertWeb, isWeb, log, noop, parseQueryParams } from './utils';
 
-// A context action applied to the hash of the given (default: the last
-// checked) update info; a no-op without one.
+// A switch action applied to the hash of the given update info; a no-op
+// without one. Called without info it targets the downloaded version — the
+// only one client.switchVersion(Later) accepts — and only falls back to the
+// last checked info before anything was downloaded. Defaulting to the last
+// checked info alone made a check that found a newer release after the
+// download (updateInfo moved on) turn "switch now" into a silent no-op.
 const forUpdateHash =
   <T,>(
     updateInfoRef: { current?: CheckResult },
+    getDownloadedHash: () => string | undefined,
     apply: (hash: string) => Promise<T>
   ) =>
-  async (info: CheckResult | undefined = updateInfoRef.current) =>
-    info?.hash ? apply(info.hash) : undefined;
+  async (info?: CheckResult) => {
+    const hash =
+      info !== undefined
+        ? info.hash
+        : getDownloadedHash() || updateInfoRef.current?.hash;
+    return hash ? apply(hash) : undefined;
+  };
 
 export const UpdateProvider = ({
   client,
@@ -111,12 +120,22 @@ export const UpdateProvider = ({
   );
 
   const switchVersion = useMemo(
-    () => forUpdateHash(updateInfoRef, client.switchVersion),
+    () =>
+      forUpdateHash(
+        updateInfoRef,
+        client.getDownloadedHash,
+        client.switchVersion
+      ),
     [client]
   );
 
   const switchVersionLater = useMemo(
-    () => forUpdateHash(updateInfoRef, client.switchVersionLater),
+    () =>
+      forUpdateHash(
+        updateInfoRef,
+        client.getDownloadedHash,
+        client.switchVersionLater
+      ),
     [client]
   );
 
@@ -225,27 +244,20 @@ export const UpdateProvider = ({
       // No throttle here: the client already dedupes checks via its 5s
       // response cache, and a second throttle layer silently returned
       // undefined, indistinguishable from a failed check.
-      let rootInfo: CheckResult | undefined;
+      // Already resolved for this device (gray rollout, running version) by
+      // the client.
+      let info: CheckResult | undefined;
       try {
-        rootInfo = await client.checkUpdate(extra);
+        info = await client.checkUpdate(extra);
       } catch (e: any) {
         surfaceCaughtError(e, client.t('error_update_check_failed'));
         return;
       }
-      if (!rootInfo) {
+      if (!info) {
         // Check was skipped or failed with no cached result; keep the last
         // known updateInfo instead of overwriting it with an empty object.
         return;
       }
-      let info = resolveCheckResult(
-        rootInfo,
-        {
-          packageVersion: client.getEffectivePackageVersion(),
-          currentVersion,
-          uuid: cInfo.uuid,
-        },
-        log
-      );
       if (
         info.update &&
         (typeof info.hash !== 'string' || info.hash.length === 0)