react-native-update 10.59.2 → 10.61.0

package/src/clientDownload.ts

@@ -0,0 +1,448 @@
+import { DeviceEventEmitter, Platform } from 'react-native';
+import type { Pushy } from './client';
+import type { Reporter } from './clientReporter';
+import type { ProcessState } from './clientState';
+import {
+  currentVersion,
+  PushyModule,
+  pushyNativeEventEmitter,
+  rolledBackVersion,
+  setLocalHashInfo,
+} from './core';
+import { readErrorCode, UpdateError } from './error';
+import type { CheckResult, ProgressData } from './type';
+import {
+  type DownloadPlan,
+  type DownloadStrategyType,
+  decideDownload,
+  isMirrorRetryableCode,
+} from './updateFlowCore';
+import { computeProgress, log, testUrls, warn } from './utils';
+
+/**
+ * What downloading needs from the client. Its public members are called
+ * through the client, so a caller that replaces one on the instance sees
+ * every use.
+ */
+export type DownloadHost = Pick<
+  Pushy,
+  'options' | 't' | 'report' | 'reportInvalidUpdateOnce' | 'throwIfEnabled'
+>;
+
+/**
+ * Downloads: the per-device plan from decideDownload executed over the
+ * native downloaders, with mirror ranking, retries and progress fan-out;
+ * plus the Android full-package (APK) path.
+ */
+export class Downloader {
+  constructor(
+    private readonly host: DownloadHost,
+    private readonly reporter: Reporter,
+    private readonly state: ProcessState
+  ) {}
+
+  downloadUpdate = async (
+    updateInfo: CheckResult,
+    onDownloadProgress?: (data: ProgressData) => void
+  ) => {
+    const { options } = this.host;
+    if (
+      options.beforeDownloadUpdate &&
+      (await options.beforeDownloadUpdate(updateInfo)) === false
+    ) {
+      log('beforeDownloadUpdate returned false, skipping download');
+      return;
+    }
+    const decision = decideDownload(
+      updateInfo,
+      { currentVersion, rolledBackVersion },
+      __DEV__
+    );
+    if (decision.action === 'none') {
+      if (decision.reason === 'alreadyCurrent') {
+        log(`current hash ${currentVersion}, ignored`);
+      } else if (decision.reason === 'rolledBack') {
+        log(`rolledback hash ${rolledBackVersion}, ignored`);
+      } else if (decision.reason === 'noArtifact') {
+        // A server response that advertises an update but provides no usable
+        // artifact is a bad release signal, not an ordinary no-update result.
+        // Keep the user flow silent and report at most once per bad release in
+        // this process: repeated checks must not inflate download_fail health.
+        this.host.reportInvalidUpdateOnce('noArtifact', updateInfo.hash || '');
+      }
+      return;
+    }
+    const { hash } = decision;
+    if (this.state.shared.downloadedHash === hash) {
+      log(
+        `duplicated downloaded hash ${this.state.shared.downloadedHash}, ignored`
+      );
+      return this.state.shared.downloadedHash;
+    }
+    // Deduplicate concurrent downloads of the same hash regardless of whether a
+    // progress callback was passed: all callers await the single in-flight
+    // promise instead of triggering parallel native downloads.
+    const existingTask = this.state.shared.downloadingTasks[hash];
+    if (existingTask) {
+      log(`download for hash ${hash} already in progress, reusing it`);
+      // The second caller's progress callback must still fire.
+      if (onDownloadProgress) {
+        this.state.shared.progressCallbacks[hash]?.add(onDownloadProgress);
+      }
+      return existingTask;
+    }
+    const task = this.performDownload(updateInfo, decision, onDownloadProgress);
+    this.state.shared.downloadingTasks[hash] = task;
+    try {
+      return await task;
+    } finally {
+      delete this.state.shared.downloadingTasks[hash];
+    }
+  };
+
+  /**
+   * Orders candidate mirrors for one artifact: the HEAD-race winner first
+   * (its post-redirect URL), then the remaining mirrors in configured order.
+   * Empty when there is nothing to try.
+   */
+  private rankDownloadUrls = async (urls?: string[]): Promise<string[]> => {
+    if (!urls?.length) {
+      return [];
+    }
+    const winner = await testUrls(urls);
+    const ordered: string[] = [];
+    const push = (url?: string | null) => {
+      if (url && !ordered.includes(url)) {
+        ordered.push(url);
+      }
+    };
+    push(winner);
+    for (const url of urls) {
+      push(url);
+    }
+    return ordered;
+  };
+
+  private performDownload = async (
+    updateInfo: CheckResult,
+    plan: DownloadPlan,
+    onDownloadProgress?: (data: ProgressData) => void
+  ) => {
+    const { host } = this;
+    const { name, description = '', metaInfo } = updateInfo;
+    const { hash, attempts, devNoop } = plan;
+    if (devNoop) {
+      // Dev without a full package URL: nothing can be fetched, let alone
+      // installed. Say so and deliver nothing — faking a success here used to
+      // hand the caller a hash whose switchVersion the native side (rightly)
+      // rejects with SWITCH_VERSION_FAILED.
+      log(this.host.t('dev_incremental_update_disabled'));
+      return;
+    }
+    const patchStartTime = Date.now();
+    // One native listener per hash dispatching to a callback set, so
+    // concurrent callers deduped onto this task can each observe progress
+    // (they register via downloadUpdate).
+    const progressCallbacks = new Set<(data: ProgressData) => void>();
+    if (onDownloadProgress) {
+      progressCallbacks.add(onDownloadProgress);
+    }
+    this.state.shared.progressCallbacks[hash] = progressCallbacks;
+    const dispatchProgress = (data: ProgressData) => {
+      if (progressCallbacks.size === 0) {
+        return;
+      }
+      const payload = {
+        ...data,
+        progress: computeProgress(data.received, data.total),
+      };
+      progressCallbacks.forEach((callback) => {
+        // One subscriber throwing must not starve the others or abort the
+        // download: business callbacks are isolated, the error is logged.
+        try {
+          callback(payload);
+        } catch (e) {
+          warn('onDownloadProgress callback threw', e);
+        }
+      });
+    };
+    // RN >= 0.87 types native event listeners as `(...args: readonly Object[])`,
+    // which a `(data: ProgressData) => void` callback is not assignable to. Take
+    // the raw event and narrow it here so this compiles on every RN version.
+    const onNativeProgress = (event: unknown) => {
+      const progressData = event as ProgressData;
+      if (progressData.hash === hash) {
+        dispatchProgress(progressData);
+      }
+    };
+    // @ts-expect-error harmony not in existing platforms
+    const isHarmony = Platform.OS === 'harmony';
+    const progressSubscription = (
+      isHarmony ? DeviceEventEmitter : pushyNativeEventEmitter
+    ).addListener('RCTPushyDownloadProgress', onNativeProgress);
+    const maxRetries = Math.max(
+      0,
+      Math.floor(this.host.options.maxRetries ?? 3)
+    );
+    let succeeded = '';
+    let lastError: UpdateError | undefined;
+    const errorMessages: string[] = [];
+    // A strategy whose bytes arrived but could not be applied fails the same
+    // way on every retry (same artifact, same base): remember it — with its
+    // message, so the final report still names it — and skip it on later
+    // attempts instead of downloading and patching it again.
+    const exhaustedStrategies = new Map<DownloadStrategyType, string>();
+
+    // The ordered attempts come from decideDownload (the pure decision layer);
+    // this side only executes them: probe candidate URLs, run the matching
+    // native download, fall through to the next attempt on failure.
+    const runners: Record<
+      DownloadStrategyType,
+      (url: string) => Promise<void>
+    > = {
+      diff: (url) =>
+        PushyModule.downloadPatchFromPpk({
+          updateUrl: url,
+          hash,
+          originHash: currentVersion,
+        }),
+      pdiff: (url) =>
+        PushyModule.downloadPatchFromPackage({
+          updateUrl: url,
+          hash,
+        }),
+      full: (url) =>
+        PushyModule.downloadFullUpdate({
+          updateUrl: url,
+          hash,
+        }),
+    };
+    // Mirror ranking per strategy, kept across retry attempts: the HEAD race
+    // runs once per strategy per download instead of once per attempt. A
+    // winner that failed its download is demoted to the back for the next
+    // attempt (every mirror is tried on every attempt anyway).
+    const rankedUrls = new Map<DownloadStrategyType, string[]>();
+    const errorKeys = {
+      diff: 'error_diff_failed',
+      pdiff: 'error_pdiff_failed',
+      full: 'error_full_patch_failed',
+    } as const;
+
+    try {
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+          // Exponential backoff with jitter: a bad CDN edge otherwise gets
+          // every client back at the same 1/2/4s marks.
+          const backoffMs = Math.round(
+            Math.min(1000 * 2 ** (attempt - 1), 10000) *
+              (0.75 + Math.random() * 0.5)
+          );
+          log(`retry attempt ${attempt}/${maxRetries}, waiting ${backoffMs}ms`);
+          await new Promise<void>((r) => setTimeout(() => r(), backoffMs));
+          errorMessages.length = 0;
+          errorMessages.push(...exhaustedStrategies.values());
+          lastError = undefined;
+          succeeded = '';
+        }
+        host.report({
+          type: 'downloading',
+          data: {
+            newVersion: hash,
+            attempt,
+          },
+        });
+        for (const { type, urls } of attempts) {
+          if (succeeded) {
+            break;
+          }
+          if (exhaustedStrategies.has(type)) {
+            continue;
+          }
+          // The HEAD race only ranks mirrors; it is not proof that a mirror can
+          // serve the whole artifact (CDNs answer HEAD and GET differently, and
+          // a transfer can die mid-stream). Every mirror of the same artifact
+          // gets a real download attempt before the strategy is abandoned —
+          // the native cold-start path already behaves this way.
+          let orderedUrls = rankedUrls.get(type);
+          if (!orderedUrls) {
+            orderedUrls = await this.rankDownloadUrls(urls);
+            rankedUrls.set(type, orderedUrls);
+          }
+          for (const url of orderedUrls) {
+            log(`downloading ${type} from ${url}`);
+            try {
+              await runners[type](url);
+              succeeded = type;
+              break;
+            } catch (e: unknown) {
+              // The native rejection's stable code (e.g. PATCH_FAILED vs
+              // DOWNLOAD_FAILED — telemetry classifies on it) may sit on the
+              // `code` property or, from bridges that cannot set it, as a
+              // `[CODE] ` message prefix. Either way it survives into the
+              // i18n-wrapped error together with the original as cause.
+              const { code, message } = readErrorCode(e);
+              if (url === orderedUrls[0] && orderedUrls.length > 1) {
+                rankedUrls.set(type, [...orderedUrls.slice(1), url]);
+              }
+              const errorMessage = this.host.t(errorKeys[type], {
+                message: message || String(e ?? ''),
+              });
+              errorMessages.push(errorMessage);
+              lastError = new UpdateError(
+                errorMessage,
+                code ?? 'DOWNLOAD_FAILED',
+                {
+                  cause: e,
+                }
+              );
+              log(errorMessage);
+              if (!isMirrorRetryableCode(lastError.code)) {
+                // The bytes arrived but could not be applied (patch/manifest
+                // mismatch): every mirror serves the same artifact, so move
+                // on to the next strategy instead of re-downloading it.
+                exhaustedStrategies.set(type, errorMessage);
+                break;
+              }
+            }
+          }
+        }
+        if (
+          succeeded ||
+          attempts.every(({ type }) => exhaustedStrategies.has(type))
+        ) {
+          // Nothing left that a retry could change.
+          break;
+        }
+      }
+    } finally {
+      progressSubscription.remove();
+      delete this.state.shared.progressCallbacks[hash];
+    }
+    // Only a patch-stage failure exhausts a strategy (isMirrorRetryableCode),
+    // and an exhausted strategy is never retried: these are exactly the patch
+    // failures, each once.
+    const patchErrorMessages = [...exhaustedStrategies.values()];
+    const patchFailed = patchErrorMessages.length > 0;
+    if (succeeded && errorMessages.length > 0) {
+      // An earlier strategy failed and a later one rescued the download
+      // (e.g. pdiff copiesCrc mismatch on a rebuilt binary → full). Surface
+      // the degradation: it is invisible to the end user but tells the
+      // platform that incremental delivery is failing for this binary.
+      host.report({
+        type: 'downloadFallback',
+        // The patch-health signal (any strategy, in any attempt, failing at
+        // the patch stage) wins over whatever transport failure happened to
+        // come last (diff PATCH_FAILED, then pdiff network error, then full
+        // succeeded is still a patch_fail server-side).
+        code: patchFailed ? 'PATCH_FAILED' : lastError?.code,
+        data: {
+          newVersion: hash,
+          succeeded,
+        },
+        // Only the patch failures: a mirror's timeout alongside them would
+        // otherwise be read as the cause server-side.
+        message: (patchFailed ? patchErrorMessages : errorMessages).join(';'),
+      });
+    }
+    if (!succeeded) {
+      // Every attempt runs at least one download (a plan always has an
+      // artifact URL, devNoop returned above), so a failure left lastError.
+      throw this.reporter.fail(lastError, 'DOWNLOAD_FAILED', 'errorUpdate', {
+        message: errorMessages.join(';'),
+        data: { newVersion: hash },
+      });
+    }
+    const data: Record<string, any> = {
+      newVersion: hash,
+      diff: succeeded,
+      duration: Date.now() - patchStartTime,
+    };
+    if (errorMessages.length > 0) {
+      data.error = errorMessages.join(';');
+    }
+    host.report({
+      type: 'downloadSuccess',
+      data,
+    });
+    log(`downloaded ${succeeded} hash:`, hash);
+    const hashInfo: Record<string, any> = {
+      name,
+      description,
+      metaInfo,
+    };
+    if (this.state.shared.toHash === hash) {
+      hashInfo.debugChannel = true;
+    }
+    // The version is "downloaded" only once its metadata is persisted: a
+    // lost hash-info write would leave the next launch with a nameless
+    // version and a switchVersion that the native side may refuse.
+    try {
+      await setLocalHashInfo(hash, hashInfo);
+    } catch (e: any) {
+      throw this.reporter.fail(e, 'FILE_OPERATION_FAILED', 'errorUpdate', {
+        data: { newVersion: hash },
+      });
+    }
+    this.state.shared.downloadedHash = hash;
+    return hash;
+  };
+
+  downloadAndInstallApk = async (
+    url: string,
+    onDownloadProgress?: (data: ProgressData) => void
+  ) => {
+    const { host } = this;
+    if (Platform.OS !== 'android') {
+      return;
+    }
+    if (this.state.shared.apkStatus === 'downloading') {
+      return;
+    }
+    if (this.state.shared.apkStatus === 'downloaded') {
+      const err = new UpdateError(
+        this.host.t('error_apk_pending_install'),
+        'APK_INSTALL_PENDING'
+      );
+      this.reporter.emitError(err, 'errorInstallApk');
+      host.throwIfEnabled(err);
+      return;
+    }
+    this.state.shared.apkStatus = 'downloading';
+    host.report({ type: 'downloadingApk' });
+    const progressKey = 'downloadingApk';
+    const progressSubscription = onDownloadProgress
+      ? pushyNativeEventEmitter.addListener(
+          'RCTPushyDownloadProgress',
+          (event: unknown) => {
+            const progressData = event as ProgressData;
+            if (progressData.hash === progressKey) {
+              onDownloadProgress(progressData);
+            }
+          }
+        )
+      : undefined;
+    try {
+      await PushyModule.downloadAndInstallApk({
+        url,
+        target: 'update.apk',
+        hash: progressKey,
+      });
+      this.state.shared.apkStatus = 'downloaded';
+    } catch (e) {
+      this.state.shared.apkStatus = null;
+      // Keep the native error (message/stack) instead of discarding it.
+      host.throwIfEnabled(
+        this.reporter.fail(
+          e,
+          'APK_DOWNLOAD_FAILED',
+          'errorDownloadAndInstallApk',
+          {
+            fallbackMessage: this.host.t('error_apk_download_failed'),
+          }
+        )
+      );
+    } finally {
+      progressSubscription?.remove();
+    }
+  };
+}

package/src/clientNativeConfig.ts

@@ -0,0 +1,171 @@
+import { cInfo, nativeMethod } from './core';
+import type { ClientOptions } from './type';
+import { log } from './utils';
+
+/** What the native config sync needs from the client. */
+export interface NativeConfigHost {
+  readonly options: ClientOptions;
+  getEffectivePackageVersion(): string;
+}
+
+/**
+ * Keeps the config the native cold-start check runs with
+ * (NATIVE_CHECKUPDATE_DESIGN §10.1) in step with the client options, and
+ * tells native when JS already holds a check response for it (§10.3).
+ */
+export class NativeConfigSync {
+  constructor(private readonly host: NativeConfigHost) {}
+
+  private syncedNativeConfigJson?: string;
+  private pendingNativeConfigJson?: string;
+  private nativeConfigSyncInFlight = false;
+  // Config last acknowledged by markJsCheckCompleted.
+  private jsCheckCompletedConfigJson?: string;
+
+  /** Build the subset of options used by the native cold-start check. */
+  private getNativeConfig = (): Record<string, unknown> | undefined => {
+    if (!nativeMethod('syncNativeConfig')) {
+      // Web, or an older native without the native check.
+      return undefined;
+    }
+    const {
+      appKey,
+      server,
+      updateStrategy,
+      checkStrategy,
+      disableNativeCheck,
+    } = this.host.options;
+    if (disableNativeCheck) {
+      // Explicit opt-out: keep the identity fields so the persisted config
+      // still describes this app, and let the orchestrators bail on `disabled`
+      // before any IO.
+      return { disabled: true, appKey, rnu: cInfo.rnu, rn: cInfo.rn };
+    }
+    if (!appKey || !server?.main?.length) {
+      // Unusable rather than merely absent: the JS check would fail on these
+      // options too (NO_ENDPOINTS / APPKEY_REQUIRED). The caller turns this
+      // into an explicit disabled state.
+      return undefined;
+    }
+    // An app that turned automatic checks off (checkStrategy: null) must not
+    // be handed a version switch it never asked for. The cold-start check
+    // still runs and still downloads — that is what keeps a bricked device
+    // rescuable — but activation waits for the JS side, or for the server's
+    // explicit per-version forceBoot directive (shouldActivateAfterDownload).
+    const autoCheckEnabled = checkStrategy != null;
+    return {
+      appKey,
+      packageVersion: this.host.getEffectivePackageVersion(),
+      endpoints: server.main,
+      queryUrls: server.queryUrls ?? [],
+      // The native check may activate a downloaded version (next launch)
+      // only under the silent strategies; alert-style strategies keep
+      // activation with the JS side (§6/§10.1).
+      afterDownload:
+        autoCheckEnabled &&
+        (updateStrategy === 'silentAndNow' ||
+          updateStrategy === 'silentAndLater')
+          ? 'setNeedUpdate'
+          : 'none',
+      rnu: cInfo.rnu,
+      rn: cInfo.rn,
+    };
+  };
+
+  getNativeConfigJson = (): string | undefined => {
+    const config = this.getNativeConfig();
+    return config ? JSON.stringify(config) : undefined;
+  };
+
+  private flushNativeConfig = () => {
+    if (this.host.options.nativeConfigSource === 'native') {
+      this.pendingNativeConfigJson = undefined;
+      this.syncedNativeConfigJson = undefined;
+      return;
+    }
+    const sync = nativeMethod('syncNativeConfig');
+    if (!sync || this.nativeConfigSyncInFlight) {
+      return;
+    }
+    const configJson = this.pendingNativeConfigJson;
+    this.pendingNativeConfigJson = undefined;
+    if (!configJson || configJson === this.syncedNativeConfigJson) {
+      return;
+    }
+    this.nativeConfigSyncInFlight = true;
+    sync(configJson)
+      .then(() => {
+        // A switch to 'native' while this write was in flight hands storage
+        // to the host; remembering the write would skip it after switching
+        // back.
+        if (this.host.options.nativeConfigSource !== 'native') {
+          this.syncedNativeConfigJson = configJson;
+        }
+      })
+      .catch((e: any) => {
+        log('syncNativeConfig failed:', e?.message || e);
+      })
+      .finally(() => {
+        this.nativeConfigSyncInFlight = false;
+        this.flushNativeConfig();
+      });
+  };
+
+  /**
+   * Tell the native cold-start orchestrator that this process already holds a
+   * valid check response for the current config, so its delayed round (5s
+   * after launch) does not repeat the request. Fire-and-forget: a failure
+   * costs one duplicate check. Never called on a failed check — the native
+   * rescue must keep running when JS could not reach the server.
+   */
+  markJsCheckCompleted = () => {
+    const markCompleted = nativeMethod('markJsCheckCompleted');
+    if (!markCompleted) {
+      return;
+    }
+    const configJson = this.getNativeConfigJson();
+    if (!configJson || configJson === this.jsCheckCompletedConfigJson) {
+      return;
+    }
+    markCompleted(configJson).then(
+      () => {
+        this.jsCheckCompletedConfigJson = configJson;
+      },
+      (e: any) => {
+        log('markJsCheckCompleted failed:', e?.message || e);
+      }
+    );
+  };
+
+  syncNativeConfig = () => {
+    if (this.host.options.nativeConfigSource === 'native') {
+      // The host owns the stored config now; forget what JS last wrote so a
+      // switch back to 'javascript' writes again instead of deduping
+      // against a value native storage no longer holds.
+      this.pendingNativeConfigJson = undefined;
+      this.syncedNativeConfigJson = undefined;
+      return;
+    }
+    if (!nativeMethod('syncNativeConfig')) {
+      return;
+    }
+    const configJson = this.getNativeConfigJson();
+    if (!configJson) {
+      // No usable config (empty appKey / no endpoints) is almost always a
+      // transient state while options are being assembled. Persisting a
+      // disabled config over the last good one would switch off the
+      // cold-start rescue for every later launch, so keep what native has.
+      // (Web and older natives never reach this point — no method.)
+      log('native check config unusable, keeping the last synced config');
+      return;
+    }
+    // Always record the latest desired value, even when it matches the last
+    // completed write. Example: A synced -> B in flight -> options revert to
+    // A. Comparing only with synced(A) would drop the revert and leave native
+    // storage at B after that in-flight write completes.
+    // Coalesce rapid setOptions calls, but serialize bridge writes so an older
+    // completion can never overwrite the newest desired configuration.
+    this.pendingNativeConfigJson = configJson;
+    this.flushNativeConfig();
+  };
+}