rn-update 1.0.0

package/harmony/pakta/src/main/ets/DownloadTaskParams.ts

@@ -0,0 +1,27 @@
+/**
+ * [INPUT]: 依赖 UpdateContext 的任务构造与 Harmony 文件/网络目标字段
+ * [OUTPUT]: 对外提供清理、全量、APP 差分、PPK 差分和普通下载的任务参数对象
+ * [POS]: UpdateContext 与 DownloadTask 之间的命令信封，集中表达制品身份、目录和冷启动截止时间
+ */
+/**
+ * 下载任务参数类
+ */
+export class DownloadTaskParams {
+  // 任务类型常量
+  static readonly TASK_TYPE_CLEANUP: number = 0; // 保留hash和originHash
+  static readonly TASK_TYPE_PATCH_FULL: number = 1; // 全量补丁
+  static readonly TASK_TYPE_PATCH_FROM_APP: number = 2; // 从APP补丁
+  static readonly TASK_TYPE_PATCH_FROM_PPK: number = 3; // 从PPK补丁
+  static readonly TASK_TYPE_PLAIN_DOWNLOAD: number = 4; // 普通下载
+
+  type: number = DownloadTaskParams.TASK_TYPE_CLEANUP; // 任务类型
+  url: string = ''; // 下载URL
+  hash: string = ''; // 文件哈希值
+  originHash: string = ''; // 原始文件哈希值
+  targetFile: string = ''; // 目标文件路径
+  unzipDirectory: string = ''; // 解压目录路径
+  originDirectory: string = ''; // 原始文件目录路径
+  // Native cold-start orchestrator's absolute monotonic-uptime deadline. Zero
+  // uses the normal public download API's 10-minute whole-call cap.
+  deadlineUptimeMs: number = 0;
+}

package/harmony/pakta/src/main/ets/ErrorCodes.ts

@@ -0,0 +1,80 @@
+/**
+ * [INPUT]: 无依赖（自包含叶子模块），手动镜像 cpp/patch_core/error_codes.h 的错误码
+ * [OUTPUT]: 提供稳定错误码常量、UpdateError（code 属性 + [CODE] 消息前缀）与 createUpdateError/toUpdateError/parseErrorCodePrefix
+ * [POS]: harmony/pakta 的错误码契约层，供任何 ets 文件安全引用而不成环
+ */
+// ArkTS mirror of cpp/patch_core/error_codes.h — keep in sync by hand
+// (harmony/pakta/src/test/check-constant-parity.js asserts the values match).
+// 与 Android/iOS 共用的稳定错误码:JS 层(src/error.ts)按 code 聚合遥测,
+// 消息文案各平台可不同,只有码是契约。
+//
+// RNOH 的异步桥以纯字符串 reject,Error 上的 `code` 属性到 JS 侧很可能已丢。
+// 因此每个错误的消息都以 `[CODE] ` 前缀开头,JS 鸿蒙分支据此解析回 code。
+// 本文件不依赖任何其他模块,任何文件都可安全引用它而不会形成 import 环。
+
+export const ERROR_INVALID_OPTIONS = 'INVALID_OPTIONS';
+export const ERROR_DOWNLOAD_FAILED = 'DOWNLOAD_FAILED';
+export const ERROR_PATCH_FAILED = 'PATCH_FAILED';
+export const ERROR_FILE_OPERATION_FAILED = 'FILE_OPERATION_FAILED';
+export const ERROR_SWITCH_VERSION_FAILED = 'SWITCH_VERSION_FAILED';
+export const ERROR_MARK_SUCCESS_FAILED = 'MARK_SUCCESS_FAILED';
+export const ERROR_RESTART_FAILED = 'RESTART_FAILED';
+export const ERROR_RESET_FAILED = 'RESET_FAILED';
+export const ERROR_INVALID_HASH_INFO = 'INVALID_HASH_INFO';
+export const ERROR_UNSUPPORTED_PLATFORM = 'UNSUPPORTED_PLATFORM';
+export const ERROR_APK_INSTALL_PERMISSION_REQUIRED =
+  'APK_INSTALL_PERMISSION_REQUIRED';
+export const ERROR_APK_INSTALL_FAILED = 'APK_INSTALL_FAILED';
+
+/**
+ * 带稳定错误码的 Error:`code` 是属性,消息同时带 `[CODE] ` 前缀(桥丢属性时
+ * JS 仍能解析)。始终经 createUpdateError / toUpdateError 构造。
+ */
+export class UpdateError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(`[${code}] ${message}`);
+    this.name = 'UpdateError';
+    this.code = code;
+  }
+}
+
+/** 任意抛出值的可读消息(Error 取 message,其余 String())。 */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String((error as Record<string, unknown>).message);
+  }
+  return String(error);
+}
+
+export function createUpdateError(code: string, message: string): UpdateError {
+  return new UpdateError(code, message);
+}
+
+/**
+ * 给未带码的错误补上 `code`:已是 UpdateError 的原样返回(保留其更精确的码
+ * 与前缀,绝不叠两层前缀),其余按 defaultCode 重包并保留原消息。
+ */
+export function toUpdateError(error: unknown, defaultCode: string): UpdateError {
+  if (error instanceof UpdateError) {
+    return error;
+  }
+  return new UpdateError(defaultCode, getErrorMessage(error));
+}
+
+/** 从 `[CODE] message` 形式的消息里解析错误码;无前缀返回空串。 */
+export function parseErrorCodePrefix(message: string): string {
+  if (typeof message !== 'string' || !message.startsWith('[')) {
+    return '';
+  }
+  const end = message.indexOf('] ');
+  if (end <= 1) {
+    return '';
+  }
+  const code = message.substring(1, end);
+  return /^[A-Z][A-Z0-9_]*$/.test(code) ? code : '';
+}

package/harmony/pakta/src/main/ets/EventHub.ts

@@ -0,0 +1,46 @@
+/**
+ * [INPUT]: 依赖 RNOH RNInstance 的 emitDeviceEvent 与订阅方的事件名/载荷
+ * [OUTPUT]: 对外提供 EventHub 单例、emit、setRNInstance/clearRNInstance 与 DeviceEventEmitter 结构化类型
+ * [POS]: Harmony 原生事件边界，将下载进度从任务层投影到 React Native，不保存业务状态
+ */
+// The subset of RNOH's RNInstance the SDK needs: device events for download
+// progress. Typed structurally so the hypium tests can pass a mock.
+export interface DeviceEventEmitter {
+  emitDeviceEvent(eventName: string, payload: Object): void;
+}
+
+export class EventHub {
+  private static instance: EventHub;
+  // 指向最近一次构造 TurboModule 的 RNInstance:RNOH 重建 RN 实例时会构造
+  // 新的 TurboModule 并在此替换,已销毁实例上的 emit 由 RNOH 自行忽略。
+  private rnInstance: DeviceEventEmitter | undefined = undefined;
+
+  private constructor() {}
+
+  public static getInstance(): EventHub {
+    if (!EventHub.instance) {
+      EventHub.instance = new EventHub();
+    }
+    return EventHub.instance;
+  }
+
+  public emit(event: string, data: Object): void {
+    if (this.rnInstance) {
+      this.rnInstance.emitDeviceEvent(event, data);
+    }
+  }
+
+  setRNInstance(instance: DeviceEventEmitter | undefined): void {
+    this.rnInstance = instance;
+  }
+
+  /**
+   * TurboModule 销毁时调用:只在仍指向该实例时清除——RNOH 重建 RN 实例时
+   * 新 TurboModule 可能先于旧实例的销毁回调构造,不能把新引用一并清掉。
+   */
+  clearRNInstance(instance: DeviceEventEmitter | undefined): void {
+    if (instance !== undefined && this.rnInstance === instance) {
+      this.rnInstance = undefined;
+    }
+  }
+}

package/harmony/pakta/src/main/ets/InstallRecord.ts

@@ -0,0 +1,192 @@
+/**
+ * [INPUT]: 依赖 @ohos.file.fs、@kit.ArkTS util、NativePatchCore 与 ErrorCodes；镜像 cpp/patch_core/install_record.h
+ * [OUTPUT]: 提供两阶段安装完成记录（.pakta-complete）的构建/写入(fsync)/解析/校验与 staging 目录、保留条目前缀工具
+ * [POS]: harmony/pakta 的安装完整性层，原子 rename 前落记录、激活前重验 bundle 摘要
+ */
+import fileIo from '@ohos.file.fs';
+import { util } from '@kit.ArkTS';
+import NativePatchCore from './NativePatchCore';
+import { ERROR_SWITCH_VERSION_FAILED, createUpdateError } from './ErrorCodes';
+
+// ArkTS mirror of cpp/patch_core/install_record.h — keep in sync by hand
+// (harmony/pakta/src/test/check-constant-parity.js asserts the values match).
+// 两阶段安装的完成记录:作为安装最后一步写进 staging 目录,随后 staging
+// 原子 rename 成版本目录;激活前重新校验 bundle 摘要。空文件 = 旧版 SDK
+// 写的历史标记,仍视为完整安装(无摘要可验)。
+export const INSTALL_RECORD_SCHEMA = 1;
+export const INSTALL_RECORD_FILE_NAME = '.pakta-complete';
+export const STAGING_SUFFIX = '.staging';
+// 归档不得携带任何 `.pakta-` 前缀的条目(任意深度):这些名字保留给 SDK 自己
+// 写的记录,与 Android 的规则一致。
+export const RESERVED_ENTRY_PREFIX = '.pakta-';
+export const HARMONY_BUNDLE_FILE_NAME = 'bundle.harmony.js';
+
+export interface InstallRecordData {
+  schema?: number;
+  versionHash?: string;
+  bundleSha256?: string;
+  artifactSha256?: string;
+}
+
+export function stagingDirectoryFor(versionDir: string): string {
+  return `${versionDir}${STAGING_SUFFIX}`;
+}
+
+export function isReservedEntryName(name: string): boolean {
+  return name.startsWith(RESERVED_ENTRY_PREFIX);
+}
+
+export function buildInstallRecord(
+  versionHash: string,
+  bundleSha256: string,
+  artifactSha256: string,
+): string {
+  const record: InstallRecordData = {
+    schema: INSTALL_RECORD_SCHEMA,
+    versionHash,
+  };
+  if (bundleSha256) {
+    record.bundleSha256 = bundleSha256;
+  }
+  if (artifactSha256) {
+    record.artifactSha256 = artifactSha256;
+  }
+  return JSON.stringify(record);
+}
+
+/** 写入并 fsync:紧随其后的 rename 必须能在盘上看到它。 */
+export async function writeInstallRecord(
+  versionDir: string,
+  recordJson: string,
+): Promise<void> {
+  const path = `${versionDir}/${INSTALL_RECORD_FILE_NAME}`;
+  if (fileIo.accessSync(path)) {
+    await fileIo.unlink(path);
+  }
+  const file = await fileIo.open(
+    path,
+    fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY,
+  );
+  try {
+    const bytes = new util.TextEncoder().encodeInto(recordJson);
+    await fileIo.write(file.fd, bytes.buffer as ArrayBuffer);
+    await fileIo.fsync(file.fd);
+  } finally {
+    await fileIo.close(file);
+  }
+}
+
+/**
+ * 解析记录文本:空串(历史标记)返回 {};畸形/非对象返回 null。纯函数,
+ * 供 readInstallRecord 与单测共用。
+ */
+export function parseInstallRecord(text: string): InstallRecordData | null {
+  if (text.length === 0) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text) as InstallRecordData | null;
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed
+      : null;
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 读取记录:文件缺失/畸形返回 null;空文件(历史标记)返回 {}。
+ */
+export function readInstallRecord(versionDir: string): InstallRecordData | null {
+  const path = `${versionDir}/${INSTALL_RECORD_FILE_NAME}`;
+  if (!fileIo.accessSync(path)) {
+    return null;
+  }
+  try {
+    const stat = fileIo.statSync(path);
+    if (stat.size === 0) {
+      return {};
+    }
+    if (stat.size > 64 * 1024) {
+      return null;
+    }
+    return parseInstallRecord(fileIo.readTextSync(path));
+  } catch (e) {
+    return null;
+  }
+}
+
+/** 记录是否宣告本版本完整安装(历史空记录视为是)。纯函数。 */
+export function isRecordForVersion(
+  record: InstallRecordData | null,
+  versionHash: string,
+): boolean {
+  if (record === null) {
+    return false;
+  }
+  if (Object.keys(record).length === 0) {
+    return true;
+  }
+  return (
+    record.schema === INSTALL_RECORD_SCHEMA && record.versionHash === versionHash
+  );
+}
+
+/** 存在性判定(启动/去重路径,不算摘要):记录存在且(非历史空文件时)指向本版本。 */
+export function isInstallComplete(versionDir: string, versionHash: string): boolean {
+  return isRecordForVersion(readInstallRecord(versionDir), versionHash);
+}
+
+/**
+ * 激活前的记录校验(不含摘要):返回需要复核的 bundle 摘要,历史空记录或
+ * 无摘要记录返回空串;记录缺失/不符抛 SWITCH_VERSION_FAILED。纯函数。
+ */
+export function expectedBundleSha256ForActivation(
+  record: InstallRecordData | null,
+  versionHash: string,
+): string {
+  if (record === null) {
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} has no valid completion record.`,
+    );
+  }
+  if (Object.keys(record).length === 0) {
+    return '';
+  }
+  if (
+    record.schema !== INSTALL_RECORD_SCHEMA ||
+    record.versionHash !== versionHash
+  ) {
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} completion record mismatch.`,
+    );
+  }
+  return record.bundleSha256 ?? '';
+}
+
+/**
+ * 激活前校验:记录带摘要时在 native 工作线程重新计算 bundle 摘要(整包
+ * 几十 MB,不能在 UI 线程同步算);不通过则抛错说明原因。
+ */
+export async function verifyInstallForActivation(
+  versionDir: string,
+  versionHash: string,
+  bundlePath: string,
+): Promise<void> {
+  const expected = expectedBundleSha256ForActivation(
+    readInstallRecord(versionDir),
+    versionHash,
+  );
+  if (!expected) {
+    return;
+  }
+  const actual = await NativePatchCore.sha256HexFileAsync(bundlePath);
+  if (actual.toLowerCase() !== expected.toLowerCase()) {
+    throw createUpdateError(
+      ERROR_SWITCH_VERSION_FAILED,
+      `Bundle version ${versionHash} bundle digest mismatch.`,
+    );
+  }
+}

package/harmony/pakta/src/main/ets/Logger.ts

@@ -0,0 +1,83 @@
+/**
+ * [INPUT]: 依赖 @ohos.hilog 的 domain/prefix/format 记录能力与调用方字符串参数
+ * [OUTPUT]: 对外提供 pakta Logger 单例，收敛 debug/info/warn/error 日志格式
+ * [POS]: Harmony 平台日志适配层，业务模块不直接散落 hilog 参数或 console 策略
+ */
+import hilog from '@ohos.hilog';
+
+class Logger {
+  private domain: number;
+  private prefix: string;
+  private format: string = '%{public}s,%{public}s';
+  private isDebug: boolean;
+
+  constructor(
+    prefix: string = 'MyApp',
+    domain: number = 0xff00,
+    isDebug = false,
+  ) {
+    this.prefix = prefix;
+    this.domain = domain;
+    this.isDebug = isDebug;
+  }
+
+  // debug 级别默认关闭;宿主处于 RN 调试模式(RNOH isDebugModeEnabled)时由
+  // TurboModule 在启动时打开,方便接入调试。info/warn/error 永远输出。
+  // (HAR 自身没有可靠的构建期 DEBUG 信号:hvigor 只为宿主模块生成
+  // BuildProfile,在 HAR 里 import 'BuildProfile' 无法解析。)
+  setDebug(enabled: boolean): void {
+    this.isDebug = enabled;
+  }
+
+  private tagOf(args: string[]): string {
+    return args.length > 0 ? args[0] : '';
+  }
+
+  private messageOf(args: string[]): string {
+    return args.length > 1 ? args.slice(1).join(' ') : '';
+  }
+
+  debug(...args: string[]): void {
+    if (this.isDebug) {
+      hilog.debug(
+        this.domain,
+        this.prefix,
+        this.format,
+        this.tagOf(args),
+        this.messageOf(args),
+      );
+    }
+  }
+
+  info(...args: string[]): void {
+    hilog.info(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
+  }
+
+  warn(...args: string[]): void {
+    hilog.warn(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
+  }
+
+  error(...args: string[]): void {
+    hilog.error(
+      this.domain,
+      this.prefix,
+      this.format,
+      this.tagOf(args),
+      this.messageOf(args),
+    );
+  }
+}
+
+export default new Logger('pakta', 0xff00, false);

package/harmony/pakta/src/main/ets/MonotonicClock.ts

@@ -0,0 +1,18 @@
+/**
+ * [INPUT]: 依赖 @kit.BasicServicesKit 的 systemDateTime ACTIVE uptime
+ * [OUTPUT]: 对外提供 monotonicNowMs，返回不受墙钟校准和深睡影响的单调毫秒时间
+ * [POS]: Harmony 截止时间基础设施，与 iOS systemUptime/Android monotonic clock 保持语义同构
+ */
+import { systemDateTime } from '@kit.BasicServicesKit';
+
+// Absolute deadlines must not use Date.now(): automatic time synchronization
+// can move the wall clock while the cold-start rescue round is running.
+//
+// TimeType.ACTIVE (not STARTUP) is the semantic match for the other two
+// platforms: iOS NSProcessInfo.systemUptime and Android System.nanoTime both
+// stop during deep sleep, so a device that sleeps mid-download resumes with
+// its budget intact. STARTUP keeps counting through sleep and would abort a
+// rescue that the same network completes on iOS/Android.
+export function monotonicNowMs(): number {
+  return systemDateTime.getUptime(systemDateTime.TimeType.ACTIVE);
+}