rn-update 1.0.0

package/src/updateFlowCore.ts

@@ -0,0 +1,428 @@
+/**
+ * [INPUT]: 仅以 type-only 方式依赖 CheckResult，所有运行时输入由调用参数注入
+ * [OUTPUT]: 对外提供 rollout/hash、URL 与端点规则、检查请求/结果、激活判断及下载策略的纯函数和类型
+ * [POS]: src 的无 IO 领域决策核心，被 client/Provider 调用并通过共享向量与 C++ update_flow_core 保持行为同构
+ */
+import type { CheckResult } from './type';
+
+// 更新流程的纯决策层:无 IO、不依赖 react-native、无模块级状态,所有输入均由
+// 参数传入(仅允许 type-only import)。这一层必须保持可在裸 JS 引擎中求值——
+// 它就是未来 guardian bundle 的编译单元(NATIVE_CHECKUPDATE_DESIGN §5),
+// IO(HTTP/下载/落盘)由调用方(现在是 client.ts,将来是原生编排)执行。
+
+/* eslint-disable no-fallthrough */
+/* eslint-disable no-bitwise */
+export function murmurhash3_32_gc(key: string, seed = 0) {
+  let remainder: number,
+    bytes: number,
+    h1: number,
+    h1b: number,
+    c1: number,
+    c2: number,
+    k1: number,
+    i: number;
+
+  remainder = key.length & 3; // key.length % 4
+  bytes = key.length - remainder;
+  h1 = seed;
+  c1 = 0xcc9e2d51;
+  c2 = 0x1b873593;
+  i = 0;
+
+  while (i < bytes) {
+    k1 =
+      (key.charCodeAt(i) & 0xff) |
+      ((key.charCodeAt(++i) & 0xff) << 8) |
+      ((key.charCodeAt(++i) & 0xff) << 16) |
+      ((key.charCodeAt(++i) & 0xff) << 24);
+    ++i;
+
+    k1 =
+      ((k1 & 0xffff) * c1 + ((((k1 >>> 16) * c1) & 0xffff) << 16)) & 0xffffffff;
+    k1 = (k1 << 15) | (k1 >>> 17);
+    k1 =
+      ((k1 & 0xffff) * c2 + ((((k1 >>> 16) * c2) & 0xffff) << 16)) & 0xffffffff;
+
+    h1 ^= k1;
+    h1 = (h1 << 13) | (h1 >>> 19);
+    h1b =
+      ((h1 & 0xffff) * 5 + ((((h1 >>> 16) * 5) & 0xffff) << 16)) & 0xffffffff;
+    h1 = (h1b & 0xffff) + 0x6b64 + ((((h1b >>> 16) + 0xe654) & 0xffff) << 16);
+  }
+
+  k1 = 0;
+
+  switch (remainder) {
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: MurmurHash fallthrough
+    case 3:
+      k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+    // biome-ignore lint/suspicious/noFallthroughSwitchClause: MurmurHash fallthrough
+    case 2:
+      k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+    case 1:
+      k1 ^= key.charCodeAt(i) & 0xff;
+
+      k1 =
+        ((k1 & 0xffff) * c1 + ((((k1 >>> 16) * c1) & 0xffff) << 16)) &
+        0xffffffff;
+      k1 = (k1 << 15) | (k1 >>> 17);
+      k1 =
+        ((k1 & 0xffff) * c2 + ((((k1 >>> 16) * c2) & 0xffff) << 16)) &
+        0xffffffff;
+      h1 ^= k1;
+  }
+
+  h1 ^= key.length;
+
+  h1 ^= h1 >>> 16;
+  h1 =
+    ((h1 & 0xffff) * 0x85ebca6b +
+      ((((h1 >>> 16) * 0x85ebca6b) & 0xffff) << 16)) &
+    0xffffffff;
+  h1 ^= h1 >>> 13;
+  h1 =
+    ((h1 & 0xffff) * 0xc2b2ae35 +
+      ((((h1 >>> 16) * 0xc2b2ae35) & 0xffff) << 16)) &
+    0xffffffff;
+  h1 ^= h1 >>> 16;
+
+  return h1 >>> 0;
+}
+
+export function isInRollout(rollout: number, uuid: string) {
+  return murmurhash3_32_gc(uuid) % 100 < rollout;
+}
+
+export function joinUrls(paths: string[], fileName?: string) {
+  if (fileName) {
+    return paths.map((path) => {
+      const normalizedPath = path.replace(/\/+$/, '');
+      // Keep explicit http(s) URLs for local/self-hosted update sources.
+      const baseUrl = /^[a-z][a-z0-9+.-]*:\/\//i.test(normalizedPath)
+        ? normalizedPath
+        : `https://${normalizedPath}`;
+      return `${baseUrl}/${fileName}`;
+    });
+  }
+}
+
+export const dedupeEndpoints = (
+  endpoints: Array<string | null | undefined>
+): string[] => {
+  const result: string[] = [];
+  const visited = new Set<string>();
+
+  for (const endpoint of endpoints) {
+    if (!endpoint || visited.has(endpoint)) {
+      continue;
+    }
+    visited.add(endpoint);
+    result.push(endpoint);
+  }
+
+  return result;
+};
+
+/**
+ * The endpoint plan: dedupe, then move the sampled pick to the front (load
+ * spreading), keeping the rest in configured order as the fallback sequence.
+ * `randomSample` ∈ [0, 1) is injected by the caller — this layer cannot draw
+ * randomness itself.
+ */
+export function orderEndpointCandidates(
+  endpoints: Array<string | null | undefined>,
+  randomSample = 0
+): string[] {
+  const deduped = dedupeEndpoints(endpoints);
+  if (deduped.length < 2) {
+    return deduped;
+  }
+  const first = Math.max(
+    0,
+    Math.min(
+      Number.isFinite(randomSample)
+        ? Math.floor(randomSample * deduped.length)
+        : 0,
+      deduped.length - 1
+    )
+  );
+  return [
+    deduped[first],
+    ...deduped.slice(0, first),
+    ...deduped.slice(first + 1),
+  ];
+}
+
+export interface CheckRequestInput {
+  /** Effective native package version (overridePackageVersion already applied). */
+  packageVersion: string;
+  /** Immutable channel declared by the native binary. */
+  channel?: string;
+  /** Hash of the currently running JS version ('' when on the packaged bundle). */
+  currentVersion?: string;
+  buildTime: string;
+  cInfo: Record<string, string>;
+  supportedDiffVersion?: number;
+  /** '' or undefined while unknown — the field is then omitted. */
+  bundleHash?: string;
+  isDev?: boolean;
+  extra?: Record<string, any>;
+}
+
+export function buildCheckRequestBody({
+  packageVersion,
+  channel,
+  currentVersion,
+  buildTime,
+  cInfo,
+  supportedDiffVersion,
+  bundleHash,
+  isDev,
+  extra,
+}: CheckRequestInput): Record<string, any> {
+  // Caller extras are spread FIRST so they can add fields (channel, custom
+  // filters, the debug-channel toHash) but never override the SDK identity
+  // fields the server keys its decision on: a stray `packageVersion` or
+  // `hash` in extra would otherwise make the server hand out a package for
+  // the wrong binary.
+  const body: Record<string, any> = {
+    ...extra,
+    packageVersion,
+    channel: channel || 'default',
+    hash: currentVersion,
+    buildTime,
+    cInfo,
+  };
+  // 可消费的 diff 轨道版本(2 = hdiffv2 轨道),服务端据此门控下发
+  if (supportedDiffVersion) {
+    body.diffV = supportedDiffVersion;
+  } else {
+    delete body.diffV;
+  }
+  if (bundleHash) {
+    body.bundleHash = bundleHash;
+  } else {
+    delete body.bundleHash;
+  }
+  if (isDev) {
+    delete body.buildTime;
+  }
+  // Transitional dual form: the legacy root-level spread above is what
+  // servers before 2026-08-30 read; the nested copy is what new servers read
+  // first (extra.toHash wins there) and lets caller keys stop sharing the
+  // SDK's namespace once the root spread is retired.
+  if (extra) {
+    // Match JSON.stringify semantics: undefined values do not exist on the
+    // wire, so they must not create a nested copy either (the native check
+    // cache compares serialized requests).
+    const defined: Record<string, any> = {};
+    for (const [key, value] of Object.entries(extra)) {
+      if (value !== undefined) {
+        defined[key] = value;
+      }
+    }
+    if (Object.keys(defined).length > 0) {
+      body.extra = defined;
+    }
+  }
+  return body;
+}
+
+export interface CheckFingerprintInput {
+  appKey?: string;
+  endpoints?: string[];
+  queryUrls?: string[];
+  uuid?: string;
+  /** The exact serialized request body (identity fields + extra). */
+  body: string;
+}
+
+/**
+ * Identity of one update check. Two checks may share an in-flight response
+ * only when every input that could change the server's answer is identical.
+ */
+export function buildCheckFingerprint({
+  appKey,
+  endpoints,
+  queryUrls,
+  uuid,
+  body,
+}: CheckFingerprintInput): string {
+  return JSON.stringify([
+    appKey ?? '',
+    endpoints ?? [],
+    queryUrls ?? [],
+    uuid ?? '',
+    body,
+  ]);
+}
+
+/**
+ * Whether a failed download attempt is worth retrying on another mirror of
+ * the same artifact. Transport failures (DNS, connect, timeout, truncated
+ * body, 5xx) and corrupt bytes are; a patch that downloaded fine but could
+ * not be applied is not — every mirror serves the same bytes, so the next
+ * strategy is the only way forward.
+ */
+export function isMirrorRetryableCode(code?: string): boolean {
+  return code !== 'PATCH_FAILED';
+}
+
+/**
+ * Schema gate for a checkUpdate response (mirrors C++ IsValidCheckResult): a
+ * JSON object carrying at least one verdict field of the expected type —
+ * `upToDate` / `update` / `expired` (boolean) or `paused` (string). A 200
+ * with `{"error": ...}`, an array or an HTML page that happened to parse is
+ * a failed endpoint, not a verdict, and must not stop the endpoint fallback.
+ */
+export function isValidCheckResult(value: unknown): value is CheckResult {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const root = value as Record<string, unknown>;
+  return (
+    typeof root.upToDate === 'boolean' ||
+    typeof root.update === 'boolean' ||
+    typeof root.expired === 'boolean' ||
+    typeof root.paused === 'string'
+  );
+}
+
+export interface UpdateIdentity {
+  packageVersion: string;
+  currentVersion?: string;
+  /** Stable client uuid — the gray-release bucketing key. */
+  uuid: string;
+}
+
+export function resolveCheckResult(
+  rootInfo: CheckResult,
+  identity: UpdateIdentity,
+  log: (...args: any[]) => void = () => {}
+): CheckResult {
+  const { expVersion, ...rootResult } = rootInfo;
+  const rollout = expVersion?.config?.rollout?.[identity.packageVersion];
+  if (rootResult.update && expVersion && typeof rollout === 'number') {
+    if (isInRollout(rollout, identity.uuid)) {
+      log(`${expVersion.name} in ${rollout}% rollout, continue`);
+      if (
+        typeof expVersion.hash === 'string' &&
+        expVersion.hash.length > 0 &&
+        expVersion.hash === identity.currentVersion
+      ) {
+        return { upToDate: true };
+      }
+      const info: CheckResult = {
+        update: true,
+        ...expVersion,
+      };
+      if (rootResult.paths) {
+        info.paths = rootResult.paths;
+      }
+      return info;
+    }
+    log(`${expVersion.name} not in ${rollout}% rollout, ignored`);
+  }
+  if (
+    rootResult.update &&
+    typeof rootResult.hash === 'string' &&
+    rootResult.hash.length > 0 &&
+    rootResult.hash === identity.currentVersion
+  ) {
+    return { upToDate: true };
+  }
+  return rootResult;
+}
+
+/**
+ * Whether the native orchestrator should activate a downloaded version for
+ * the next launch: either the client opted in via its silent strategies
+ * (afterDownload === 'setNeedUpdate'), or the server marked this version
+ * `config.forceBoot` — the per-version remote override that closes the
+ * brick-rescue gap for alert-strategy apps (a bricked device never runs JS,
+ * so activation cannot wait for it). Native-only: the JS side's interactive
+ * strategies are not consulted and not affected. The device-local
+ * rolledBackVersion guard in decideDownload still wins over forceBoot, and
+ * the activated version keeps the first_time crash-protection rollback.
+ */
+export function shouldActivateAfterDownload(
+  info: CheckResult,
+  afterDownload?: string
+): boolean {
+  return afterDownload === 'setNeedUpdate' || !!info?.config?.forceBoot;
+}
+
+export type DownloadStrategyType = 'diff' | 'pdiff' | 'full';
+
+export interface DownloadAttempt {
+  type: DownloadStrategyType;
+  /** Candidate URLs (paths × file name); the executor probes and picks one. */
+  urls: string[];
+}
+
+export interface DownloadPlan {
+  hash: string;
+  /** Ordered attempts: incremental first, full as the last resort. */
+  attempts: DownloadAttempt[];
+  /**
+   * Dev-only: nothing to fetch. The executor logs why and delivers nothing
+   * (resolves undefined) — not a fake success whose hash could never be
+   * switched to.
+   */
+  devNoop: boolean;
+}
+
+export type DownloadDecision =
+  | {
+      action: 'none';
+      reason: 'noUpdate' | 'alreadyCurrent' | 'rolledBack' | 'noArtifact';
+    }
+  | ({ action: 'download' } & DownloadPlan);
+
+export function decideDownload(
+  info: CheckResult,
+  identity: { currentVersion?: string; rolledBackVersion?: string },
+  isDev = false
+): DownloadDecision {
+  const { hash, diff, pdiff, full } = info;
+  // A server `paths: null` behaves like an absent field (a destructuring
+  // default only covers undefined, and `null.map` would throw). The C++ port
+  // treats null and undefined alike here.
+  const paths = info.paths ?? [];
+  if (!info.update || !hash) {
+    return { action: 'none', reason: 'noUpdate' };
+  }
+  if (hash === identity.currentVersion) {
+    return { action: 'none', reason: 'alreadyCurrent' };
+  }
+  if (identity.rolledBackVersion && hash === identity.rolledBackVersion) {
+    return { action: 'none', reason: 'rolledBack' };
+  }
+  const attempts: DownloadAttempt[] = [];
+  // Incremental artifacts only exist against release builds; dev goes
+  // straight to full (or the no-op below when there is none).
+  if (!isDev) {
+    const diffUrls = joinUrls(paths, diff);
+    if (diffUrls?.length) {
+      attempts.push({ type: 'diff', urls: diffUrls });
+    }
+    const pdiffUrls = joinUrls(paths, pdiff);
+    if (pdiffUrls?.length) {
+      attempts.push({ type: 'pdiff', urls: pdiffUrls });
+    }
+  }
+  const fullUrls = joinUrls(paths, full);
+  if (fullUrls?.length) {
+    attempts.push({ type: 'full', urls: fullUrls });
+  }
+  const devNoop = !!isDev && !fullUrls?.length;
+  if (!attempts.length && !devNoop) {
+    return { action: 'none', reason: 'noArtifact' };
+  }
+  return {
+    action: 'download',
+    hash,
+    attempts,
+    devNoop,
+  };
+}

package/src/utils.ts

@@ -0,0 +1,268 @@
+/**
+ * [INPUT]: 依赖 react-native Platform、i18n，以及宿主提供的 fetch/AbortController/console 基础能力
+ * [OUTPUT]: 对外提供统一日志、平台断言、空实现、URL 探测、进度计算、超时与幂等重试 fetch 工具
+ * [POS]: src 的横切基础设施工具集，被 core、client 与 Provider 复用；业务策略应留在 updateFlowCore 而非在此生长
+ */
+import { Platform } from 'react-native';
+import i18n from './i18n';
+
+// log/info are developer diagnostics (they include full check request bodies
+// and responses); release builds only print them when the client's `debug`
+// option is on. warn/error always print.
+let debugLogging = false;
+export const setDebugLogging = (enabled: boolean) => {
+  debugLogging = !!enabled;
+};
+const isVerbose = () =>
+  // Metro always defines __DEV__; guard anyway so a bundler that does not
+  // cannot break the whole module at import time.
+  (typeof __DEV__ === 'boolean' && __DEV__) || debugLogging;
+
+export function log(...args: any[]) {
+  if (isVerbose()) {
+    console.log(i18n.t('dev_log_prefix'), ...args);
+  }
+}
+
+export function info(...args: any[]) {
+  if (isVerbose()) {
+    console.info(i18n.t('dev_log_prefix'), ...args);
+  }
+}
+
+export function warn(...args: any[]) {
+  console.warn(i18n.t('dev_log_prefix'), ...args);
+}
+
+export function error(...args: any[]) {
+  console.error(i18n.t('dev_log_prefix'), ...args);
+}
+
+export const isWeb = Platform.OS === 'web';
+export const DEFAULT_FETCH_TIMEOUT_MS = 5000;
+
+export function promiseAny<T>(promises: Promise<T>[]) {
+  return new Promise<T>((resolve, reject) => {
+    if (!promises.length) {
+      reject(Error(i18n.t('error_all_promises_rejected')));
+      return;
+    }
+    let count = 0;
+
+    promises.forEach((promise) => {
+      Promise.resolve(promise)
+        .then(resolve)
+        .catch(() => {
+          count++;
+          if (count === promises.length) {
+            reject(Error(i18n.t('error_all_promises_rejected')));
+          }
+        });
+    });
+  });
+}
+
+export const noop = () => {};
+const emptyModuleTarget: Record<string, typeof noop> = {};
+export const emptyModule = new Proxy(emptyModuleTarget, {
+  get(_target, _prop) {
+    return noop;
+  },
+});
+
+const ping = isWeb
+  ? Promise.resolve
+  : async (url: string) => {
+      try {
+        const {
+          status,
+          statusText,
+          url: finalUrl,
+        } = await fetchWithTimeout(
+          url,
+          {
+            method: 'HEAD',
+          },
+          DEFAULT_FETCH_TIMEOUT_MS
+        );
+        if (status === 200) {
+          if (isProtocolDowngrade(url, finalUrl)) {
+            // The probe was redirected from https to plaintext http. Never
+            // let a downgraded final URL win the race: the winner is what
+            // the real artifact download uses.
+            log('ping rejected: https redirected to http', url, finalUrl);
+            throw Error(i18n.t('error_ping_failed'));
+          }
+          return finalUrl;
+        }
+        log('ping failed', url, status, statusText);
+        throw Error(i18n.t('error_ping_failed'));
+      } catch (e) {
+        log('ping error', url, e);
+        throw e;
+      }
+    };
+
+export { joinUrls } from './updateFlowCore';
+
+export const testUrls = async (urls?: string[]): Promise<string | null> => {
+  if (!urls?.length) {
+    return null;
+  }
+
+  try {
+    const ret = await promiseAny(urls.map(ping));
+    if (ret) {
+      log('ping success, use url:', ret);
+      return ret as string;
+    }
+  } catch {}
+  log('all ping failed, use first url:', urls[0]);
+  return urls[0];
+};
+
+export const assertWeb = () => {
+  if (isWeb) {
+    warn(i18n.t('dev_web_not_supported'));
+    return false;
+  }
+  return true;
+};
+
+export const computeProgress = (received: number, total: number): number =>
+  total > 0
+    ? Math.min(100, Math.max(0, Math.floor((received / total) * 100)))
+    : 0;
+
+export const fetchWithTimeout = (
+  url: string,
+  params: Parameters<typeof fetch>[1],
+  timeoutMs = DEFAULT_FETCH_TIMEOUT_MS
+): Promise<Response> => {
+  // AbortController landed in the RN fetch polyfill around 0.60; we support
+  // older peers, so fall back to a plain timer race when it is unavailable
+  // (the losing fetch keeps running there — old runtimes can't do better).
+  if (typeof AbortController === 'undefined') {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    return Promise.race([
+      enhancedFetch(url, params),
+      new Promise<Response>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          log('fetch timeout', url);
+          reject(Error(i18n.t('error_ping_timeout')));
+        }, timeoutMs);
+      }),
+    ]).finally(() => {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    });
+  }
+
+  // Abort the underlying request on timeout instead of racing a timer: with
+  // Promise.race the losing fetch kept running (and kept the connection busy)
+  // long after the caller had already moved on.
+  const controller = new AbortController();
+  // The timeout controller replaces params.signal on the fetch call, so a
+  // caller-provided signal (e.g. the hedged endpoint race cancelling losers)
+  // must be chained onto it manually.
+  const externalSignal = (params as any)?.signal as AbortSignal | undefined;
+  const onExternalAbort = () => controller.abort();
+  if (externalSignal?.aborted) {
+    controller.abort();
+  } else if (externalSignal) {
+    externalSignal.addEventListener('abort', onExternalAbort);
+  }
+  const timeoutId = setTimeout(() => {
+    log('fetch timeout', url);
+    controller.abort();
+  }, timeoutMs);
+
+  return enhancedFetch(url, { ...params, signal: controller.signal as any })
+    .catch((e: any) => {
+      if (externalSignal?.aborted) {
+        // Cancelled by the caller, not timed out; keep the abort semantics.
+        throw e;
+      }
+      if (controller.signal.aborted) {
+        throw Error(i18n.t('error_ping_timeout'));
+      }
+      throw e;
+    })
+    .finally(() => {
+      clearTimeout(timeoutId);
+      // A long-lived caller signal (one per endpoint race) would otherwise
+      // keep every finished request's listener — and its controller — alive.
+      externalSignal?.removeEventListener('abort', onExternalAbort);
+    });
+};
+
+/**
+ * Query parameters of a URL as a plain object, without a URL polyfill: the
+ * only consumer is the test-channel deep link (`?type=...&data=...`). Handles
+ * a missing `?`, a `#fragment`, `+` as space and percent-encoding; a value
+ * that fails to decode is kept verbatim rather than throwing. Later
+ * duplicates win.
+ */
+export const parseQueryParams = (url: string): Record<string, string> => {
+  const params: Record<string, string> = {};
+  const hashStart = url.indexOf('#');
+  const withoutFragment = hashStart < 0 ? url : url.slice(0, hashStart);
+  const queryStart = withoutFragment.indexOf('?');
+  if (queryStart < 0) {
+    return params;
+  }
+  const query = withoutFragment.slice(queryStart + 1);
+  const decode = (value: string) => {
+    const spaced = value.replace(/\+/g, ' ');
+    try {
+      return decodeURIComponent(spaced);
+    } catch {
+      return spaced;
+    }
+  };
+  for (const pair of query.split('&')) {
+    if (!pair) {
+      continue;
+    }
+    const separator = pair.indexOf('=');
+    const key = decode(separator < 0 ? pair : pair.slice(0, separator));
+    if (!key) {
+      continue;
+    }
+    params[key] = separator < 0 ? '' : decode(pair.slice(separator + 1));
+  }
+  return params;
+};
+
+/**
+ * True when `finalUrl` (after redirects) is plaintext http while the request
+ * started on https. An https endpoint or artifact URL must never be served
+ * over http, redirected or otherwise: the update package is the supply chain
+ * boundary, and TLS is the only thing authenticating it.
+ */
+export const isProtocolDowngrade = (
+  requestedUrl: string,
+  finalUrl?: string | null
+): boolean =>
+  !!finalUrl && /^https:/i.test(requestedUrl) && /^http:/i.test(finalUrl);
+
+export const enhancedFetch = async (
+  url: string,
+  params: Parameters<typeof fetch>[1]
+): Promise<Response> => {
+  // No https -> http retry here, ever. Earlier versions replayed failed
+  // idempotent https requests over plaintext http as a "network
+  // compatibility" fallback; that silently moved endpoint discovery and
+  // package downloads outside TLS. Self-hosted plaintext deployments must
+  // configure explicit http:// URLs instead.
+  const response = await fetch(url, params).catch((e) => {
+    log('fetch error', url, e);
+    throw e;
+  });
+  if (isProtocolDowngrade(url, response?.url)) {
+    log('fetch rejected: https redirected to http', url, response.url);
+    throw Error(i18n.t('error_insecure_redirect'));
+  }
+  return response;
+};