xuqmGroup/XuqmGroup-RNSDK
0
0
派生 0
代码 工单 合并请求 版本发布 百科 动态

比较提交

基准分支: xuqmGroup:daa96302dd1f1eb8a1d3bc16cd24d1539e5a9175
分支列表 标签列表
xuqmGroup:main
xuqmGroup:0.2.2
..
比较: xuqmGroup:a2d3a27d80418632576b92341c4723147348fed9
分支列表 标签列表
xuqmGroup:main
xuqmGroup:0.2.2

没有共同的提交。daa96302dd1f1eb8a1d3bc16cd24d1539e5a9175 和 a2d3a27d80418632576b92341c4723147348fed9 的历史完全不同。
daa96302dd ... a2d3a27d80

共有 141 个文件被更改，包括 2836 次插入 和 7890 次删除
显示统计 展开所有文件 折叠所有文件

1
.gitignore vendored
查看文件

@ -7,7 +7,6 @@ target/
build/ build/
.gradle/ .gradle/
.native-gradle/ .native-gradle/
.xuqm-cache/
*.iml *.iml
.idea/ .idea/
*.log *.log

47
README.md
查看文件

@ -4,14 +4,14 @@ XuqmGroup 通用 React Native SDK 工作区。`@xuqm/rn-common` 是唯一基础
## 包结构 ## 包结构
| 包 | 用途 | 可独立使用 | | 包 | 用途 | 可独立使用 |
| --------------------- | ------------------------------------------------------ | ---------------------- | | --- | --- | --- |
| `@xuqm/rn-common` | 可选 SDK 上下文、网络、文件、时间、加密、设备与通用 UI | 是，且无需初始化或登录 | | `@xuqm/rn-common` | 可选 SDK 上下文、网络、文件、时间、加密、设备与通用 UI | 是，且无需初始化或登录 |
| `@xuqm/rn-update` | App 更新、RN 插件注册、下载、校验与运行 | 否，依赖 common | | `@xuqm/rn-update` | App 更新、RN 插件注册、下载、校验与运行 | 否，依赖 common |
| `@xuqm/rn-xwebview` | WebView、JSBridge、权限与下载 | 否，依赖 common | | `@xuqm/rn-xwebview` | WebView、JSBridge、权限与下载 | 否，依赖 common |
| `@xuqm/rn-bugcollect` | 错误、事件、漏斗和批量上报 | 否，依赖 common | | `@xuqm/rn-bugcollect` | 错误、事件、漏斗和批量上报 | 否，依赖 common |
| `@xuqm/rn-im` | IM 连接、消息和本地数据 | 否，依赖 common | | `@xuqm/rn-im` | IM 连接、消息和本地数据 | 否，依赖 common |
| `@xuqm/rn-push` | 多厂商原生推送桥接 | 否，依赖 common | | `@xuqm/rn-push` | 多厂商原生推送桥接 | 否，依赖 common |
根包 `@xuqm/rn-sdk` 只用于仓库内聚合开发，不对外发布。应用应按需安装具体包，避免引入未使用的原生能力。 根包 `@xuqm/rn-sdk` 只用于仓库内聚合开发，不对外发布。应用应按需安装具体包，避免引入未使用的原生能力。
@ -43,34 +43,37 @@ pnpm add @xuqm/rn-update @xuqm/rn-xwebview @xuqm/rn-bugcollect
## 扩展包一次初始化、一次登录 ## 扩展包一次初始化、一次登录
把平台生成的 `config.xuqmconfig` 放在 `src/assets/config/`，然后只包装一次 Metro 配置。使用 update 插件化时采用 update 组合器（它已包含 common 自动初始化）： 把平台生成的 `config.xuqmconfig` 放在 `src/assets/config/`，然后只包装一次 Metro 配置：
```js ```js
const { getDefaultConfig } = require('@react-native/metro-config') const {getDefaultConfig} = require('@react-native/metro-config');
const { withXuqmModuleConfig } = require('@xuqm/rn-update/metro') const {withXuqmConfig} = require('@xuqm/rn-common/metro');
module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname)) module.exports = withXuqmConfig(getDefaultConfig(__dirname));
``` ```
不使用 update 时仍调用 `@xuqm/rn-common/metro` 的 `withXuqmConfig()`。两种组合器都会把初始化模块注册为 Metro pre-main module，避免 `inlineRequires` 延迟扩展包加载。应用登录成功后只更新一次公共会话： `withXuqmConfig()` 会把初始化模块注册为 Metro pre-main module，避免 `inlineRequires` 延迟扩展包加载。应用登录成功后只更新一次公共会话：
```ts ```ts
import { XuqmSDK } from '@xuqm/rn-common' import {XuqmSDK} from '@xuqm/rn-common';
await XuqmSDK.awaitInitialization() await XuqmSDK.awaitInitialization();
await XuqmSDK.login({ await XuqmSDK.login({
userId: 'user-id', userId: 'user-id',
accessToken: 'http-access-token', accessToken: 'http-access-token',
userSig: 'optional-im-credential', userSig: 'optional-im-credential',
}) });
await XuqmSDK.logout() await XuqmSDK.logout();
``` ```
扩展包通过 `@xuqm/rn-common/internal` 接收同一次会话变化。宿主业务代码不得导入该内部子路径，也不得逐级传递公共 token 或用户状态。 扩展包通过 `@xuqm/rn-common/internal` 接收同一次会话变化。宿主业务代码不得导入该内部子路径，也不得逐级传递公共 token 或用户状态。
平台签发配置与 Metro 自动初始化是扩展 SDK 的唯一初始化入口；不提供手动 无法使用配置文件自动初始化时，才调用一次：
`initialize`。common-only 宿主不放配置，也不初始化。
```ts
await XuqmSDK.initialize({appKey: 'app-key'});
```
## 开发与验证 ## 开发与验证
@ -81,7 +84,11 @@ corepack pnpm install
corepack pnpm validate corepack pnpm validate
``` ```
`validate` 会执行全部包的 TypeScript 校验和测试。开发 alpha 及正式包都只能由 Jenkins 发布到 Nexus，开发机不执行 npm publish。 `validate` 会执行全部包的 TypeScript 校验和测试。开发版本发布到 Nexus hosted 仓库：
```bash
corepack pnpm --filter @xuqm/rn-common publish --tag next --no-git-checks
```
集成 update 的宿主由 `xuqm-rn start` 和 `xuqm-rn run android` 统一代理 Metro 与 Android Debug 启动；宿主只保留简短的 `start/android` package script。 集成 update 的宿主由 `xuqm-rn start` 和 `xuqm-rn run android` 统一代理 Metro 与 Android Debug 启动；宿主只保留简短的 `start/android` package script。

284
docs/IMPLEMENTATION_HANDOFF.md
查看文件

@ -1,118 +1,9 @@
# RN SDK 重构实施接管文档 # RN SDK 重构实施接管文档
> 状态更新时间：2026-07-27 > 状态更新时间：2026-07-18
> 当前实施范围：`@xuqm/rn-common`、`@xuqm/rn-bugcollect`、`@xuqm/rn-update`、`@xuqm/rn-xwebview` > 当前实施范围：`@xuqm/rn-common`、`@xuqm/rn-bugcollect`、`@xuqm/rn-update`、`@xuqm/rn-xwebview`
> 发布约束：所有 XuqmGroup npm/Maven 制品和服务部署只能通过 `https://jenkins.xuqinmin.com/` 的 Jenkins 完成。 > 发布约束：所有 XuqmGroup npm/Maven 制品和服务部署只能通过 `https://jenkins.xuqinmin.com/` 的 Jenkins 完成。
## 2026-07-26 / 当前实施状态
- common 已增加 `idle / initializing / ready / degraded / failed` 初始化状态、
`XuqmError` 结构化错误、七天最后成功配置缓存，以及最多三次的指数退避抖动。
平台暂不可用时优先进入 degraded；没有缓存时扩展返回 `XUQM_NOT_READY`，不向宿主
制造未处理异常。最后成功配置使用 AES-GCM 完整性加密，密钥由签发配置和
app/package/environment 上下文派生且不写入缓存；这里是应用沙箱内防明文与防篡改
边界，不宣称具备 Android Keystore/iOS Keychain 的硬件保密性。
- 扩展 SDK 的唯一正式初始化入口是平台签发 `.xuqmconfig` 与 Metro 自动初始化；
`XuqmSDK.initialize(options)` 及公开 `XuqmInitOptions` 已删除，不保留兼容壳。
common-only 不初始化。未使用 `withXuqmConfig` 时，公开
`@xuqm/rn-common/auto-init-config` 空实现保证 Metro 能完成静态解析；真实 Metro
fixture 已覆盖无配置构建。
- 唯一隐私入口为 `XuqmSDK.setPrivacyConsent(boolean)`。BugCollect 只有在平台启用、
用户已同意且非 Debug 时自动注册采集；Debug 单次验证使用
`BugCollect.sendTestErrorAndFlush()`，宿主不再手动 `startCapture()`。
- BugCollect 收到 `BUGCOLLECT_DISABLED` 会立即停用并清除队列；上传请求不进入自身
HTTP 拦截链。部署中的 `{code:403,status:'1',message:'BUGCOLLECT_DISABLED'}` 同样
识别。持久化事件最多 500 条、保留七天，复用 common AES-GCM 沙箱加密，失败不会
先删除队列。冷启动首次获得“平台关闭”配置时，即使尚未创建内存 LogQueue，也会
直接删除该 appKey 的遗留加密队列；Debug 单次测试上传同样要求隐私同意。
- update 从原生 manifest/state 提供当前 Bundle 精确身份；BugCollect 仅在 stack 唯一
命中模块时附带 `buildId/moduleId/moduleVersion/bundleHash`。无法唯一归属时标记
`symbolicationStatus=unavailable`，不伪造 latest 身份。
- Update 使用平台动态 `updateRequiresLogin`。需要登录时未登录正常跳过；登录后自动
补检一次并通过 `onAutomaticCheck` 交给宿主决定 UI。账号变化会取消旧下载授权和
灰度缓存；后台补检失败不影响宿主登录。服务端权威字段
`allowAnonymousUpdateCheck` 缺失时安全默认禁止匿名检查。
- Update 服务开关统一解析 `features.update`（兼容平铺 `updateEnabled`），缺失安全
默认关闭并进入最后成功配置缓存。所有显式检查/下载/安装入口在网络和原生调用前
抛出 `UPDATE_DISABLED`；自动启动路径正常跳过。
- 插件候选已实现 Ed25519 不可变 manifest 验签：common 集中维护 canonical JSON、
可信 keyId 与 Hermes 运行时验签，Metro 构建期复用同一规则和密钥集合。候选在计划
前与安装前双重验签，Android stager 进一步绑定 buildId、bundleFormat 和
bundleSha256；响应 ZIP `sha256` 以 `archiveSha256` 纳入同一签名，下载后仍使用
同值校验归档。未知 keyId、签名错误和字段篡改测试均已覆盖。
common 加密、Ed25519 与 secureCache 复用 common/security 唯一纯 JS
Base64/Base64URL codec，不依赖 Hermes 全局 `atob/btoa`；非法字母表、长度、填充和
尾随位直接拒绝。canonical
JSON 对函数、symbol、非有限数、非普通对象、数组空位/undefined 确定性失败，避免
Node、Hermes 与服务端实现各自容错产生不同签名正文。
Server 的 `update-service/src/test/resources/rn-release-signature-vector.json` 是
唯一规范源。RN 测试只读明确标记 GENERATED/DO NOT EDIT 的仓内生成副本，保证独立
Git/Jenkins checkout 可运行；`scripts/sync-server-signature-vector.mjs
--check|--write` 负责跨仓字节级同步。相邻 Server 缺失时常规单仓 validate 跳过跨仓
比较，发布前必须提供 Server checkout 并执行 `--check`。测试会逐字节比较 canonical
UTF-8 正文，并以同一 keyId、原始公钥和 Base64URL 签名完成验签。
- release-set 检查已强制携带 appVersion、nativeApiLevel、nativeBaselineId；缺少
baseline 在发请求前失败。发布 Token 只读取 Jenkins 注入的 XUQM_API_TOKEN，
`release.apiToken` 配置会被构建校验拒绝。
- `xuqm.modules.json` 使用 `packageName` 保存 Android applicationId、使用
`iosBundleId` 保存 iOS Bundle Identifier；相应字段仅在目标平台
build/package/release 时必填。唯一 `resolveHostPackageId(config, platform)` 被
构建、在线配置验证、ZIP 期望身份和发布上传共同复用。wire 仍使用
`packageName`，但不会再把 Android 身份写入 iOS ZIP。
- 插件 ZIP v1 协议限制已与 Server 对齐：归档 50 MiB、单 entry 100 MiB、总解压
100 MiB、最多 4096 entries。Android stager 不再保留 5000 上限，4096/4097 和单
entry 100 MiB 边界已有原生单测；CLI `zipSync` 不生成目录 entry，Server 与 stager
均明确拒绝目录 entry。
- Debug 的 `XuqmRuntime.start()` 不做远程整包或插件检查；开发页仍可显式调用公开
check/install API 做一次性验证。
- 插件构建清单已从 `xuqm.config.json` 更名为 `xuqm.modules.json`；租户平台签发的
`.xuqmconfig` 仍是唯一初始化源。Metro 使用 `src/assets/config/` 内唯一文件，
保留平台下载文件名；零个保持 common-only，多个构建失败。Android/iOS 生成目录
中的构建副本才固定命名为 `config.xuqmconfig`。
- Metro 只接受严格 `XUQM-CONFIG-V2`：使用内置 `keyId` 公钥先做 Ed25519 验签，再
解密并校验 canonical JSON、Schema、UUID、revision 和有效期。V1、未知 keyId 与
签名失败在构建期阻断。当前内置开发公钥为 `xuqm-config-dev-2026-07`，私钥未入仓。
- Release 每个模块始终生成独立 Source Map，删除 `sourcesContent` 并清理绝对路径。
`--bugcollect=disabled` 只归档不上传；启用时按完整 Bundle 身份上传，失败阻断发布。
上传契约固定为 `POST /bugcollect/v1/artifacts/upload` 且
`artifactType=RN_SOURCEMAP`；旧 Metro serializer 上传器已删除。发布登记和
Source Map 上传的 `buildId/moduleId/moduleVersion/bundleHash` 均从待上传 ZIP 的
`rn-manifest.json` 和真实 Bundle 校验后取得，禁止根据环境变量二次推导身份；
artifact 上传与插件发布使用同一 Jenkins 发布 Bearer，匿名请求不会发出。
- 整包和插件发布前调用 `/api/sdk/build/config/validate`。服务不可达、配置过期、
revision 撤销或包名不匹配均阻断新 Release；已安装 App 运行时不查询吊销状态。
- 相同 versionName 的连续 Android Release 自动生成递增 versionCode 和独立 buildId；
- 2026-07-27 本地全量 `pnpm validate` 通过：六个 workspace TypeScript、common 42、
bugcollect 11、xwebview 7、IM 3、update CLI/Metro 28 与 update domain 18 项测试
全部通过；update 发布包内容校验为 51 个文件。common npm dry-run 未包含测试目录及
生成签名向量。Server 相邻仓库存在时签名向量逐字节检查通过，模拟 Server checkout
缺失的单仓 CI 也按契约独立通过。
同一工作区通过 `.xuqm-cache/release-build.json` 保证单调递增，跨工作区 CI 通过
`XUQM_VERSION_CODE` 和 `XUQM_BUILD_ID` 注入全局唯一流水线身份。
- Gradle 内嵌任务把 `buildId` 与 `bugCollectMode` 声明为显式 `@Input` 并传入 embed
子进程；测试验证 APK 内嵌 manifest 和模块 ZIP 使用同一 Release identity。
`package` 与 `publish` 共用唯一 `--bugcollect` 参数解析器，等号和空格写法一致。
- Android 相同模块版本使用 SHA-256 识别新版 APK 内容；真正更高且兼容 native
baseline 的远程插件继续保留。新 release 允许两次进程启动握手，失败 releaseId
本机隔离，服务端内容未变化前不重复安装。
- 原生最终恢复入口只删除 SDK 私有 `files/rn-bundles`，并递增 reset generation；
common/app 初始化后仅清除 `xuqm_update_*` 状态并确认该 generation，重试不会误清
宿主、BugCollect 或签名 SDK 数据。
- 已执行 `pnpm validate`：全部包类型检查、common 42 项、bugcollect 11 项、update
CLI 28 项、update 领域 18 项、xwebview 7 项和 IM 3 项测试均通过；update 包内容
校验通过，发布包为 51 个文件；Prettier 和 `git diff --check` 通过。
独立 `native-test` 的系统 Gradle 仍在任务配置前因本机
`libnative-platform.dylib` 无法加载；改用 App4 Gradle 9.3.1 wrapper 后，
`:xuqm_rn-update:testDebugUnitTest --tests
com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功。
尚未执行完整宿主 Android 构建、设备运行、开发环境接口和真实 Source Map 上传；
这些结果不得从当前门禁推断。
- License 离线激活 SDK 已审计：RNSDK 不存在对应包、API、依赖、脚本、文档或空目录；
npm 的 `license: UNLICENSED` 元数据和 RN 插件事务 `activation` 不属于离线授权。
- 配置中的 `signingKey` 明确是客户端可提取的请求完整性/缓存派生材料，不是 License、
用户授权或服务端秘密；敏感 API 仍依赖登录 `accessToken`，构建制品上传依赖独立
Jenkins Bearer，并由服务端执行授权。
## 1. 本轮目标 ## 1. 本轮目标
1. `rn-common` 可以完全独立使用公共工具，不要求初始化或登录。 1. `rn-common` 可以完全独立使用公共工具，不要求初始化或登录。
@ -122,28 +13,6 @@ com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功
5. update SDK 统一承担插件 manifest、兼容性、原子激活、启动确认、崩溃回滚和内嵌恢复；宿主不得再实现平行版本管理器。 5. update SDK 统一承担插件 manifest、兼容性、原子激活、启动确认、崩溃回滚和内嵌恢复；宿主不得再实现平行版本管理器。
6. Android 整包更新必须具备应用内下载、SHA-256 校验、安装权限处理、进度、取消、重试和确定性错误码。 6. Android 整包更新必须具备应用内下载、SHA-256 校验、安装权限处理、进度、取消、重试和确定性错误码。
7. 宿主通过最少配置完成插件创建、开发运行、打包、随 APK 内嵌、发布和回滚。 7. 宿主通过最少配置完成插件创建、开发运行、打包、随 APK 内嵌、发布和回滚。
8. XWebView 收敛为 `XWebViewHost + openWebView` 的 SDK 自管页面栈；宿主不再注册路由或传 navigate 回调。
## 0. 2026-07-26 / XWebView 1.0 实施状态
- 已取得用户实施授权，目标为 `@xuqm/rn-xwebview@1.0.0`。
- 旧 `openXWebView(navigate, config)`、common 内全局 `_config/_controller` 和公开
`XWebViewScreen` 已删除，不保留转发兼容层；迁移规则已写入包 README。
- 新公开入口固定为根部一次挂载 `XWebViewHost`、业务直接调用
`openWebView(config)`，并返回页面级句柄和 `closed` Promise。
- 配置改为 `source/navigationBar/statusBar/behavior/permissions/downloads/bridge`
分组强类型结构；URL 与 HTML 互斥。
- 页面栈、Host 等待/卸载、页面级动态导航、系统返回、外链、下载、权限和 Bridge
异常已收口到 xwebview；common 中错误归属的 WebView 状态与业务 Bridge 已删除。
- H5 媒体权限由页面白名单、可选宿主决策和 Android 系统权限三层控制；SDK 不向
Manifest 注入摄像头或麦克风权限。
- 下载自动复用 URI 首屏鉴权 headers；Bridge 原始 payload 不写日志。
- `react-native-svg` 已收敛为 peer；宿主必须直接声明这一原生依赖以参与 autolink，
禁止由 xwebview 私自安装第二份。App4 运行验收曾据此捕获并修复
`RNSVGSvgViewAndroid` 未注册问题。
- xwebview 类型检查和 7 项独立测试已通过。App4 在 Android 36.1
`emulator-5554` 通过“移动报销”真实 H5 页面验证：页面打开、SDK 初始化、
`userInfo`、右上角菜单和关闭返回均正常，窗口日志无 Java/React/Fabric FATAL。
## 2. 已冻结的设计约束 ## 2. 已冻结的设计约束
@ -170,10 +39,10 @@ com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功
- 本地已使用 JDK 21 + Gradle 9.3.1 编译通过；RN Bridge 明确输出 Java 17 字节码，不再隐式回落到 Java 8。 - 本地已使用 JDK 21 + Gradle 9.3.1 编译通过；RN Bridge 明确输出 Java 17 字节码，不再隐式回落到 Java 8。
- RN 包不再内置第二份 AGP buildscript；宿主负责插件版本，独立夹具使用与 Android SDK 一致的 AGP 9.1.0。 - RN 包不再内置第二份 AGP buildscript；宿主负责插件版本，独立夹具使用与 Android SDK 一致的 AGP 9.1.0。
- `pnpm validate`：通过。 - `pnpm validate`：通过。
- common：20 个测试通过。 - common：16 个测试通过。
- bugcollect：5 个独立测试通过。 - bugcollect：4 个独立测试通过。
- xwebview：7 个独立测试通过。 - xwebview：4 个独立测试通过。
- update CLI/Metro：11 个测试通过；release-set：6 个测试通过。 - update CLI：9 个测试通过；release-set：6 个测试通过。
- IM 现有测试：3 个通过；IM 不在本轮开发范围。 - IM 现有测试：3 个通过；IM 不在本轮开发范围。
- 所有 workspace TypeScript typecheck：通过。 - 所有 workspace TypeScript typecheck：通过。
@ -184,17 +53,15 @@ com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功
- common-only 宿主缺少配置文件时不会触发自动初始化，已有测试覆盖。 - common-only 宿主缺少配置文件时不会触发自动初始化，已有测试覆盖。
- 配置文件自动初始化遇到临时网络失败时会清理失败 Promise；扩展下一次等待初始化时使用同一加密配置重试，不要求宿主重新传 appKey/URL，也不会产生未处理 Promise 或重复错误日志。 - 配置文件自动初始化遇到临时网络失败时会清理失败 Promise；扩展下一次等待初始化时使用同一加密配置重试，不要求宿主重新传 appKey/URL，也不会产生未处理 Promise 或重复错误日志。
- bugcollect、update、xwebview 通过 `@xuqm/rn-common/internal` 触发一次自动初始化入口。 - bugcollect、update、xwebview 通过 `@xuqm/rn-common/internal` 触发一次自动初始化入口。
- update CLI 已能从 schema v3 `xuqm.modules.json` 构建 startup/common/app/buz，生成携带 SemVer 兼容范围和原生 API 等级的内嵌 manifest。 - update CLI 已能从 schema v3 `xuqm.config.json` 构建 startup/common/app/buz，生成携带 SemVer 兼容范围和原生 API 等级的内嵌 manifest。
- update 的 `withXuqmModuleConfig()` 是多 Bundle 模块编号的唯一实现：日常 Metro 不变，CLI 构建时自动先生成 startup/common 共享模块表，并按配置序号为每个 app/buz 分配独立区间；宿主不再维护多份 Metro 配置或业务名硬编码 offset。 - Android bundle 引擎不在 `xuqm.config.json` 重复声明：CLI 直接读取宿主 `android/gradle.properties` 的 `hermesEnabled`。启用时所有插件统一编译为 Hermes bytecode、组合 source map，并在 manifest/上传表单记录 `bundleFormat`。
- Android bundle 引擎不在 `xuqm.modules.json` 重复声明：CLI 直接读取宿主 `android/gradle.properties` 的 `hermesEnabled`。启用时所有插件统一编译为 Hermes bytecode、组合 source map，并在 manifest/上传表单记录 `bundleFormat`。
- common 的唯一 XWebView 契约新增实时导航状态；全屏与内嵌容器统一提供 `canGoBack`、`canGoForward`、当前标题和 URL，并支持宿主配置回调。Bridge 不再重复声明第二份 controller 类型。 - common 的唯一 XWebView 契约新增实时导航状态；全屏与内嵌容器统一提供 `canGoBack`、`canGoForward`、当前标题和 URL，并支持宿主配置回调。Bridge 不再重复声明第二份 controller 类型。
- RN update 已有 release-set 纯领域规划器；Android 原生模块已改为整组 staging/激活/确认/回滚，并从 APK assets 恢复内嵌基线。 - RN update 已有 release-set 纯领域规划器；Android 原生模块已改为整组 staging/激活/确认/回滚，并从 APK assets 恢复内嵌基线。
### 3.3 已确认缺口 ### 3.3 已确认缺口
- RN update 已编码 `XuqmAppUpdateModule`，只桥接 XuqmGroup Android `sdk-update:2.0.0-SNAPSHOT`；Android Snapshot、Bridge 编译和 App4 完整 debug 构建已通过，模拟器安装事务仍待验证。 - RN update 已编码 `XuqmAppUpdateModule`，只桥接 XuqmGroup Android `sdk-update:2.0.0-SNAPSHOT`；Android Snapshot、Bridge 编译和 App4 完整 debug 构建已通过，模拟器安装事务仍待验证。
- release-set 已统一使用 SHA-256 和 Ed25519 签名 manifest；服务端仍需按同一 - release-set 已统一使用 SHA-256，但签名 manifest 尚待实现。
canonical 字段契约签发 `keyId/signature` 并完成联调。
- 原生 state 已成为 Bundle 版本与事务状态唯一真相；App 更新提示缓存仍可使用 AsyncStorage，但不保存 Bundle 版本。 - 原生 state 已成为 Bundle 版本与事务状态唯一真相；App 更新提示缓存仍可使用 AsyncStorage，但不保存 Bundle 版本。
- 客户端已改为 `/api/v1/rn/release-set/check` 单次请求目标入口依赖闭包；租户平台服务端接口尚待同步实现。 - 客户端已改为 `/api/v1/rn/release-set/check` 单次请求目标入口依赖闭包；租户平台服务端接口尚待同步实现。
- `nativeBaselineId` 已自动计算并进入内嵌 manifest/插件上传：覆盖 Android 原生源码、Gradle 配置、RN 与含原生代码的 npm 依赖，普通业务 JS 不影响指纹；Jenkins/服务端登记校验尚待实现。 - `nativeBaselineId` 已自动计算并进入内嵌 manifest/插件上传：覆盖 Android 原生源码、Gradle 配置、RN 与含原生代码的 npm 依赖，普通业务 JS 不影响指纹；Jenkins/服务端登记校验尚待实现。
@ -205,17 +72,17 @@ com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功
## 4. 实施进度 ## 4. 实施进度
| 工作项 | 状态 | 说明 | | 工作项 | 状态 | 说明 |
| ----------------------------- | ------ | ----------------------------------------------------- | | ----------------------------- | -------- | ------------------------------------------------------ |
| 基线审计与门禁 | 完成 | 2026-07-17 本地 validate 全通过 | | 基线审计与门禁 | 完成 | 2026-07-17 本地 validate 全通过 |
| 实时接管文档 | 进行中 | 本文件为唯一实施状态入口 | | 实时接管文档 | 进行中 | 本文件为唯一实施状态入口 |
| common 公共上下文收敛 | 完成 | 公共基础、共享生命周期与安全 API 诊断 19 测试 | | common 公共上下文收敛 | 完成 | 公共基础与共享生命周期 16 测试 |
| bugcollect 依赖 common 与测试 | 完成 | 自动初始化、SHA、版本、策略与 HTTP 脱敏已统一，5 测试 | | bugcollect 依赖 common 与测试 | 完成 | 自动初始化、SHA、版本与策略已统一，4 测试 |
| xwebview 1.0 Host/权限/下载 | 完成 | 页面栈、分组配置、7 项测试及 App4 Android 运行通过 | | xwebview 文件/权限能力与测试 | 完成 | 文件下沉 common，H5 摄像头/麦克风统一授权，4 测试通过 |
| update release set 与原生事务 | 进行中 | Android Snapshot、Bridge、App4 构建通过；待事务 E2E | | update release set 与原生事务 | 进行中 | Android Snapshot、Bridge、App4 构建通过；待事务 E2E |
| package 内容校验 | 完成 | update 包 42 个发布文件已校验 | | package 内容校验 | 待实施 | 四包完成后执行 |
| Jenkins alpha 发布 | 完成 | `#59/#60` 已发布 common、xwebview、update | | Jenkins alpha 发布 | 完成 | `#59/#60` 已发布 common、xwebview、update |
| App4 接入 | 完成 | V5 Host、8 模块、Debug APK 与真实 H5 Android 链路通过 | | App4 接入 | 完成构建 | 精确 alpha 已接入，六 Hermes 插件与 debug APK 构建通过 |
## 5. 下一步操作 ## 5. 下一步操作
@ -223,7 +90,7 @@ com.xuqm.update.XuqmPluginPackageStagerTest` 共 25 tasks 构建并测试成功
2. 在 Android 宿主补充 release-set 安装、冷启动确认和崩溃回滚仪器测试。 2. 在 Android 宿主补充 release-set 安装、冷启动确认和崩溃回滚仪器测试。
3. 收敛 Jenkins 四包依赖发布顺序和 package 内容检查。 3. 收敛 Jenkins 四包依赖发布顺序和 package 内容检查。
4. 后续租户平台实现 `/api/v1/rn/release-set/check`，服务端只返回目标入口与 common 的兼容闭包。 4. 后续租户平台实现 `/api/v1/rn/release-set/check`，服务端只返回目标入口与 common 的兼容闭包。
5. App4 当前使用相邻源码联调本轮未发布变更；验证完成后必须由 Jenkins 发布新 alpha，再恢复 Nexus 精确版本。禁止手改 `node_modules` 或本地发布正式制品。 5. App4 保持使用 Jenkins 精确版本，禁止链接 SDK 源码、手改 `node_modules` 或本地发布正式制品。
## 6. 常用验证命令 ## 6. 常用验证命令
@ -246,31 +113,6 @@ pnpm --dir packages/update test
- 新增测试使用带手机号、sessionId、userId、token 的伪响应，强制验证 - 新增测试使用带手机号、sessionId、userId、token 的伪响应，强制验证
序列化后的诊断结果不包含这些敏感值。 序列化后的诊断结果不包含这些敏感值。
### 2026-07-19 / common Bundle 模块过滤修复
- App4 模拟器首次加载内嵌插件时出现 `Requiring unknown module "726"`。定位结果不是宿主页面问题，而是 Metro 的模块编号工厂把本轮首次发现的 common 模块写入共享缓存后，过滤器又读取同一份可变缓存并把该模块从当前 Bundle 删除。
- `withXuqmModuleConfig()` 现在只使用构建开始前的共享模块快照做去重：common 本轮新分配的模块保留在 common Bundle；后续 app/buz 仍过滤 startup/common 已有模块。宿主不增加补丁、模块白名单或第二套编号逻辑。
- Metro 测试新增“common 本轮新模块必须保留”断言；格式、全部 workspace 类型检查及 48 项测试通过。
- 根工作区脚本统一通过 Corepack 调用锁定的 pnpm，校验不再依赖开发机预装全局 pnpm。
- 当前下一步：刷新 App4 的 `file:` SDK 联调副本，重建并安装 debug APK；确认六个 Hermes Bundle 可连续加载后继续双模拟器像素校准。修复尚未通过 Jenkins 发布，不得把相邻源码依赖作为正式发版基线。
### 2026-07-19 / Android 插件图片资源恢复
- App4 common/app 连续加载成功后，登录 logo 和单选框仍为空。根因是 Metro 生成的 `drawable-*` 仅位于 `assets/rn-bundles`，同时原生恢复只复制 `active.bundle`；动态 `loadBundle(file)` 会相对当前 Bundle 文件目录解析图片。
- Gradle 生成任务现在公开 assets 与 res 两个独立 `DirectoryProperty`：Bundle/manifest 进入 APK assets，drawable 同时进入 aapt2 资源表，符合 AGP 生成源 API 的类型约束。
- `XuqmBundleModule` 恢复内嵌 Bundle 时同步读取该模块 manifest 的 `assetFiles`，校验路径只允许标准 `drawable-*/resource_name.ext`，再原子写入同一模块目录；图片恢复不由宿主页面逐个处理。
- App4 arm64 debug 已真实编译该 Java 实现并安装验证；app 模块私有目录共恢复 289 个 Bundle/状态/资源文件，登录 logo 与单选框显示正常。
- 当前只取得内嵌基线恢复证据；远程 release set 的二进制 Bundle 与资源下载、校验、事务激活仍需作为同一组实现和验证，不能把本次结果扩大为 OTA 资源已完成。
- 全局 API 错误回调不再交付带 Axios cause 的 `RequestError`，只交付不可逆的安全诊断报告；宿主无法误把请求体、headers 或响应上传到采集平台。
- bugcollect 的全局 fetch 拦截器只上报 method、相对 path 和 HTTP status；完整 host、query、请求体、headers 及原始网络异常对象全部丢弃，测试覆盖敏感查询参数和鉴权头。
### 2026-07-18 / 多 Bundle Metro 能力下沉
- 新增公开入口 `@xuqm/rn-update/metro`，`withXuqmModuleConfig()` 内部复用 common 的 `withXuqmConfig()`，宿主只保留一份 Metro 配置。
- `xuqm-rn build/embed/publish` 为每个模块注入 id、type、配置序号和共享缓存位置；模块区间不再依赖 `szyx/miniapp` 等业务目录名称。
- 独立构建 app/buz 时 CLI 自动先构建 startup/common 依赖以重建共享模块表，但仍只发布用户选择的模块，适用于全新 Jenkins 工作区。
- 测试覆盖 0 号模块存在性、startup/common 去重、app/buz 唯一区间，以及单独构建 buz 的依赖顺序；update CLI/Metro 11 项、release-set 6 项和 42 文件包内容校验通过。
### 2026-07-18 / Jenkins #58—#60 与 App4 精确版本接入 ### 2026-07-18 / Jenkins #58—#60 与 App4 精确版本接入
- `sdk-rn-publish #58` 被 Windows Hermes 测试正确阻断：测试曾把文本写成 `hermesc.exe`，Windows `spawnSync` 无法执行；该构建未发布任何包。 - `sdk-rn-publish #58` 被 Windows Hermes 测试正确阻断：测试曾把文本写成 `hermesc.exe`，Windows `spawnSync` 无法执行；该构建未发布任何包。
@ -348,7 +190,7 @@ pnpm --dir packages/update test
- 更新检查改为按入口依赖闭包：启动时整包优先，其后 app+common；buz 进入前只检查当前 buz+common。 - 更新检查改为按入口依赖闭包：启动时整包优先，其后 app+common；buz 进入前只检查当前 buz+common。
- SDK 不决定宿主 UI：整包与插件均提供独立检查/安装 API；App4 进入 buz 使用 `checkAndInstallPlugin`，需要弹窗的宿主使用 `checkPluginRelease` 后再调用 `installPluginRelease`。 - SDK 不决定宿主 UI：整包与插件均提供独立检查/安装 API；App4 进入 buz 使用 `checkAndInstallPlugin`，需要弹窗的宿主使用 `checkPluginRelease` 后再调用 `installPluginRelease`。
- release-set 记录检查时的全部本地基线版本；弹窗停留期间状态变化会触发 `StaleReleaseSetError`，不会安装过期计划。 - release-set 记录检查时的全部本地基线版本；弹窗停留期间状态变化会触发 `StaleReleaseSetError`，不会安装过期计划。
- `xuqm.modules.json` 统一使用 schema v3：`commonVersionRange` + `minNativeApiLevel`，删除 `minCommonVersion`/`minNativeVersion` 双重语义。 - `xuqm.config.json` 统一升级到 schema v3：`commonVersionRange` + `minNativeApiLevel`，删除 `minCommonVersion`/`minNativeVersion` 双重语义。
- 验证：update typecheck、CLI 6 测试、release-set 6 测试通过；Android 原生代码尚待宿主工程编译验证。 - 验证：update typecheck、CLI 6 测试、release-set 6 测试通过；Android 原生代码尚待宿主工程编译验证。
### 2026-07-17 / Android 整包安装桥接 ### 2026-07-17 / Android 整包安装桥接
@ -363,87 +205,3 @@ pnpm --dir packages/update test
- Jenkins Windows 节点直接访问外部 Android 仓库会出现无输出的长时间依赖等待；`native-test` 的 plugin management 已与 AndroidSDK 对齐，统一优先使用 Nexus `android` 聚合仓库，再回退官方仓库。 - Jenkins Windows 节点直接访问外部 Android 仓库会出现无输出的长时间依赖等待；`native-test` 的 plugin management 已与 AndroidSDK 对齐，统一优先使用 Nexus `android` 聚合仓库，再回退官方仓库。
- Windows CLI 测试路径统一使用 `fileURLToPath`，禁止把 `file:` URL 的 pathname 直接作为本机路径。 - Windows CLI 测试路径统一使用 `fileURLToPath`，禁止把 `file:` URL 的 pathname 直接作为本机路径。
- native baseline 现在按 Android/iOS 分别计算，并覆盖全部运行时依赖的实际安装版本、平台原生源码/资源、`src`/`assets` 内会随安装包打入的图片、字体和媒体文件；这些内容变化后必须先发布完整 App，不能只发布 JS 插件。 - native baseline 现在按 Android/iOS 分别计算，并覆盖全部运行时依赖的实际安装版本、平台原生源码/资源、`src`/`assets` 内会随安装包打入的图片、字体和媒体文件；这些内容变化后必须先发布完整 App，不能只发布 JS 插件。
### 2026-07-19 / 同版本内嵌基线覆盖修复
- App4 覆盖安装新 debug APK 后仍加载手机内旧 `active.bundle`。根因是 `ensureEmbeddedBundle()` 只判断文件存在，插件版本仍为 `1.0.0` 时无法识别整包内的代码已经变化。
- `xuqm-rn embed` 现在为每个模块记录实际 bundle 的 SHA-256；Android state 同步记录 `activeHash`。状态仍为 `embedded` 且摘要变化时，SDK 原子替换 bundle、清理该模块旧 drawable 目录并按 manifest 恢复新资源。
- 状态为 `active` 或事务中的远程插件不会被覆盖安装改写；线上更新仍只能经过 stage/activate/confirm/rollback。该分支避免以开发便利破坏生产事务边界。
- RN SDK 全量门禁通过。App4 重新编译 Java Bridge 与六模块共 450 tasks 成功；第一次不清 `rn-bundles` 覆盖安装把旧 state 自动写入新 manifest 摘要，第二次相同 APK 覆盖后 bundle mtime 未变化，证明变化替换和相同复用均生效。下一步为 Jenkins 发布新 alpha 后恢复 App4 精确 Nexus 版本。
### 2026-07-19 / 平台地址与更新检查超时收敛
- `XuqmConfig` 新增职责明确的 `platformUrl`；配置文件 `serverUrl/baseUrl` 只在解密入口归一为该字段。租户配置、整包和插件更新统一访问 `platformUrl`，远程 `apiUrl` 只表示业务扩展服务，禁止两者混用。
- common HTTP 增加唯一 30 秒默认超时，并将调用方 `AbortSignal` 与内部超时合并；定时器在成功、失败和取消后统一清理，不要求每个 SDK 复制 `Promise.race`。
- `checkPluginRelease()` 支持 `signal/timeoutMs`；`checkAndInstallPlugin()` 支持 `signal/checkTimeoutMs`，宿主可为“进入插件前检查”设置更短交互边界，同时保留纯检查、确认后安装和自动检查安装三种既有 API 语义。
- App4 使用 5 秒检查边界：平台暂时不可达且本地 Bundle 健康时继续进入本地插件，网络异常不被误报为 Bundle 崩溃；真实 `szyx/active.bundle` 已在 Android 模拟器加载成功。
- common 新增停滞请求超时测试，并扩展生命周期/初始化测试覆盖 `platformUrl` 与 `apiUrl` 分离；全量 `pnpm validate` 再次通过：六个 workspace 类型检查、common 20、bugcollect 5、xwebview 4、IM 3、update CLI/Metro 11 与 release-set 6 项测试全部无回归。
### 2026-07-20 / 启动壳轻量原生分包入口
- `@xuqm/rn-update` 新增公开子路径 `@xuqm/rn-update/native-bundle`，只导出原生 Bundle 状态与路径桥，不加载 AsyncStorage、HTTP、SemVer、整包更新或 release-set 编排。
- App4 startup 已改用 `NativeBundle.preparePendingRelease()` / `getLaunchPath()`；完整 `UpdateSDK` 仍只在 app 更新和插件激活阶段加载，不存在第二套状态实现。
- App4 的 startup Android Hermes bytecode 从此前约 2.2 MB 降至约 1.27 MB。该数据只证明启动入口依赖收敛；common/app 动态装载和模拟器交互首屏仍需独立计时，不能只用 startup 文件大小宣称启动性能完成。
- `packages/update/package.json` 的 exports、README 与 App4 实际调用已同步。该变更仍是 main 本地源码联调状态，未通过 Jenkins 发布新 alpha，外部项目不得提前写入一个尚不存在的 Nexus 版本号。
### 2026-07-20 / common 构建期配置解析与 XWebView 权限收口
- App4 冷启动日志证明 common 请求与 app 请求之间曾固定阻塞约 10.6 秒；直接读取原生 Bundle 仅约 1ms。根因是 common 自动初始化在 Hermes 主线程执行 120,000 次纯 JavaScript PBKDF2，而不是 Bundle IO 或 App 页面渲染。
- `withXuqmConfig()` 现在使用 Node `crypto` 在 Metro 构建期完成 PBKDF2、AES-256-GCM 解密和 Schema 校验，虚拟模块只导出解析后的只读配置。设备端自动初始化不再执行解密；临时网络失败重试复用同一份解析结果，不恢复第二套初始化入口。
- App4 重新生成六模块并安装后，common 请求到 app 请求的间隔由约 10.6 秒降至约 405ms；一次 Android 冷启动 `Displayed` 为 783ms。该结果是 API 34 ARM64 软件模拟器观测值，只作为本轮相对回归证据，不替代真机性能验收。
- XWebView 默认权限策略只接受摄像头和麦克风两类已知 WebView 资源，并逐项核对 Android 运行时授权；未知资源明确拒绝。单测覆盖摄像头、麦克风、混合资源、拒绝和未知资源场景。
- common 18 项 TypeScript 测试、2 项 Metro 测试、类型检查，以及 xwebview 4 项测试和类型检查均通过。App4 当前使用相邻 `file:` 源码联调；完成设备 H5 权限闭环后仍需由 Jenkins 发布新 alpha，再恢复精确 Nexus 版本。
### 2026-07-20 / 多 Bundle 插件注册表单例收口
- App4 内嵌 `miniapp` 设备验证暴露 `[XuqmRuntime] Plugin did not call definePlugin()`。bundle 摘要与内嵌 manifest 完全一致，插件入口也确实调用 `definePlugin()`；根因是 app/buz 模块区间隔离后，各自复制的 `PluginRuntime` 创建了不同 `definitions` Map。
- update SDK 将插件定义 Map 拆到轻量 `PluginRegistry.ts`，并导出 `@xuqm/rn-update/plugin-registry` 子路径。宿主 common 入口必须副作用导入该子路径，使 app 与所有 buz 通过共享模块编号读写同一个注册表；不得在 App 内写兼容 Map 或改成全局变量。
- 新增注册、读取、删除和重复定义测试；RNSDK 完整 `pnpm validate` 已通过：common 20、bugcollect 5、xwebview 4、IM 3、update CLI/Metro 11 与 update domain 8 项测试全部通过。
- App4 重建六模块并进入真实“医信课堂”后，注册表错误消失；设备随后进一步暴露并修复两类相同边界缺陷：app/miniapp 重复执行 `BVLinearGradient` 原生 View 注册，以及 miniapp 反向导入 host 后复制 `UpdateContext`。宿主 common 现统一持有跨 Bundle 原生依赖；插件通过 common 更新命令端口调用 host 实现，不再导入宿主 Context，也未增加全局变量兼容层。
- 最终 `emulator-5556` 的 common/app/miniapp 均加载成功，日志无插件注册、重复 View、Context 或 Java/React FATAL；XWebView 容器已显示真实服务标题和 DNS 错误页。该结果只证明多 Bundle 与容器运行时通过，远端 H5 内容及摄像头/麦克风授权仍需网络正常的开发环境设备验收。
### 2026-07-20 / XWebView 浏览器内核与错误态唯一实现
- 设备 DNS 失败复测发现 Android 系统英文错误页会在 `onError` 后再次触发加载事件，旧实现因此清空自定义错误状态；同时错误分支卸载 WebView，按钮持有的 ref 已为空，重试实际无效。
- `XWebViewView` 现在始终保留 WebView，并以白底中文错误层覆盖系统页；刷新、前进、后退和重试统一先清理错误状态再操作同一控制器。错误页不再由原生事件先后顺序随机决定。
- 删除 `XWebViewScreen` 内 600 余行重复的 WebView、下载、Bridge、权限和错误处理，
并最终删除该公开入口。全屏页面由 `XWebViewHost` 组合统一导航栏、系统返回与
`XWebViewView`；全屏和内嵌场景共享同一个浏览器内核。
- 当时的 xwebview 类型检查与 4 项下载/权限测试、RNSDK 全量门禁和 App4 457 tasks
构建均通过；该历史结果不能替代 1.0.0 当前实现的最终验证。当前 1.0.0 已扩展为
7 项独立测试，Android 运行验证仍待执行。
### 2026-07-20 / Android 内嵌 Bundle 启动短路
- 审计确认旧 `ensureEmbeddedBundle()` 每次查询模块路径或状态都会先从 APK assets 读取整份 Bundle，再用摘要判断是否需要覆盖；虽然不会每次写盘，但六模块冷启动仍产生无效的大文件读取和摘要对象创建。
- Android 原生模块现将 APK `manifest.json` 按进程缓存，并先读取本地 `state.json`：下载版本 SemVer 大于等于内嵌版本、原生 baseline/API 等级兼容且记录长度正常时直接加载；APK 自有 embedded 状态则使用 manifest SHA-256 短路，同版本新开发构建仍能正确替换。
- 恢复 API 始终按传入的单个 moduleId 工作，不预装 manifest 中的全部模块。宿主冷启动只请求 common、app；buz 必须在用户进入相应入口后，通过目标插件的检查/安装与 `XuqmRuntime.activate()` 按需恢复和执行。
- 设备清数据复核进一步发现，启动期 app/common 更新检查会收集全部已登记模块版本，而旧 `getBundleState()` 内部错误调用 `ensureEmbeddedBundle()`，导致“查询状态”顺带把三个 buz 全部释放到私有目录。该副作用已删除：状态存在时只读 state，未访问模块从 manifest 构造只读内嵌状态；只有 `getLaunchBundlePath(moduleId)` 能触发恢复。
- manifest 新增 `byteLength`；远程 staging 同步记录 pending/active/rollback 长度。首次安装、本地落后、baseline 不匹配、长度异常或摘要变化时才读取内嵌 Bundle，且写盘前强制校验 manifest SHA-256，再原子恢复 Bundle 与 drawable 资源。
- release-set 规划器新增 `NATIVE_BASELINE_INCOMPATIBLE`，候选缺失或不匹配当前 `builtAgainstNativeBaselineId` 时拒绝安装，避免修改原生依赖后仍向旧完整包发布 JS 插件。
- RNSDK 全量格式、六 workspace TypeScript、common 20、bugcollect 5、xwebview 4、IM 3、update CLI/Metro 11 与 update domain 9 项测试通过；App4 宿主真实执行 `:xuqm_rn-update:compileDebugJavaWithJavac`，19 tasks 构建成功，完整六模块 Debug APK 457 tasks 构建成功。
- `emulator-5556` 覆盖安装后的第一次启动只为旧状态补写 `activeByteLength` 等小型元数据，未重写已有 common `active.bundle`；第二次 `force-stop` 冷启动前后，common/app 的 `active.bundle` 与 `state.json` mtime、长度均完全不变，日志确认两者直接从应用私有目录 `rn-bundles/*/active.bundle` 装载，common 到 app 请求间隔约 15ms，且无 Java/React FATAL。两次 `am start -W` TotalTime 分别为 1052ms、1085ms，只作为模拟器回归记录；系统首帧耗时不能单独归因于 Bundle 短路，也不替代真机性能验收。
- 修复状态查询副作用后重新构建 457 tasks APK，并在 `emulator-5556` 清除数据验证：首次启动私有目录只有 `rn-bundles/common`、`rn-bundles/app`，不再出现 szyx/miniapp/workbench；第二次冷启动仍只有这两个目录，四个 bundle/state 文件的 mtime 与长度完全一致。两次清数据/二次启动 TotalTime 分别为 1137ms、1028ms，只作为正确性和相对回归记录。
### 2026-07-20 / 本地原生依赖 baseline 与原生 SemVer 收口
- `XuqmBundleModule` 不再内嵌一套 80 余行 SemVer 算法。Android 启动门禁统一调用包内 `XuqmSemanticVersion`；原生单测覆盖 SemVer 官方预发布顺序、构建元数据、超大数字标识和非法旧状态，非法状态固定返回“不可信”并恢复 APK 基线。
- 完整包 baseline 原先只记录宿主 Android/iOS 源码和依赖版本；相邻 `file:` SDK 在版本号未变时修改 Java/Kotlin 会被漏掉。`computeNativeBaseline()` 现在额外哈希每个 `file:` 运行时依赖的对应平台原生源码与资源，registry 依赖仍由不可变安装版本标识，不扫描整个 `node_modules`。
- Gradle `prepareXuqmEmbeddedBundles` 同步把所有 `file:` 依赖的 Android/iOS 原生源码、资源、podspec 与 package manifest 声明为输入，并排除 build/.cxx/.gradle/generated。baseline 计算和 Gradle 增量使用同一边界，不再出现脚本认为变化而 Gradle 跳过、或 Gradle 重建但 baseline 不变的分裂状态。
- 新增 Node fixture 证明本地依赖版本不变、只修改原生源码也会改变 Android baseline；RNSDK 全量格式、六 workspace 类型检查与全部测试通过。update CLI/Metro 测试增至 14 项，domain 仍为 9 项。
- App4 刷新本地依赖后，旧 baseline `android-sha256:4567…7501` 正确触发六模块重建，新 baseline 为 `android-sha256:eae4…99df`；紧接着复跑 998ms，11 tasks 全部 `UP-TO-DATE`。原生 SemVer 单测、update Java 编译与 App4 457 tasks Debug 构建均通过。
- 新 APK 在 `emulator-5556` 不清用户数据覆盖安装后，common/app 状态都原子刷新为 1.0.0、native API 2 和新 baseline；私有目录仍只有 common/app，无 buz，也无 Java/React FATAL。宿主同时运行 DevEco Studio/Harmony 模拟器导致本轮三次冷启动约 2.27–2.47s、fully-drawn 约 3.28–3.55s；该受竞争负载样本只保留为功能回归证据，不覆盖独立性能基准。
### 2026-07-20 / Android 插件包暂存与存储职责拆分
- `XuqmBundleModule` 不再同时承担 RN Bridge、发布事务、ZIP 解压、manifest 校验、摘要和文件系统实现。下载包大小/SHA-256、ZIP 条目与解压上限、manifest/候选版本一致性、Bundle/资源完整性统一归入 `XuqmPluginPackageStager`；桥接模块只编排 stage/activate/confirm/rollback。
- `XuqmBundleStorage` 成为插件更新原生层文件读取、安全相对路径、SHA-256、原子替换和递归删除的唯一实现；内嵌 Bundle 恢复与远端插件暂存共用同一摘要和写盘语义，没有保留旧私有方法或补丁兼容层。
- `XuqmBundleModule` 从 1081 行降至 853 行。新增原生单测覆盖标准 SHA-256、目录穿越拒绝、Android 资源路径白名单，并与既有 SemVer 测试一起在 App4 宿主执行：3 个测试类、6 项测试、0 failure/error。
- App4 刷新相邻 `file:` 依赖后，原生源码变化按设计触发六模块重建，native baseline 更新为 `android-sha256:1a95…5cf0`；紧接着复跑 `:app:prepareXuqmEmbeddedBundles` 为 11 tasks 全部 `UP-TO-DATE`。完整 `:app:assembleDebug` 与 `:xuqm_rn-update:testDebugUnitTest` 同轮构建成功。
### 2026-07-20 / Gradle 9.3.1 宿主兼容复核
- update Android 仓库声明已改为 Gradle 9 持续支持的 `url = uri(...)` 赋值形式，不再由 Xuqm 自有脚本产生旧 Groovy property-space assignment warning；不在 SDK 内覆盖宿主 AGP、Kotlin、Gradle 或 React Native 版本。
- App4 按 RN 0.86 官方模板切换到 Gradle 9.3.1 后，真实执行 `:xuqm_rn-update:testDebugUnitTest` 成功，并完成 451 tasks 六模块 Debug APK 构建；原生存储、暂存、SemVer 与 Bridge 拆分均进入宿主编译，不只是独立源码测试。
- 本轮 SDK 定向复核结果：common 21 tests、update CLI/Metro/native-baseline 14 tests、release-set/plugin-registry 9 tests、bugcollect 5 tests、xwebview 4 tests；根工作区及各 package TypeScript、Prettier 和 update 发布包 35 文件校验均通过。App4 完整门禁同步达到 20 suites / 87 tests。
- Gradle 9 构建仍报告的弃用项来自 React Native/三方插件，不通过 SDK 关闭 warning。后续升级必须继续以宿主完整构建和原生单测为门禁，不能只验证 TypeScript 或 npm 打包。

69
docs/SDK-API参考.md
查看文件

@ -3,9 +3,9 @@
## 公共生命周期 ## 公共生命周期
```ts ```ts
import { XuqmSDK } from '@xuqm/rn-common' import {XuqmSDK} from '@xuqm/rn-common';
await XuqmSDK.awaitInitialization() await XuqmSDK.awaitInitialization();
await XuqmSDK.login({ await XuqmSDK.login({
userId: 'user-id', userId: 'user-id',
@ -13,30 +13,18 @@ await XuqmSDK.login({
userSig: 'optional-im-credential', userSig: 'optional-im-credential',
name: '姓名', name: '姓名',
phone: '手机号', phone: '手机号',
}) });
await XuqmSDK.logout() await XuqmSDK.logout();
``` ```
- `awaitInitialization()`：等待唯一自动初始化完成；缺少平台签发配置或 Metro 集成时 - `initialize(options)`：仅在不能使用配置文件自动初始化时调用。
抛出明确错误。 - `awaitInitialization()`：等待唯一初始化完成；未配置且未手动初始化会抛出明确错误。
- `login(options)`：唯一登录入口；同一会话重复调用幂等，不同会话串行切换。 - `login(options)`：唯一登录入口；同一会话重复调用幂等，不同会话串行切换。
- `setPrivacyConsent(consented)`：唯一隐私同意同步入口；扩展 SDK 不自行弹窗。
- `getInitializationState()`：返回 `idle / initializing / ready / degraded / failed` 及
可选结构化错误。
- `logout()`：唯一登出入口。 - `logout()`：唯一登出入口。
- `getUserId()` / `getUserInfo()`：只读获取当前会话。 - `getUserId()` / `getUserInfo()`：只读获取当前会话。
不提供 `initialize`、`setUserInfo`、`setUserId` 或公开的配置文件初始化入口。 不提供 `setUserInfo`、`setUserId` 或公开的配置文件初始化入口。
### 地址职责
- `platformUrl`：Xuqm 租户平台地址。远程配置、整包更新、插件 release set 检查等平台接口只使用该地址；自动配置未提供时使用 SDK 内置的公有平台地址。
- `apiUrl`：租户平台返回的业务扩展服务地址，只供明确声明使用该业务服务的扩展能力读取，不能替代 `platformUrl`。
- common 的 `apiRequest()` 默认基础地址在 SDK 初始化后固定为 `platformUrl`；访问其它业务服务时必须传绝对 URL 或在 common-only 模式显式 `configureHttp()`，禁止用远程 `apiUrl` 静默改写平台请求。
- 配置中的 `signingKey` 是可被客户端提取的请求完整性材料，不代表用户身份或接口
授权；敏感接口必须继续校验登录 `accessToken`，构建制品上传使用 Jenkins 发布
Bearer。
## common 通用能力 ## common 通用能力
@ -45,55 +33,16 @@ await XuqmSDK.logout()
- `apiRequest`、`configureHttp`、`useRequest`、`useApi`、`usePageApi` - `apiRequest`、`configureHttp`、`useRequest`、`useApi`、`usePageApi`
- `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime` - `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`
- `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile` - `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`
- `hmacSha256Base64Url`、`sha256Hex` - `decryptXuqmFile`、`hmacSha256Base64Url`
- `getDeviceId`、`getDeviceInfo`、`detectPushVendor` - `getDeviceId`、`getDeviceInfo`、`detectPushVendor`
- `showToast`、`showAlert`、`showConfirm`、`ScaledImage` - `showToast`、`showAlert`、`showConfirm`、`ScaledImage`
## 扩展包 ## 扩展包
- `@xuqm/rn-update`：`UpdateSDK`、`XuqmRuntime`、`definePlugin` 和 `xuqm-rn` CLI。 - `@xuqm/rn-update`：`UpdateSDK`、`XuqmRuntime`、`definePlugin` 和 `xuqm-rn` CLI。
原生最终恢复页使用 `UpdateSDK.resetToEmbedded()`；它只清理 Update SDK 私有 - `@xuqm/rn-xwebview`：`XWebViewView`、`XWebViewScreen`、JSBridge 与统一下载。
Bundle/发布状态，不影响宿主账号、业务数据、BugCollect 或签名 SDK。
- `@xuqm/rn-xwebview`：根部一次挂载 `XWebViewHost`，业务使用
`openWebView(config)` 打开全屏页面；`XWebViewView` 只用于内嵌浏览器。业务
JSBridge 通过 `config.bridge` 注入，不属于 XWebView 自身协议。
- `@xuqm/rn-bugcollect`：`BugCollect` 错误、事件、漏斗和队列上报。 - `@xuqm/rn-bugcollect`：`BugCollect` 错误、事件、漏斗和队列上报。
Debug 单次联调使用 `BugCollect.sendTestErrorAndFlush()`，App 不调用
`startCapture()`。
- `@xuqm/rn-im`：在 common 会话含 `userSig` 且服务启用时连接。 - `@xuqm/rn-im`：在 common 会话含 `userSig` 且服务启用时连接。
- `@xuqm/rn-push`：在 common 会话变化时同步原生推送绑定。 - `@xuqm/rn-push`：在 common 会话变化时同步原生推送绑定。
所有扩展包都不提供第二套初始化或登录 API。 所有扩展包都不提供第二套初始化或登录 API。
## update 插件检查边界
Update 服务由平台远程配置 `features.update` 控制，缺失时默认关闭。显式调用
`checkAppUpdate`、`downloadApk`、`downloadAndInstallApp`、`checkPluginRelease` 或
`installPluginRelease` 时，关闭状态统一抛出 `UpdateDisabledError`，错误码为
`UPDATE_DISABLED`，且不会先访问网络或原生安装模块；自动启动检查会正常跳过。
```ts
const plan = await UpdateSDK.checkPluginRelease('buz1', {
signal,
timeoutMs: 5_000,
})
if (plan) {
await UpdateSDK.installPluginRelease(plan, { signal, onProgress })
}
await UpdateSDK.checkAndInstallPlugin('buz1', {
signal,
checkTimeoutMs: 5_000,
onProgress,
})
```
- `checkPluginRelease()` 只检查版本和兼容依赖闭包，不下载、不激活；`timeoutMs` 只约束检查请求。
- `installPluginRelease()` 只安装此前确认的计划；本地基线已变化时抛出 `StaleReleaseSetError`。
- `checkAndInstallPlugin()` 用于宿主自动进入插件的场景；`checkTimeoutMs` 只传给检查阶段，下载仍由 `signal` 和进度回调控制。
- release-set 请求固定包含 `appVersion`、`nativeApiLevel`、`nativeBaselineId`；缺少
native baseline 时不发请求。服务端返回的插件候选必须具有平台 Ed25519
`keyId/signature`，客户端在计划前和安装前验证不可变 manifest。
候选响应的 ZIP `sha256` 以 `archiveSha256` 纳入签名，下载后继续以同一值校验归档。
- common HTTP 的统一默认请求上限为 30 秒；宿主需要更短的交互等待时显式传上述参数，不得在页面复制 `Promise.race` 或第二套超时器。

231
docs/XWebView-JSBridge.md
查看文件

@ -1,52 +1,211 @@
# XWebView Bridge 边界 # XWebView JSBridge 标准接口
> 最后更新：2026-07-26 > 最后更新：2026-06-15
XWebView 不是业务 JSBridge 协议。它只定义一个通用适配接口： ---
```ts ## 概述
type XWebViewBridge = {
injectedJavaScriptBeforeContentLoaded?: string XWebView 内置 JSBridge，支持 H5 页面与 React Native 宿主之间的双向通信。
onMessage(raw: string, context: XWebViewBridgePageContext): boolean | Promise<boolean>
onPageClosed?(pageId: string): void **通信机制**：
} - H5 → RN：`window.ReactNativeWebView.postMessage(JSON.stringify(data))`
- RN → H5：`webViewRef.injectJavaScript(jsString)`
---
## 一、H5 → RN 消息协议
### 1.1 内置消息（__xwv 前缀）
XWebView 自动拦截以下浏览器行为，通过 `postMessage` 发送给 RN：
| 消息类型 | 触发场景 | 数据格式 |
|---------|---------|---------|
| `alert` | `window.alert(msg)` | `{__xwv: 'alert', msg: string}` |
| `confirm` | `window.confirm(msg)` | `{__xwv: 'confirm', msg: string}` |
| `prompt` | `window.prompt(msg, def)` | `{__xwv: 'prompt', msg: string, def: string}` |
| `download` | 点击下载链接 | `{__xwv: 'download', url: string, filename: string}` |
| `blobdownload` | blob URL 下载 | `{__xwv: 'blobdownload', url: string, filename: string, data: base64}` |
| `bloberror` | blob 读取失败 | `{__xwv: 'bloberror', msg: string}` |
| `log` | 调试日志 | `{__xwv: 'log', msg: string}` |
### 1.2 自定义消息
H5 发送非 `__xwv` 前缀的消息时，XWebView 将其转发给 `onMessage` 回调：
```javascript
// H5 端
window.ReactNativeWebView.postMessage(JSON.stringify({
type: 'customEvent',
payload: { key: 'value' }
}));
``` ```
## 页面上下文 ```typescript
// RN 端
<XWebViewView
onMessage={(event) => {
const data = JSON.parse(event.nativeEvent.data);
if (data.type === 'customEvent') {
// 处理自定义消息
}
}}
/>
```
业务协议实现可以： ---
- 关闭当前页； ## 二、RN → H5 通信
- 向当前页执行 JavaScript；
- 判断当前页是否为页面栈顶；
- 取得真实状态栏高度；
- 修改当前页导航栏标题/背景；
- 修改当前页导航栏与状态栏显隐。
协议实现不能： ### 2.1 注入 JavaScript
- 访问或修改其他 WebView 页面； ```typescript
- 从 XWebView 读取用户、token、平台、域名或厂商； // 通过 controller API
- 直接控制宿主导航器； controller.postMessageToWeb('window.dispatchEvent(new CustomEvent("rnMessage", {detail: {type: "update", data: "hello"}}))');
- 输出原始 Bridge payload；
- 在 common 中注册全局业务 handler。
## 消息所有权 // 通过 ref
webViewRef.injectJavaScript('window.handleRNMessage("hello")');
```
XWebView 内部只消费 `__xwv` 命名空间： ### 2.2 Controller API
- `download` / `blobdownload` / `bloberror` 通过 `setXWebViewController` 获取的 controller 对象提供以下方法：
- `permission`
其他消息先交给 `config.bridge`。Bridge 返回 `false` 时才继续交给 | 方法 | 说明 |
`behavior.onMessage`。Bridge 抛错由 `behavior.onBridgeError` 接收，不产生未处理 |------|------|
Promise。 | `refresh()` | 刷新当前页面 |
| `close()` | 关闭 WebView |
| `goBack()` | 返回上一页 |
| `goForward()` | 前进 |
| `copyUrl()` | 复制当前 URL 到剪贴板 |
| `postMessageToWeb(jsString)` | 向 H5 注入并执行 JS |
| `getTitle()` | 获取当前页面标题 |
## 业务协议接入 ---
业务协议必须在自己的 SDK/插件中维护唯一方法表、请求解析、响应结构、错误码和兼容 ## 三、下载处理
测试，然后以 `XWebViewBridge` 适配到容器。XWebView 不提供 `getSession`、`navigate`、
`showToast`、签名、支付或任何假定宿主业务的内置方法。
医网信 H5 场景使用 `@szyx/sdk-h5-app/host`；其 V5 线协议不属于 ### 3.1 自动下载拦截
`@xuqm/rn-xwebview` 的公开契约。
XWebView 自动拦截以下文件扩展名的链接点击：
```
.pdf .zip .rar .tar .gz .apk .ipa .doc .docx .xls .xlsx .ppt .pptx .mp4 .mp3 .mov .exe .dmg
```
### 3.2 下载回调
```typescript
<XWebViewView
autoDownload={true}
onDownloadStart={(request) => {
// request: { url, suggestedFilename, mimeType?, fileSize? }
console.log('Download started:', request.suggestedFilename);
}}
onDownloadProgress={(progress) => {
// progress: { url, filename, received, total, percentage }
console.log(`Download: ${progress.percentage}%`);
}}
onDownloadComplete={(result) => {
// result: { url, filename, filePath, fileSize }
console.log('Download complete:', result.filePath);
}}
onDownloadError={(url, error) => {
console.error('Download failed:', url, error);
}}
onDownloadDecide={(request) => {
// 返回下载决策
return { allowed: true, filename: request.suggestedFilename };
}}
downloadConflict="rename" // 'rename' | 'overwrite'
/>
```
### 3.3 Blob URL 下载
XWebView 自动处理 blob URL 下载：
1. 拦截 `<a href="blob:...">` 点击
2. 通过 `FileReader` 读取 blob 数据为 base64
3. 通过 `saveBase64File` 保存到本地
---
## 四、内置 Dialog 覆盖
XWebView 注入 `DIALOG_OVERRIDE_JS`，覆盖浏览器原生对话框：
| 原生方法 | 覆盖行为 |
|---------|---------|
| `window.alert(msg)` | 发送 `{__xwv: 'alert', msg}` 消息 |
| `window.confirm(msg)` | 发送 `{__xwv: 'confirm', msg}` 消息，始终返回 `true` |
| `window.prompt(msg, def)` | 发送 `{__xwv: 'prompt', msg, def}` 消息，返回默认值 |
| `window.open(url)` | 发送日志消息，然后 `window.location.href = url` |
RN 端收到这些消息后，可以展示原生 Alert/Confirm/Prompt 对话框。
---
## 五、标准 Bridge 接口（宿主实现）
以下接口由宿主应用通过 `bridgeHandlers` 实现，H5 通过 `xuqm.call(method, params)` 调用：
### 5.1 会话管理
| 接口 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `getSession` | — | `{token, userId}` | 获取当前登录会话 |
| `getUserInfo` | — | `{userId, name, phone, avatar}` | 获取用户信息 |
### 5.2 导航
| 接口 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `navigate` | `{screen, params?}` | — | 跳转宿主页面 |
| `close` | — | — | 关闭当前 WebView |
| `goBack` | — | — | 返回上一页 |
### 5.2 UI 交互
| 接口 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `showToast` | `{message}` | — | 显示 Toast |
| `showAlert` | `{title?, message}` | — | 显示 Alert 对话框 |
| `showConfirm` | `{title?, message, confirmText?, cancelText?}` | `{confirmed: boolean}` | 显示确认对话框 |
### 5.3 文件操作
| 接口 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `uploadFile` | `{accept?}` | `{url, name, size}` | 选择并上传文件 |
| `openCamera` | — | `{url, base64}` | 打开相机拍照 |
| `scanQR` | — | `{result}` | 扫描二维码 |
### 5.4 设备信息
| 接口 | 参数 | 返回值 | 说明 |
|------|------|--------|------|
| `getDeviceInfo` | — | `{platform, version, model}` | 获取设备信息 |
| `getLocation` | — | `{latitude, longitude}` | 获取当前位置 |
---
## 六、H5 端调用示例
```javascript
// 获取会话
xuqm.call('getSession').then(session => {
console.log('Token:', session.token);
});
// 跳转宿主页面
xuqm.call('navigate', { screen: 'Settings' });
// 显示 Toast
xuqm.call('showToast', { message: '操作成功' });
// 上传文件
xuqm.call('uploadFile', { accept: 'image/*' }).then(file => {
console.log('Uploaded:', file.url);
});
```

16
docs/插件脚手架.md
查看文件

@ -9,17 +9,7 @@ pnpm exec xuqm-rn init
pnpm xuqm:doctor pnpm xuqm:doctor
``` ```
`init` 只创建缺失的统一配置和必要脚本，不覆盖宿主已有代码。唯一插件构建清单为根目录 `xuqm.modules.json`。它与租户平台签发、宿主不可编辑的 `config.xuqmconfig` 初始化文件职责完全分离。 `init` 只创建缺失的统一配置和必要脚本，不覆盖宿主已有代码。唯一插件配置文件为根目录 `xuqm.config.json`。
构建清单分别使用 `packageName` 保存 Android applicationId、使用 `iosBundleId`
保存 iOS Bundle Identifier。目标平台字段只在该平台 build/package/release 时必填。
ZIP wire 字段统一名为 `packageName`，但其值必须由 CLI 按平台从上述两个配置字段解析；
发布时再与同一平台身份精确比较。
插件 ZIP v1 只有一套协议上限：归档不超过 50 MiB、单个 entry 解压后不超过
100 MiB、全部 entry 解压后合计不超过 100 MiB、entry 总数不超过 4096。CLI
`zipSync` 只生成文件 entry，因此显式目录 entry 不属于 v1 协议，服务端和 Android
stager 都必须拒绝；禁止在任一端另设 5000 等平行上限。
开发启动也使用同一 CLI，不由宿主复制 Node 包装脚本： 开发启动也使用同一 CLI，不由宿主复制 Node 包装脚本：
@ -40,7 +30,7 @@ pnpm exec xuqm-rn plugin create prescription
- 以小写字母开头 - 以小写字母开头
- 只包含小写字母、数字和连字符 - 只包含小写字母、数字和连字符
- 在 `xuqm.modules.json` 中唯一 - 在 `xuqm.config.json` 中唯一
CLI 会生成： CLI 会生成：
@ -50,7 +40,7 @@ src/plugins/prescription/
PrescriptionScreen.tsx PrescriptionScreen.tsx
``` ```
并向 `xuqm.modules.json.modules` 增加唯一模块声明。不会修改 Babel alias、TypeScript paths、Metro offset 或增加模块专属 package script。 并向 `xuqm.config.json.modules` 增加唯一模块声明。不会修改 Babel alias、TypeScript paths、Metro offset 或增加模块专属 package script。
## 插件入口 ## 插件入口

2
docs/架构总览.md
查看文件

@ -4,7 +4,7 @@
`@xuqm/rn-common` 是唯一可以独立使用的基础包，负责： `@xuqm/rn-common` 是唯一可以独立使用的基础包，负责：
- 为官方扩展提供从 `src/assets/config/` 内唯一 `.xuqmconfig` 自动初始化的共享上下文；common 单独使用时不启动初始化； - 为官方扩展提供从 `src/assets/config/config.xuqmconfig` 自动初始化的共享上下文；common 单独使用时不启动初始化；
- 维护唯一的 SDK 配置和用户会话； - 维护唯一的 SDK 配置和用户会话；
- 网络、访问令牌、签名、文件、时间、加密、设备信息和通用 UI； - 网络、访问令牌、签名、文件、时间、加密、设备信息和通用 UI；
- 将一次 `XuqmSDK.login()` / `logout()` 传播给官方扩展包。 - 将一次 `XuqmSDK.login()` / `logout()` 传播给官方扩展包。

80
docs/配置文件规范.md
查看文件

@ -8,7 +8,7 @@ Xuqm RN 扩展 SDK 只支持一种自动初始化方案：宿主保存一份平
- 不放 `.xuqmconfig` - 不放 `.xuqmconfig`
- 不使用 `withXuqmConfig()` - 不使用 `withXuqmConfig()`
- 不存在也不需要调用 `XuqmSDK.initialize()` - 不调用 `XuqmSDK.initialize()`
- 不调用 `XuqmSDK.login()` - 不调用 `XuqmSDK.login()`
common-only 模式保持零初始化、零登录。 common-only 模式保持零初始化、零登录。
@ -18,35 +18,35 @@ common-only 模式保持零初始化、零登录。
安装 update、bugcollect、xwebview 等扩展后，将平台签发的原始文件放到： 安装 update、bugcollect、xwebview 等扩展后，将平台签发的原始文件放到：
```text ```text
src/assets/config/<平台下载的文件名>.xuqmconfig src/assets/config/config.xuqmconfig
``` ```
文件名由租户平台决定，不要求宿主改名。该目录没有 `.xuqmconfig` 时保持 文件名也可以是其他 `*.xuqmconfig`。扫描优先级为：
common-only；恰好一个时自动使用；存在多个时构建明确失败，禁止按名称或排序猜测
权威配置。不会扫描其它目录。 1. `config.xuqmconfig`
2. `config.xuqm`
3. 目录中的第一个 `*.xuqmconfig`
Metro 配置只包装一次： Metro 配置只包装一次：
```js ```js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config') const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const { withXuqmConfig } = require('@xuqm/rn-common/metro') const {withXuqmConfig} = require('@xuqm/rn-common/metro');
const baseConfig = mergeConfig(getDefaultConfig(__dirname), { const baseConfig = mergeConfig(getDefaultConfig(__dirname), {
// 宿主自己的 Metro 配置 // 宿主自己的 Metro 配置
}) });
module.exports = withXuqmConfig(baseConfig) module.exports = withXuqmConfig(baseConfig);
``` ```
## 自动初始化时序 ## 自动初始化时序
```text ```text
Metro 读取唯一 .xuqmconfig Metro 读取唯一 .xuqmconfig
→ 验证平台 Ed25519 签名
→ 校验 V2 Schema、有效期和 canonical JSON
→ AES-GCM 解密
→ 生成构建期传输模块 → 生成构建期传输模块
→ 注册 @xuqm/rn-common/internal 为 pre-main module → 注册 @xuqm/rn-common/internal 为 pre-main module
→ 解密配置
→ 使用 appKey 请求远程 SDK 配置 → 使用 appKey 请求远程 SDK 配置
→ 初始化唯一 HTTP/扩展上下文 → 初始化唯一 HTTP/扩展上下文
→ 执行业务入口 → 执行业务入口
@ -56,69 +56,50 @@ pre-main 机制保证初始化不受 Metro `inlineRequires` 和业务模块加
## 原生配置同步 ## 原生配置同步
Android Release 构建任务会在 V2 验签和 Bundle 构建成功后，把同一份源文件复制到： `withXuqmConfig()` 会把同一份源文件幂等同步到：
```text ```text
android/app/build/generated/xuqm/assets/config/config.xuqmconfig android/app/src/main/assets/config/config.xuqmconfig
ios/<App>/config/config.xuqmconfig
``` ```
该位置是被 Git 排除的固定构建目标，不是第二配置源。宿主只维护 这些位置是构建目标，不是第二配置源。宿主只维护 `src/assets/config` 下的原文件。
`src/assets/config/` 中平台下载的唯一 `.xuqmconfig`；不得把副本写进 Android/iOS
源码目录。
## 加密文件 ## 加密文件
文件格式： 文件格式：
```text ```text
XUQM-CONFIG-V2.{keyId}.{salt}.{iv}.{ciphertextAndTag}.{signature} XUQM-CONFIG-V1.{salt}.{iv}.{ciphertextAndTag}
``` ```
- Ed25519 验签覆盖前五段的精确 ASCII，必须先验签再解密 - PBKDF2-HMAC-SHA256
- `keyId` 只能命中 SDK 内置的 X.509 Ed25519 公钥集合 - AES-256-GCM
- PBKDF2-HMAC-SHA256 + AES-256-GCM 仅用于混淆正文
- 12 字节 IV - 12 字节 IV
- 16 字节认证标签 - 16 字节认证标签
明文必须是键按字典序排列、无空白、忽略 null 的 canonical JSON。必要字段为 解密后的必要字段为 `appKey`，可选字段包括 `serverUrl`、`baseUrl` 和 `signingKey`。明文结构由平台负责签发，业务仓库不得自行构造。
`schemaVersion=2`、`configId`、正整数 `revision`、`issuedAt`、`appKey`、`appName`、
`serverUrl` 和 `signingKey`；`expiresAt` 省略表示长期有效。平台重新生成配置后，
旧 `configId/revision` 只会阻止后续 Release 构建，不会追溯影响已经安装的 App。
远程配置响应中的 `apiUrl` 是业务扩展服务地址，与配置文件中的平台地址职责不同：
```text
配置文件 serverUrl/baseUrl
→ platformUrl
→ /api/sdk/config、整包更新、插件 release set 等 Xuqm 平台接口
平台返回 apiUrl
→ 业务扩展服务
→ 只有明确依赖该服务的扩展能力使用
```
禁止把远程 `apiUrl` 写回公共 HTTP 基础地址，否则会把版本检查错误地发送到 App 自身业务服务。
## 登录 ## 登录
初始化与业务登录是两个动作。App 登录完成后只同步一次公共会话： 初始化与业务登录是两个动作。App 登录完成后只同步一次公共会话：
```ts ```ts
import { XuqmSDK } from '@xuqm/rn-common' import {XuqmSDK} from '@xuqm/rn-common';
await XuqmSDK.awaitInitialization() await XuqmSDK.awaitInitialization();
await XuqmSDK.login({ await XuqmSDK.login({
userId: 'user-id', userId: 'user-id',
accessToken: 'access-token', accessToken: 'access-token',
name: '姓名', name: '姓名',
phone: '手机号', phone: '手机号',
}) });
``` ```
退出时只调用： 退出时只调用：
```ts ```ts
await XuqmSDK.logout() await XuqmSDK.logout();
``` ```
扩展包不得各自初始化或登录，业务代码不得导入 `@xuqm/rn-common/internal`。 扩展包不得各自初始化或登录，业务代码不得导入 `@xuqm/rn-common/internal`。
@ -126,9 +107,7 @@ await XuqmSDK.logout()
## 失败规则 ## 失败规则
- 扩展项目缺少配置：`awaitInitialization()` 明确报错。 - 扩展项目缺少配置：`awaitInitialization()` 明确报错。
- 签名、V2 Schema、canonical JSON 或有效期校验失败：构建立即失败。 - 解密失败或远程配置失败：初始化 Promise 拒绝并保留原始错误。
- 远程配置失败且存在七天内的最后成功配置：进入 `degraded` 并继续启动。
- 首次启动没有缓存：扩展能力返回 `XUQM_NOT_READY`，宿主核心业务继续运行。
- 不自动切换到硬编码配置，不静默创建默认租户，不提供多级兼容回退。 - 不自动切换到硬编码配置，不静默创建默认租户，不提供多级兼容回退。
- common-only 项目没有配置时不会执行初始化，也不会报错。 - common-only 项目没有配置时不会执行初始化，也不会报错。
@ -138,12 +117,3 @@ await XuqmSDK.logout()
- 不提交明文 appKey、signingKey 或租户密钥。 - 不提交明文 appKey、signingKey 或租户密钥。
- 不在多个目录手工维护配置副本。 - 不在多个目录手工维护配置副本。
- `.xuqmconfig` 变更必须通过平台重新签发。 - `.xuqmconfig` 变更必须通过平台重新签发。
- 最后成功配置不会明文写入 AsyncStorage。SDK 使用签发配置中的 `signingKey`、
appKey、包名和平台地址派生独立 AES-GCM 缓存密钥，密钥材料不落缓存；篡改、
跨包或跨环境读取都会失败。该边界属于应用沙箱内加密，不宣称具备 Android
Keystore/iOS Keychain 的硬件密钥保密性。
- `signingKey` 是随客户端配置交付、可被终端提取的请求签名材料，只用于请求完整性
标记和本地缓存派生，不是 License、授权凭据或服务端秘密，服务端不得仅凭该签名
授予敏感权限。
- 用户数据、灰度发布、上传构建制品等敏感 API 仍必须使用登录得到的用户
`accessToken` 或 Jenkins 发布流水线的独立 Bearer，并由服务端执行真实授权。

11
package.json
查看文件

@ -18,13 +18,12 @@
"registry": "https://nexus.xuqinmin.com/repository/npm-hosted/" "registry": "https://nexus.xuqinmin.com/repository/npm-hosted/"
}, },
"scripts": { "scripts": {
"format": "prettier --write AGENTS.md docs/IMPLEMENTATION_HANDOFF.md package.json scripts packages/common packages/bugcollect packages/update packages/xwebview", "format": "prettier --write AGENTS.md docs/IMPLEMENTATION_HANDOFF.md package.json packages/common packages/bugcollect packages/update packages/xwebview",
"format:check": "prettier --check AGENTS.md docs/IMPLEMENTATION_HANDOFF.md package.json scripts packages/common packages/bugcollect packages/update packages/xwebview", "format:check": "prettier --check AGENTS.md docs/IMPLEMENTATION_HANDOFF.md package.json packages/common packages/bugcollect packages/update packages/xwebview",
"signature-vector:check": "node scripts/sync-server-signature-vector.mjs --check", "test": "pnpm --recursive --if-present test",
"test": "corepack pnpm --recursive --if-present test",
"typecheck": "tsc --noEmit", "typecheck": "tsc --noEmit",
"typecheck:all": "corepack pnpm --recursive --if-present typecheck", "typecheck:all": "pnpm --recursive --if-present typecheck",
"validate": "corepack pnpm signature-vector:check && corepack pnpm format:check && corepack pnpm typecheck:all && corepack pnpm test" "validate": "pnpm format:check && pnpm typecheck:all && pnpm test"
}, },
"peerDependencies": { "peerDependencies": {
"@react-native-async-storage/async-storage": ">=1.21.0", "@react-native-async-storage/async-storage": ">=1.21.0",

12
packages/bugcollect/README.md
查看文件

@ -24,18 +24,8 @@ try {
} }
``` ```
初始化只由 common 自动完成，登录只由 `XuqmSDK.login()` 完成。宿主通过 初始化只由 common 自动完成，登录只由 `XuqmSDK.login()` 完成。配置中启用 bugcollect 后，SDK 在共享初始化完成时自动执行一次 `startCapture()`；手工调用仍然幂等，但正常集成不需要调用。`BugCollect.flush()` 可在 App 转入后台前主动刷新队列。
`XuqmSDK.setPrivacyConsent(true)` 同步已取得的隐私同意；只有平台启用、用户同意且
非 Debug 三个条件同时满足时，SDK 才自动注册采集。不存在宿主手工启动入口。
`BugCollect.flush()` 可在 App 转入后台前主动刷新队列；Debug 开发页使用
`BugCollect.sendTestErrorAndFlush()` 做一次性真实上报验证。
错误指纹使用 common 的统一 SHA-256 实现，事件里的 SDK 版本直接读取当前发布包版本，不再维护第二份硬编码版本号。 错误指纹使用 common 的统一 SHA-256 实现，事件里的 SDK 版本直接读取当前发布包版本，不再维护第二份硬编码版本号。
SourceMap 上传使用独立打包后处理流程；不要再叠加基于 Metro `customSerializer` 的旧插件方案，以免破坏新版 Metro 的 exports 与序列化流程。 SourceMap 上传使用独立打包后处理流程；不要再叠加基于 Metro `customSerializer` 的旧插件方案，以免破坏新版 Metro 的 exports 与序列化流程。
fatal/error 持久队列复用 common 的 AES-GCM 沙箱加密能力；没有签发密钥时不降级写入
包含堆栈和设备信息的明文。Issue 只有在错误堆栈能唯一匹配当前原生 Bundle
state/manifest 时才携带 `buildId/moduleId/moduleVersion/bundleHash` 并标记
`symbolicationStatus=exact`；无法归属时明确为 `unavailable`，服务端不得猜测 latest
Source Map。

220
packages/bugcollect/metro/index.js 普通文件
查看文件

@ -0,0 +1,220 @@
'use strict'
const fs = require('fs')
const path = require('path')
const https = require('https')
const http = require('http')
/**
* 读取配置文件获取 bugCollectApiUrl
*/
function readConfig(projectRoot) {
// 1. 尝试读取 xuqm.config.js
const configJsPath = path.join(projectRoot, 'xuqm.config.js')
if (fs.existsSync(configJsPath)) {
try {
const config = require(configJsPath)
if (config.bugCollectApiUrl) return config.bugCollectApiUrl
if (config.platformUrl) return config.platformUrl.replace(/\/$/, '') + '/api'
} catch (e) {
console.warn('[BugCollect] Failed to read xuqm.config.js:', e.message)
}
}
// 2. 尝试读取 .xuqmconfig (加密配置文件)
const configDirs = ['config', 'xuqm']
for (const dir of configDirs) {
const configDir = path.join(projectRoot, 'src', 'assets', dir)
if (!fs.existsSync(configDir)) continue
const files = fs.readdirSync(configDir)
const configFile = files.find(f => f.endsWith('.xuqmconfig') || f.endsWith('.xuqm'))
if (configFile) {
// 加密配置文件需要解密，这里先跳过
// 实际使用时应该通过 SDK 解密
console.warn('[BugCollect] Encrypted config found but cannot be read directly')
}
}
// 3. 从环境变量读取
if (process.env.BUG_COLLECT_API_URL) return process.env.BUG_COLLECT_API_URL
return null
}
/**
* 上传 SourceMap 文件
*/
function uploadSourceMap(apiUrl, appKey, platform, appVersion, sourceMapPath) {
return new Promise((resolve, reject) => {
const url = new URL(`${apiUrl}/bugcollect/v1/sourcemaps/upload`)
const isHttps = url.protocol === 'https:'
const client = isHttps ? https : http
// 读取 sourcemap 文件
const fileContent = fs.readFileSync(sourceMapPath)
const fileName = path.basename(sourceMapPath)
// 构建 multipart/form-data
const boundary = '----BugCollectBoundary' + Date.now()
const parts = []
// appKey
parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="appKey"\r\n\r\n${appKey}`)
// platform
parts.push(
`--${boundary}\r\nContent-Disposition: form-data; name="platform"\r\n\r\n${platform}`,
)
// appVersion
parts.push(
`--${boundary}\r\nContent-Disposition: form-data; name="appVersion"\r\n\r\n${appVersion}`,
)
// bundleName
parts.push(`--${boundary}\r\nContent-Disposition: form-data; name="bundleName"\r\n\r\nindex`)
// file
parts.push(
`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName}"\r\nContent-Type: application/json\r\n\r\n`,
)
const header = Buffer.from(parts.join('\r\n') + '\r\n')
const footer = Buffer.from(`\r\n--${boundary}--\r\n`)
const body = Buffer.concat([header, fileContent, footer])
const options = {
hostname: url.hostname,
port: url.port || (isHttps ? 443 : 80),
path: url.pathname,
method: 'POST',
headers: {
'Content-Type': `multipart/form-data; boundary=${boundary}`,
'Content-Length': body.length,
},
}
const req = client.request(options, res => {
let data = ''
res.on('data', chunk => (data += chunk))
res.on('end', () => {
if (res.statusCode >= 200 && res.statusCode < 300) {
console.log(`[BugCollect] SourceMap uploaded successfully: ${fileName}`)
resolve(data)
} else {
console.warn(`[BugCollect] SourceMap upload failed: ${res.statusCode} ${data}`)
reject(new Error(`Upload failed: ${res.statusCode}`))
}
})
})
req.on('error', err => {
console.warn('[BugCollect] SourceMap upload error:', err.message)
reject(err)
})
req.write(body)
req.end()
})
}
/**
* 获取应用版本号
*/
function getAppVersion(projectRoot) {
try {
const packageJson = require(path.join(projectRoot, 'package.json'))
return packageJson.version || '1.0.0'
} catch {
return '1.0.0'
}
}
/**
* withBugCollect(metroConfig)
* 包裹 Metro 配置，打 Release 包时自动上传 SourceMap。
*/
function withBugCollect(metroConfig) {
const projectRoot = metroConfig.projectRoot || process.cwd()
return {
...metroConfig,
serializer: {
...metroConfig.serializer,
customSerializer: async (entryPoint, preModules, graph, options) => {
// 仅在宿主已有 customSerializer 时委托；否则保持 result 未定义并交回 Metro。
// 注意：本插件应通过显式包裹在已有 serializer 之上使用（见 README），
// 不建议自动链式启用（Metro 默认 serializer 不可经 exports 获取）。
const baseSerializer = metroConfig.serializer?.customSerializer
const result = baseSerializer
? await baseSerializer(entryPoint, preModules, graph, options)
: undefined
// 仅 Release 包上传 SourceMap（dev 模式跳过）
if (!options.dev) {
try {
// 获取配置
const apiUrl = readConfig(projectRoot)
if (!apiUrl) {
console.warn('[BugCollect] No API URL configured, skipping SourceMap upload')
return result
}
// 从 graph 中获取 appKey
const appKey = graph.transformer?.config?.xuqmAppKey || process.env.XUQM_APP_KEY || ''
if (!appKey) {
console.warn('[BugCollect] No appKey configured, skipping SourceMap upload')
return result
}
// 获取平台和版本
const platform = options.platform || 'android'
const appVersion = getAppVersion(projectRoot)
// 查找 sourcemap 文件路径
// Metro 会在 options.sourceMapUrl 中指定 sourcemap 路径
const sourceMapUrl = options.sourceMapUrl
let sourceMapPath = null
if (sourceMapUrl) {
// 从 URL 中提取本地路径
if (sourceMapUrl.startsWith('file://')) {
sourceMapPath = sourceMapUrl.replace('file://', '')
} else if (sourceMapUrl.startsWith('/')) {
sourceMapPath = sourceMapUrl
}
}
// 如果没有从 URL 获取，尝试默认路径
if (!sourceMapPath || !fs.existsSync(sourceMapPath)) {
const defaultPaths = [
path.join(projectRoot, `${platform}.bundle.map`),
path.join(projectRoot, 'index.bundle.map'),
path.join(projectRoot, 'bundle.map'),
]
sourceMapPath = defaultPaths.find(p => fs.existsSync(p))
}
if (!sourceMapPath || !fs.existsSync(sourceMapPath)) {
console.warn('[BugCollect] SourceMap file not found, skipping upload')
return result
}
// 异步上传（不阻塞构建）
uploadSourceMap(apiUrl, appKey, platform, appVersion, sourceMapPath).catch(err => {
console.warn('[BugCollect] SourceMap upload failed:', err.message)
})
} catch (err) {
console.warn('[BugCollect] SourceMap upload error:', err.message)
}
}
return result
},
},
}
}
module.exports = { withBugCollect }

4
packages/bugcollect/package.json
查看文件

@ -6,8 +6,10 @@
"main": "src/index.ts", "main": "src/index.ts",
"react-native": "src/index.ts", "react-native": "src/index.ts",
"types": "src/index.ts", "types": "src/index.ts",
"metro": "metro/index.js",
"files": [ "files": [
"src" "src",
"metro"
], ],
"private": false, "private": false,
"publishConfig": { "publishConfig": {

161
packages/bugcollect/src/BugCollect.ts
查看文件

@ -1,7 +1,5 @@
import { Platform, Dimensions } from 'react-native' import { Platform, Dimensions } from 'react-native'
import AsyncStorage from '@react-native-async-storage/async-storage' import { getConfig, isInitialized, getUserId } from '@xuqm/rn-common'
import { getConfig, hasPrivacyConsent, isInitialized, getUserId } from '@xuqm/rn-common'
import { _resolveBundleIdentity } from '@xuqm/rn-common/internal'
import { LogQueue } from './queue/LogQueue' import { LogQueue } from './queue/LogQueue'
import { ErrorCapture } from './capture/ErrorCapture' import { ErrorCapture } from './capture/ErrorCapture'
import { HttpInterceptor } from './interceptor/HttpInterceptor' import { HttpInterceptor } from './interceptor/HttpInterceptor'
@ -9,7 +7,6 @@ import { computeFingerprint } from './fingerprint'
import { FunnelTracker } from './funnel/FunnelTracker' import { FunnelTracker } from './funnel/FunnelTracker'
import { BUGCOLLECT_SDK_NAME, BUGCOLLECT_SDK_VERSION } from './sdkInfo' import { BUGCOLLECT_SDK_NAME, BUGCOLLECT_SDK_VERSION } from './sdkInfo'
import { ReportPolicy } from './reportPolicy' import { ReportPolicy } from './reportPolicy'
import { assertBugCollectPrivacyConsent, sanitizeDiagnostic } from './privacy'
import type { import type {
LogLevel, LogLevel,
Environment, Environment,
@ -31,12 +28,6 @@ let _queue: LogQueue | null = null
let _errorCaptureStarted = false let _errorCaptureStarted = false
let _httpInterceptorStarted = false let _httpInterceptorStarted = false
let _breadcrumbs: BreadcrumbItem[] = [] let _breadcrumbs: BreadcrumbItem[] = []
let _platformDisabled = false
const DISABLED_KEY_PREFIX = '@xuqm_bugcollect:disabled:'
function disabledKey(): string {
return `${DISABLED_KEY_PREFIX}${getConfig().appKey}`
}
const reportPolicy = new ReportPolicy() const reportPolicy = new ReportPolicy()
@ -102,69 +93,14 @@ function _getDeviceInfo(): DeviceInfo {
} }
} }
function _createQueue(): LogQueue { function _enqueue(event: BugCollectEvent): void {
const cfg = getConfig() if (!_queue) {
return new LogQueue({ const cfg = getConfig()
bugCollectApiUrl: cfg.bugCollectApiUrl, if (!cfg.bugCollectApiUrl || !cfg.bugCollectEnabled) return
appKey: cfg.appKey, _queue = new LogQueue({ bugCollectApiUrl: cfg.bugCollectApiUrl, appKey: cfg.appKey })
encryptionSecret: cfg.signingKey, }
onDisabled: () => {
_platformDisabled = true
void AsyncStorage.setItem(disabledKey(), 'true').catch(() => undefined)
stopCapture()
},
})
}
async function _withBundleIdentity(event: BugCollectEvent): Promise<BugCollectEvent> {
if (event.type !== 'issue') return event
const stacktrace = event.exception?.stacktrace
if (!stacktrace) return { ...event, symbolicationStatus: 'unavailable' }
const identity = await _resolveBundleIdentity(stacktrace).catch(() => null)
return identity
? { ...event, ...identity, symbolicationStatus: 'exact' }
: { ...event, symbolicationStatus: 'unavailable' }
}
async function _enqueue(event: BugCollectEvent): Promise<void> {
if (!_canCollect()) return
if (!_queue) _queue = _createQueue()
if (!_shouldReport(event)) return if (!_shouldReport(event)) return
const enriched = await _withBundleIdentity(event) void _queue.push(event)
await _queue?.push(sanitizeDiagnostic(enriched))
}
function _enqueueInBackground(event: BugCollectEvent): void {
void _enqueue(event).catch(() => undefined)
}
function _canCollect(): boolean {
if (!isInitialized() || !hasPrivacyConsent() || _platformDisabled) return false
const cfg = getConfig()
return !cfg.debug && cfg.bugCollectEnabled && Boolean(cfg.bugCollectApiUrl)
}
function startCapture(): void {
if (!_canCollect()) return
if (!_errorCaptureStarted) {
_errorCaptureStarted = true
ErrorCapture.start(BugCollect.captureError.bind(BugCollect))
}
if (!_httpInterceptorStarted) {
_httpInterceptorStarted = true
HttpInterceptor.start(BugCollect.captureError.bind(BugCollect))
}
}
function stopCapture(): void {
if (_errorCaptureStarted) {
ErrorCapture.stop()
_errorCaptureStarted = false
}
if (_httpInterceptorStarted) {
HttpInterceptor.stop()
_httpInterceptorStarted = false
}
} }
function _buildIssue(level: Level, error: unknown, metadata?: Record<string, unknown>): IssueEvent { function _buildIssue(level: Level, error: unknown, metadata?: Record<string, unknown>): IssueEvent {
@ -189,7 +125,6 @@ function _buildIssue(level: Level, error: unknown, metadata?: Record<string, unk
tags: metadata, tags: metadata,
device: _getDeviceInfo(), device: _getDeviceInfo(),
sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION }, sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION },
symbolicationStatus: 'unavailable',
} }
} }
@ -233,20 +168,20 @@ export const BugCollect = {
device: _getDeviceInfo(), device: _getDeviceInfo(),
sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION }, sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION },
} }
_enqueueInBackground(event) _enqueue(event)
FunnelTracker.track(name, properties) FunnelTracker.track(name, properties)
}, },
/** Upload a JS exception as an error-level issue. */ /** Upload a JS exception as an error-level issue. */
captureError(error: unknown, metadata?: Record<string, unknown>): void { captureError(error: unknown, metadata?: Record<string, unknown>): void {
if (!isInitialized()) return if (!isInitialized()) return
_enqueueInBackground(_buildIssue('error', error, metadata)) _enqueue(_buildIssue('error', error, metadata))
}, },
/** Upload a JS exception as a fatal-level issue (persisted across restarts). */ /** Upload a JS exception as a fatal-level issue (persisted across restarts). */
captureFatal(error: unknown, metadata?: Record<string, unknown>): void { captureFatal(error: unknown, metadata?: Record<string, unknown>): void {
if (!isInitialized()) return if (!isInitialized()) return
_enqueueInBackground(_buildIssue('fatal', error, metadata)) _enqueue(_buildIssue('fatal', error, metadata))
}, },
/** Log a warning (if log level allows). */ /** Log a warning (if log level allows). */
@ -268,9 +203,8 @@ export const BugCollect = {
sessionId: _sessionId, sessionId: _sessionId,
tags: metadata, tags: metadata,
sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION }, sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION },
symbolicationStatus: 'unavailable',
} }
_enqueueInBackground(issue) _enqueue(issue)
}, },
/** Log an informational event (if log level allows). */ /** Log an informational event (if log level allows). */
@ -291,34 +225,31 @@ export const BugCollect = {
sessionId: _sessionId, sessionId: _sessionId,
tags: metadata, tags: metadata,
sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION }, sdk: { name: BUGCOLLECT_SDK_NAME, version: BUGCOLLECT_SDK_VERSION },
symbolicationStatus: 'unavailable',
} }
_enqueueInBackground(issue) _enqueue(issue)
}, },
/** Debug 开发页的一次性测试入口；不改变真实隐私同意状态或自动采集开关。 */ /**
async sendTestErrorAndFlush(message = 'Xuqm BugCollect test error'): Promise<void> { * Enable automatic capture of JS global errors and unhandled Promise rejections,
if (!isInitialized()) throw new Error('[BugCollect] SDK is not initialized') * plus HTTP/接口报错 自动上报（包裹 global.fetch）。
assertBugCollectPrivacyConsent(hasPrivacyConsent()) * Call once at app startup after XuqmSDK.initialize().
const cfg = getConfig() */
if (!cfg.bugCollectEnabled || !cfg.bugCollectApiUrl || _platformDisabled) { startCapture(): void {
throw new Error('[BugCollect] Service is disabled') if (!_errorCaptureStarted) {
_errorCaptureStarted = true
ErrorCapture.start(BugCollect.captureError.bind(BugCollect))
} }
if (!_queue) { if (!_httpInterceptorStarted) {
_queue = _createQueue() _httpInterceptorStarted = true
HttpInterceptor.start(BugCollect.captureError.bind(BugCollect))
} }
const issue = await _withBundleIdentity(
_buildIssue('error', new Error(message), { testEvent: true }),
)
await _queue.push(sanitizeDiagnostic(issue))
await _queue.flush(true)
}, },
defineFunnel: FunnelTracker.define.bind(FunnelTracker), defineFunnel: FunnelTracker.define.bind(FunnelTracker),
getFunnelProgress: FunnelTracker.getProgress.bind(FunnelTracker), getFunnelProgress: FunnelTracker.getProgress.bind(FunnelTracker),
async flush(): Promise<void> { async flush(): Promise<void> {
if (_queue) await _queue.flush(true) if (_queue) await _queue.flush()
}, },
destroy(): void { destroy(): void {
@ -326,43 +257,11 @@ export const BugCollect = {
_queue.destroy() _queue.destroy()
_queue = null _queue = null
} }
stopCapture() if (_httpInterceptorStarted) {
HttpInterceptor.stop()
_httpInterceptorStarted = false
}
reportPolicy.clear() reportPolicy.clear()
_breadcrumbs = [] _breadcrumbs = []
}, },
} }
/** 仅供包内初始化/隐私生命周期使用，不从 package index 导出。 */
export const _BugCollectLifecycle = {
startCapture,
async applyEnabledConfig(authoritative: boolean): Promise<boolean> {
if (authoritative) {
_platformDisabled = false
await AsyncStorage.removeItem(disabledKey()).catch(() => undefined)
return true
}
_platformDisabled = (await AsyncStorage.getItem(disabledKey()).catch(() => null)) === 'true'
return !_platformDisabled
},
async disableAndClear(): Promise<void> {
_platformDisabled = true
if (isInitialized()) {
await AsyncStorage.setItem(disabledKey(), 'true').catch(() => undefined)
}
stopCapture()
await _queue?.clear()
if (isInitialized()) await LogQueue.clearStored(getConfig().appKey)
_queue?.destroy()
_queue = null
},
async clearPendingAndStop(): Promise<void> {
stopCapture()
await _queue?.clear()
if (isInitialized()) await LogQueue.clearStored(getConfig().appKey)
_queue?.destroy()
_queue = null
},
}

25
packages/bugcollect/src/capture/ErrorCapture.ts
查看文件

@ -11,41 +11,24 @@ declare const ErrorUtils: {
// React Native / Hermes exposes onunhandledrejection on globalThis // React Native / Hermes exposes onunhandledrejection on globalThis
type UnhandledRejectionHandler = ((event: { reason: unknown }) => void) | null | undefined type UnhandledRejectionHandler = ((event: { reason: unknown }) => void) | null | undefined
let previousErrorHandler: ((error: Error, isFatal?: boolean) => void) | null = null
let previousUnhandledHandler: UnhandledRejectionHandler = null
let started = false
export const ErrorCapture = { export const ErrorCapture = {
start(onError: (error: unknown, meta?: Record<string, unknown>) => void): void { start(onError: (error: unknown, meta?: Record<string, unknown>) => void): void {
if (started) return
started = true
// JS global error handler // JS global error handler
previousErrorHandler = typeof ErrorUtils !== 'undefined' ? ErrorUtils.getGlobalHandler() : null const prevError = typeof ErrorUtils !== 'undefined' ? ErrorUtils.getGlobalHandler() : null
if (typeof ErrorUtils !== 'undefined') { if (typeof ErrorUtils !== 'undefined') {
ErrorUtils.setGlobalHandler((error, isFatal) => { ErrorUtils.setGlobalHandler((error, isFatal) => {
onError(error, { isFatal: isFatal ?? false }) onError(error, { isFatal: isFatal ?? false })
previousErrorHandler?.(error, isFatal) prevError?.(error, isFatal)
}) })
} }
// Unhandled Promise rejection // Unhandled Promise rejection
const g = globalThis as unknown as Record<string, unknown> const g = globalThis as unknown as Record<string, unknown>
previousUnhandledHandler = (g['onunhandledrejection'] as UnhandledRejectionHandler) ?? null const prevUnhandled = (g['onunhandledrejection'] as UnhandledRejectionHandler) ?? null
g['onunhandledrejection'] = (event: { reason: unknown }) => { g['onunhandledrejection'] = (event: { reason: unknown }) => {
onError(event.reason, { type: 'unhandledRejection' }) onError(event.reason, { type: 'unhandledRejection' })
previousUnhandledHandler?.(event) prevUnhandled?.(event)
} }
}, },
stop(): void {
if (!started) return
if (typeof ErrorUtils !== 'undefined') {
ErrorUtils.setGlobalHandler(previousErrorHandler ?? (() => undefined))
}
const g = globalThis as unknown as Record<string, unknown>
g['onunhandledrejection'] = previousUnhandledHandler ?? null
previousErrorHandler = null
previousUnhandledHandler = null
started = false
},
} }

23
packages/bugcollect/src/index.ts
查看文件

@ -1,27 +1,12 @@
import { import { _registerInitializationHandler } from '@xuqm/rn-common/internal'
_registerInitializationHandler,
_registerPrivacyConsentHandler,
} from '@xuqm/rn-common/internal'
import { hasPrivacyConsent } from '@xuqm/rn-common'
import { _BugCollectLifecycle, BugCollect } from './BugCollect' import { BugCollect } from './BugCollect'
_registerInitializationHandler('rn-bugcollect', async config => { _registerInitializationHandler('rn-bugcollect', config => {
if (config.bugCollectEnabled && config.bugCollectApiUrl) { if (config.bugCollectEnabled && config.bugCollectApiUrl) {
const enabled = await _BugCollectLifecycle.applyEnabledConfig( BugCollect.startCapture()
config.configurationSource === 'remote',
)
if (enabled && hasPrivacyConsent() && !config.debug) _BugCollectLifecycle.startCapture()
else void _BugCollectLifecycle.clearPendingAndStop()
} else {
void _BugCollectLifecycle.disableAndClear()
} }
}) })
_registerPrivacyConsentHandler('rn-bugcollect', consented => {
if (consented) _BugCollectLifecycle.startCapture()
else return _BugCollectLifecycle.clearPendingAndStop()
})
export { BugCollect } export { BugCollect }
export type { LogLevel, Environment, LogEvent, IssueEvent, BugCollectEvent } from './types' export type { LogLevel, Environment, LogEvent, IssueEvent, BugCollectEvent } from './types'

43
packages/bugcollect/src/interceptor/HttpInterceptor.ts
查看文件

@ -10,32 +10,6 @@ type OnError = (error: unknown, meta?: Record<string, unknown>) => void
let _originalFetch: typeof fetch | null = null let _originalFetch: typeof fetch | null = null
function getRequestMetadata(input: RequestInfo | URL, init?: RequestInit) {
const rawUrl =
typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
let path: string
try {
path = new URL(rawUrl).pathname
} catch {
path = rawUrl.split(/[?#]/, 1)[0] ?? ''
}
return {
method: init?.method?.toUpperCase() ?? 'GET',
path,
type: 'api_error',
}
}
function isBugCollectRequest(input: RequestInfo | URL): boolean {
const rawUrl =
typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
try {
return new URL(rawUrl).pathname.includes('/bugcollect/')
} catch {
return rawUrl.includes('/bugcollect/')
}
}
export const HttpInterceptor = { export const HttpInterceptor = {
start(onError: OnError): void { start(onError: OnError): void {
if (_originalFetch) return // already installed if (_originalFetch) return // already installed
@ -48,20 +22,23 @@ export const HttpInterceptor = {
init?: RequestInit, init?: RequestInit,
): Promise<Response> => { ): Promise<Response> => {
const original = _originalFetch! const original = _originalFetch!
if (isBugCollectRequest(input)) return original(input, init)
try { try {
const res = await original(input, init) const res = await original(input, init)
if (!res.ok) { if (!res.ok) {
onError(new Error(`HTTP ${res.status}`), { const url =
...getRequestMetadata(input, init), typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
onError(new Error(`HTTP ${res.status} ${res.statusText}`), {
type: 'api_error',
url,
status: res.status, status: res.status,
}) })
} }
return res return res
} catch (error) { } catch (e) {
// fetch 抛出的对象可能携带原始 URL 或原生请求细节；采集端只接收固定错误和摘要。 const url =
onError(new Error('HTTP request failed'), getRequestMetadata(input, init)) typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
throw error onError(e, { type: 'api_error', url })
throw e
} }
} }
}, },

34
packages/bugcollect/src/privacy.ts
查看文件

@ -1,34 +0,0 @@
const SENSITIVE_KEY =
/authorization|cookie|token|secret|password|passwd|pin|idcard|identity|phone|mobile/i
const PHONE = /(?<!\d)1[3-9]\d{9}(?!\d)/g
const ID_CARD = /(?<![0-9A-Z])\d{17}[0-9X](?![0-9A-Z])/gi
const BEARER = /Bearer\s+[A-Za-z0-9._~+/=-]+/gi
export function assertBugCollectPrivacyConsent(consented: boolean): void {
if (!consented) {
throw new Error('[BugCollect] Privacy consent is required')
}
}
function sanitizeString(value: string): string {
return value
.replace(BEARER, 'Bearer [REDACTED]')
.replace(PHONE, '[PHONE]')
.replace(ID_CARD, '[ID_CARD]')
}
/** BugCollect 入队前的唯一深度脱敏实现，避免网络与持久化分支出现不同策略。 */
export function sanitizeDiagnostic<T>(value: T, seen = new WeakSet<object>()): T {
if (typeof value === 'string') return sanitizeString(value) as T
if (value === null || typeof value !== 'object') return value
if (seen.has(value)) return '[CIRCULAR]' as T
seen.add(value)
if (Array.isArray(value)) {
return value.map(item => sanitizeDiagnostic(item, seen)) as T
}
const result: Record<string, unknown> = {}
for (const [key, item] of Object.entries(value)) {
result[key] = SENSITIVE_KEY.test(key) ? '[REDACTED]' : sanitizeDiagnostic(item, seen)
}
return result as T
}

131
packages/bugcollect/src/queue/LogQueue.ts
查看文件

@ -2,50 +2,25 @@ import AsyncStorage from '@react-native-async-storage/async-storage'
import type { BugCollectEvent } from '../types' import type { BugCollectEvent } from '../types'
import { BUGCOLLECT_SDK_NAME, BUGCOLLECT_SDK_VERSION } from '../sdkInfo' import { BUGCOLLECT_SDK_NAME, BUGCOLLECT_SDK_VERSION } from '../sdkInfo'
import { shouldPersist } from './queuePolicy' import { shouldPersist } from './queuePolicy'
import { retryWithBackoff } from '@xuqm/rn-common'
import { const STORED_QUEUE_KEY = '@xuqm_bugcollect:queue'
clearStoredQueue,
isBugCollectDisabledPayload,
openQueue,
sealQueue,
storedQueueKey,
} from './queueStorage'
const BATCH_SIZE = 30 const BATCH_SIZE = 30
const FLUSH_INTERVAL_MS = 10_000 // 10 seconds const FLUSH_INTERVAL_MS = 10_000 // 10 seconds
const MAX_QUEUE_SIZE = 500 const MAX_QUEUE_SIZE = 500
const MAX_STORED_AGE_MS = 7 * 24 * 60 * 60 * 1_000 const MAX_RETRY = 3
const DISABLED_ERROR_CODE = 'BUGCOLLECT_DISABLED'
export class BugCollectDisabledError extends Error {
readonly name = 'BugCollectDisabledError'
readonly code = DISABLED_ERROR_CODE
}
export class LogQueue { export class LogQueue {
private _memory: BugCollectEvent[] = [] private _memory: BugCollectEvent[] = []
private flushTimer: ReturnType<typeof setInterval> | null = null private flushTimer: ReturnType<typeof setInterval> | null = null
private disabled = false private retryCount = 0
private flushPromise: Promise<void> | null = null
constructor( constructor(private cfg: { bugCollectApiUrl: string; appKey: string }) {
private cfg: {
bugCollectApiUrl: string
appKey: string
encryptionSecret?: string
onDisabled?: () => void | Promise<void>
},
) {
this.flushTimer = setInterval(() => { this.flushTimer = setInterval(() => {
void this.flush() void this.flush()
}, FLUSH_INTERVAL_MS) }, FLUSH_INTERVAL_MS)
} }
static async clearStored(appKey: string): Promise<void> {
await clearStoredQueue(AsyncStorage, appKey).catch(() => undefined)
}
async push(event: BugCollectEvent): Promise<void> { async push(event: BugCollectEvent): Promise<void> {
if (this.disabled) return
if (shouldPersist(event)) { if (shouldPersist(event)) {
const stored = await this._readStored() const stored = await this._readStored()
if (stored.length >= MAX_QUEUE_SIZE) stored.shift() if (stored.length >= MAX_QUEUE_SIZE) stored.shift()
@ -57,16 +32,7 @@ export class LogQueue {
} }
} }
async flush(throwOnFailure = false): Promise<void> { async flush(): Promise<void> {
if (this.flushPromise) return this.flushPromise
this.flushPromise = this._flushOnce(throwOnFailure).finally(() => {
this.flushPromise = null
})
return this.flushPromise
}
private async _flushOnce(throwOnFailure: boolean): Promise<void> {
if (this.disabled) return
const stored = await this._readStored() const stored = await this._readStored()
const combined = [...stored, ...this._memory] const combined = [...stored, ...this._memory]
if (combined.length === 0) return if (combined.length === 0) return
@ -75,38 +41,30 @@ export class LogQueue {
const storedUsed = Math.min(stored.length, BATCH_SIZE) const storedUsed = Math.min(stored.length, BATCH_SIZE)
const memUsed = batch.length - storedUsed const memUsed = batch.length - storedUsed
// Optimistically remove from sources before sending to avoid duplicates
await this._writeStored(stored.slice(storedUsed))
this._memory = this._memory.slice(memUsed)
const issues = batch.filter(e => e.type !== 'event') const issues = batch.filter(e => e.type !== 'event')
const events = batch.filter(e => e.type === 'event') const events = batch.filter(e => e.type === 'event')
try { try {
await retryWithBackoff( if (issues.length > 0) await this._post('/bugcollect/v1/issues/batch', issues)
async () => { if (events.length > 0) await this._post('/bugcollect/v1/events/batch', events)
if (issues.length > 0) await this._post('/bugcollect/v1/issues/batch', issues) this.retryCount = 0
if (events.length > 0) await this._post('/bugcollect/v1/events/batch', events) } catch {
}, this.retryCount++
{ if (this.retryCount < MAX_RETRY) {
maxAttempts: 3, // Re-queue only the persistent subset (re-queuing memory events would inflate duplicates)
shouldRetry: error => !(error instanceof BugCollectDisabledError), const toRequeue = batch.filter(shouldPersist)
}, if (toRequeue.length > 0) {
) const current = await this._readStored()
await this._writeStored(stored.slice(storedUsed)) await this._writeStored([...toRequeue, ...current])
this._memory = this._memory.slice(memUsed) }
} catch (error) {
if (error instanceof BugCollectDisabledError) {
this.disabled = true
await this.clear()
await this.cfg.onDisabled?.()
} }
// 后台上报失败由队列吸收；保留原队列，等待网络恢复或下次进程启动。
if (throwOnFailure) throw error
} }
} }
async clear(): Promise<void> {
this._memory = []
await AsyncStorage.removeItem(this.storageKey).catch(() => undefined)
}
destroy(): void { destroy(): void {
if (this.flushTimer !== null) { if (this.flushTimer !== null) {
clearInterval(this.flushTimer) clearInterval(this.flushTimer)
@ -129,57 +87,20 @@ export class LogQueue {
body, body,
}) })
if (!res.ok) { if (!res.ok) {
let code: string | undefined
let disabledByPlatform = false
try {
const payload = (await res.json()) as Record<string, unknown>
disabledByPlatform = isBugCollectDisabledPayload(payload)
code = String(payload.code ?? payload.errorCode ?? payload.message ?? '')
} catch {
// 非 JSON 错误由通用重试策略处理。
}
if (disabledByPlatform || code === DISABLED_ERROR_CODE) {
throw new BugCollectDisabledError()
}
throw new Error(`[BugCollect] Upload failed: ${res.status}`) throw new Error(`[BugCollect] Upload failed: ${res.status}`)
} }
} }
private get storageKey(): string {
return storedQueueKey(this.cfg.appKey)
}
private get storageContext(): string {
return `bugcollect-queue|${this.cfg.appKey}`
}
private async _readStored(): Promise<BugCollectEvent[]> { private async _readStored(): Promise<BugCollectEvent[]> {
const raw = await AsyncStorage.getItem(this.storageKey) const raw = await AsyncStorage.getItem(STORED_QUEUE_KEY)
if (!raw) return [] return raw ? (JSON.parse(raw) as BugCollectEvent[]) : []
if (!this.cfg.encryptionSecret) {
await AsyncStorage.removeItem(this.storageKey)
return []
}
try {
const cutoff = Date.now() - MAX_STORED_AGE_MS
return openQueue(raw, this.cfg.encryptionSecret, this.storageContext, cutoff)
} catch {
await AsyncStorage.removeItem(this.storageKey)
return []
}
} }
private async _writeStored(queue: BugCollectEvent[]): Promise<void> { private async _writeStored(queue: BugCollectEvent[]): Promise<void> {
if (queue.length === 0) { if (queue.length === 0) {
await AsyncStorage.removeItem(this.storageKey) await AsyncStorage.removeItem(STORED_QUEUE_KEY)
} else if (!this.cfg.encryptionSecret) {
// 没有签发密钥时绝不降级写入含栈和设备信息的明文持久队列。
await AsyncStorage.removeItem(this.storageKey)
} else { } else {
await AsyncStorage.setItem( await AsyncStorage.setItem(STORED_QUEUE_KEY, JSON.stringify(queue))
this.storageKey,
sealQueue(queue, this.cfg.encryptionSecret, this.storageContext),
)
} }
} }
} }

36
packages/bugcollect/src/queue/queueStorage.ts
查看文件

@ -1,36 +0,0 @@
import { openLocalCache, sealLocalCache } from '@xuqm/rn-common/secure-cache'
import type { BugCollectEvent } from '../types'
const STORED_QUEUE_KEY_PREFIX = '@xuqm_bugcollect:queue:'
export function storedQueueKey(appKey: string): string {
return `${STORED_QUEUE_KEY_PREFIX}${appKey}`
}
export async function clearStoredQueue(
storage: { removeItem(key: string): Promise<unknown> },
appKey: string,
): Promise<void> {
await storage.removeItem(storedQueueKey(appKey))
}
export function sealQueue(queue: BugCollectEvent[], secret: string, context: string): string {
return sealLocalCache(JSON.stringify(queue), secret, context)
}
export function openQueue(
payload: string,
secret: string,
context: string,
cutoff: number,
): BugCollectEvent[] {
const parsed = JSON.parse(openLocalCache(payload, secret, context)) as BugCollectEvent[]
if (!Array.isArray(parsed)) throw new Error('BugCollect queue payload is not an array')
return parsed.filter(event => Number.isFinite(event.timestamp) && event.timestamp >= cutoff)
}
export function isBugCollectDisabledPayload(payload: Record<string, unknown>): boolean {
return [payload.code, payload.errorCode, payload.message]
.map(value => String(value ?? ''))
.includes('BUGCOLLECT_DISABLED')
}

6
packages/bugcollect/src/types.ts
查看文件

@ -79,12 +79,6 @@ export interface IssueEvent {
device?: DeviceInfo device?: DeviceInfo
tags?: Record<string, unknown> tags?: Record<string, unknown>
sdk?: SdkInfo sdk?: SdkInfo
/** 四项齐全时服务端才允许精确 Source Map 符号化。 */
buildId?: string
moduleId?: string
moduleVersion?: string
bundleHash?: string
symbolicationStatus: 'exact' | 'unavailable'
} }
export type BugCollectEvent = LogEvent | IssueEvent export type BugCollectEvent = LogEvent | IssueEvent

52
packages/bugcollect/tests/http-interceptor.test.ts
查看文件

@ -1,52 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { HttpInterceptor } from '../src/interceptor/HttpInterceptor'
test('HTTP interception removes host, query and request contents before reporting', async () => {
const originalFetch = globalThis.fetch
const reports: Array<{ error: unknown; metadata?: Record<string, unknown> }> = []
globalThis.fetch = async () => new Response(null, { status: 500 })
try {
HttpInterceptor.start((error, metadata) => reports.push({ error, metadata }))
await globalThis.fetch('https://api.example.com/am/user?phone=13800000000&token=secret', {
body: JSON.stringify({ userId: 'secret-user' }),
headers: { authorization: 'secret-authorization' },
method: 'POST',
})
} finally {
HttpInterceptor.stop()
globalThis.fetch = originalFetch
}
assert.equal(reports.length, 1)
assert.deepEqual(reports[0]?.metadata, {
method: 'POST',
path: '/am/user',
status: 500,
type: 'api_error',
})
const serialized = JSON.stringify(reports)
assert.doesNotMatch(serialized, /example\.com|13800000000|token|secret|authorization|userId/)
})
test('BugCollect transport failures are excluded to prevent recursive reporting', async () => {
const originalFetch = globalThis.fetch
const reports: unknown[] = []
globalThis.fetch = async () => new Response(null, { status: 503 })
try {
HttpInterceptor.start(error => reports.push(error))
const response = await globalThis.fetch(
'https://bugcollect.example.com/bugcollect/v1/issues/batch',
{ method: 'POST' },
)
assert.equal(response.status, 503)
} finally {
HttpInterceptor.stop()
globalThis.fetch = originalFetch
}
assert.deepEqual(reports, [])
})

1
packages/bugcollect/tests/policy.test.ts
查看文件

@ -44,7 +44,6 @@ test('fatal and error issues are the only events persisted for restart recovery'
exception: { type: 'Error', value: 'value' }, exception: { type: 'Error', value: 'value' },
sessionId: 'session', sessionId: 'session',
sdk: { name: 'bugcollect.rn', version: '1.0.0' }, sdk: { name: 'bugcollect.rn', version: '1.0.0' },
symbolicationStatus: 'unavailable',
} as const } as const
assert.equal(shouldPersist({ ...base, level: 'fatal' } as BugCollectEvent), true) assert.equal(shouldPersist({ ...base, level: 'fatal' } as BugCollectEvent), true)
assert.equal(shouldPersist({ ...base, level: 'error' } as BugCollectEvent), true) assert.equal(shouldPersist({ ...base, level: 'error' } as BugCollectEvent), true)

22
packages/bugcollect/tests/privacy.test.ts
查看文件

@ -1,22 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { assertBugCollectPrivacyConsent, sanitizeDiagnostic } from '../src/privacy'
test('diagnostic sanitization removes secrets and common identity values recursively', () => {
const sanitized = sanitizeDiagnostic({
authorization: 'Bearer secret-token',
nested: {
message: 'phone=13800138000 id=110101199001011234',
token: 'secret',
},
})
const serialized = JSON.stringify(sanitized)
assert.doesNotMatch(serialized, /secret-token|13800138000|110101199001011234|"secret"/)
assert.match(serialized, /REDACTED|PHONE|ID_CARD/)
})
test('manual BugCollect test upload still requires privacy consent', () => {
assert.throws(() => assertBugCollectPrivacyConsent(false), /Privacy consent is required/)
assert.doesNotThrow(() => assertBugCollectPrivacyConsent(true))
})

58
packages/bugcollect/tests/queue-storage.test.ts
查看文件

@ -1,58 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import {
clearStoredQueue,
isBugCollectDisabledPayload,
openQueue,
sealQueue,
} from '../src/queue/queueStorage'
import type { IssueEvent } from '../src/types'
const issue: IssueEvent = {
type: 'issue',
level: 'error',
platform: 'android',
fingerprint: 'fingerprint',
timestamp: 1_000,
appKey: 'app',
release: '8.0.0',
exception: { type: 'Error', value: 'secret', stacktrace: 'private stack' },
symbolicationStatus: 'unavailable',
}
test('persistent queue is encrypted, context-bound and tamper-evident', () => {
const encrypted = sealQueue([issue], 'signing-key', 'bugcollect-queue|app')
assert.equal(encrypted.includes('private stack'), false)
assert.deepEqual(openQueue(encrypted, 'signing-key', 'bugcollect-queue|app', 0), [issue])
assert.throws(() => openQueue(encrypted, 'signing-key', 'bugcollect-queue|other', 0))
const parts = encrypted.split('.')
parts[2] = `${parts[2][0] === 'A' ? 'B' : 'A'}${parts[2].slice(1)}`
assert.throws(() => openQueue(parts.join('.'), 'signing-key', 'bugcollect-queue|app', 0))
})
test('platform disabled response recognizes the deployed message contract', () => {
assert.equal(
isBugCollectDisabledPayload({
code: 403,
status: '1',
message: 'BUGCOLLECT_DISABLED',
}),
true,
)
assert.equal(isBugCollectDisabledPayload({ code: 'BUGCOLLECT_DISABLED' }), true)
assert.equal(isBugCollectDisabledPayload({ code: 403, message: 'forbidden' }), false)
})
test('cold-start disable removes a persisted queue before LogQueue is created', async () => {
const removed: string[] = []
await clearStoredQueue(
{
async removeItem(key) {
removed.push(key)
},
},
'app',
)
assert.deepEqual(removed, ['@xuqm_bugcollect:queue:app'])
})

25
packages/common/README.md
查看文件

@ -25,8 +25,7 @@ const state = expirationStatus('2027-01-01T00:00:00Z')
## 扩展包自动初始化 ## 扩展包自动初始化
把平台生成的加密配置原名放到 `src/assets/config/`（目录内只能有一个 把平台生成的加密配置放到 `src/assets/config/config.xuqmconfig`，并只包装一次 Metro 配置：
`.xuqmconfig`），并只包装一次 Metro 配置：
```js ```js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config') const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config')
@ -39,15 +38,19 @@ module.exports = withXuqmConfig(
) )
``` ```
使用 update、bugcollect、xwebview 等扩展包时，`withXuqmConfig()` 会在 Node/Metro 构建进程中解密配置，生成只读的虚拟配置模块，并把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 `inlineRequires` 影响。Metro 插件还会把同一份加密配置同步到 Android assets；宿主不需要在多个位置维护副本。PBKDF2 与 AES-GCM 解密不在 Hermes 启动线程执行，应用启动时只消费构建已经解析的配置并发起共享初始化。 使用 update、bugcollect、xwebview 等扩展包时，`withXuqmConfig()` 会把 common 的初始化入口注册为 Metro pre-main module，确保初始化早于业务入口且不受 `inlineRequires` 影响。Metro 插件还会把同一份配置同步到 Android assets；宿主不需要在多个位置维护副本。
common-only 项目不要放置 `.xuqmconfig`，也不要使用 `withXuqmConfig()`，即可保持零初始化。是否初始化只由这一条规则决定，不提供手动初始化、额外 alias 或多套配置约定。 common-only 项目不要放置 `.xuqmconfig`，也不要使用 `withXuqmConfig()`，即可保持零初始化。是否初始化只由这一条规则决定，不提供额外 alias 或多套配置约定。
Metro 预加载发起的自动初始化如果因临时网络或 DNS 问题失败，common 会终止该 Promise，避免形成未处理异常。随后第一个真正需要配置的扩展调用共享 `awaitInitialization()` 时，会使用同一份已解析配置重新尝试；配置、appKey 和平台地址不需要由页面或子 SDK 再次传入。持续失败由宿主入口统一记录一次，SDK 不重复打印同一错误。构建期配置损坏、密钥不匹配或 Schema 非法会直接阻断构建，禁止打出运行时才失败的安装包。 无法使用配置文件时，才调用一次手动初始化：
平台远程配置中的 `features.update` 是 Update 服务开关；兼容字段 ```ts
`updateEnabled` 只在前者缺失时读取。两者都缺失时安全默认关闭，最后成功配置缓存会 await XuqmSDK.initialize({ appKey: 'app-key' })
原样保存开关值。关闭 Update 不影响 common、宿主业务或其它扩展 SDK。 ```
同一配置的并发初始化会复用同一个 Promise；重复使用不同配置会直接报错。
Metro 预加载发起的自动初始化如果因临时网络或 DNS 问题失败，common 会终止该 Promise，避免形成未处理异常。随后第一个真正需要配置的扩展调用共享 `awaitInitialization()` 时，会使用同一份加密配置重新尝试；配置、appKey 和平台地址不需要由页面或子 SDK 再次传入。持续失败由宿主入口统一记录一次，SDK 不重复打印同一错误。
## 扩展包的唯一登录入口 ## 扩展包的唯一登录入口
@ -77,11 +80,7 @@ await XuqmSDK.logout()
- `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`：统一时间解析与过期判断。 - `expirationStatus`、`toTimestamp`、`millisecondsUntil`、`formatDateTime`：统一时间解析与过期判断。
- `formatNumericDateTime`：为 API 参数和固定数字布局提供不受 locale 标点/顺序影响的本地时间格式，调用方通过选项控制日期、时间、秒和分隔符。 - `formatNumericDateTime`：为 API 参数和固定数字布局提供不受 locale 标点/顺序影响的本地时间格式，调用方通过选项控制日期、时间、秒和分隔符。
- `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`、`registerAndroidDownloadedFile`：统一文件与 Android 下载登记操作。 - `fileExists`、`ensureDirectory`、`readFileAsBase64`、`writeBase64File`、`openLocalFile`、`registerAndroidDownloadedFile`：统一文件与 Android 下载登记操作。
- `hmacSha256Base64Url`、`sha256Hex`：签名与文件摘要使用的统一实现。平台签发的 - `decryptXuqmFile`、`hmacSha256Base64Url`：基于 `@noble/*` 的跨平台加密实现。
`.xuqmconfig` 只允许由 Metro 构建插件验签和解析，不向运行时暴露通用解密 API。
- `getDeviceInfo`、`getDeviceId`、`useApi`、`usePageApi`、`showToast` 等项目通用能力。 - `getDeviceInfo`、`getDeviceId`、`useApi`、`usePageApi`、`showToast` 等项目通用能力。
业务代码不得导入 `@xuqm/rn-common/internal`。该子路径仅供官方 `@xuqm` 扩展包接入公共生命周期。 业务代码不得导入 `@xuqm/rn-common/internal`。该子路径仅供官方 `@xuqm` 扩展包接入公共生命周期。
`internal-security` 同样只供官方扩展使用：配置 V2 和插件不可变 manifest 复用一份
canonical JSON（键排序、无空白、null/undefined 字段省略）与可信 Ed25519 keyId
集合，不是宿主可替换的通用验签入口。

218
packages/common/metro/index.js
查看文件

@ -6,144 +6,42 @@
* 宿主只需将平台下载的 .xuqmconfig 文件放入 src/assets/config/， * 宿主只需将平台下载的 .xuqmconfig 文件放入 src/assets/config/，
* SDK 自动读取并完成初始化，无需重命名或创建 .ts 包装文件。 * SDK 自动读取并完成初始化，无需重命名或创建 .ts 包装文件。
* *
* 目录内没有配置时保持 common-only；唯一一个 *.xuqmconfig 自动使用；多个文件 * 对齐 Android SDK 的 ConfigFileReader 逻辑：
* 无法判断权威配置，必须在构建期明确失败。 * 优先 config.xuqmconfig，否则取第一个 *.xuqmconfig。
* *
* @param {import('@react-native/metro-config').MetroConfig} metroConfig * @param {import('@react-native/metro-config').MetroConfig} metroConfig
* @returns {import('@react-native/metro-config').MetroConfig} * @returns {import('@react-native/metro-config').MetroConfig}
*/ */
const fs = require('fs') const fs = require('fs')
const path = require('path') const path = require('path')
const crypto = require('node:crypto')
const VIRTUAL_MODULE_ID = '@xuqm/rn-common/auto-init-config' const VIRTUAL_MODULE_ID = '@xuqm/autoinit-config'
const AUTO_INIT_MODULE = path.resolve(__dirname, '../src/internal.ts') const AUTO_INIT_MODULE = path.resolve(__dirname, '../src/internal.ts')
const CONFIG_DIRECTORY_RELATIVE_PATH = 'src/assets/config' const CONFIG_DIR_CANDIDATES = [
const CONFIG_MAGIC = 'XUQM-CONFIG-V2' 'src/assets/config',
const CONFIG_PASSPHRASE = 'xuqm-config-file-v2.2026.internal' 'src/assets/xuqm',
const PBKDF2_ITERATIONS = 120_000 'assets/config',
const TRUSTED_CONFIG_KEYS = require('../security/trusted-signing-keys.json') 'assets/xuqm',
const { canonicalJson } = require('../security/canonical-json.js') ]
const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
function decodeBase64Url(value) {
return Buffer.from(value, 'base64url')
}
/**
* 配置文件只在 Node/Metro 构建期解密。移动端运行时直接消费解析后的配置，
* 避免 Hermes 在应用启动阶段执行 12 万次 PBKDF2 并阻塞 JS 线程。
*/
function assertConfigPayload(config, plaintext) {
const allowedFields = new Set([
'schemaVersion',
'configId',
'revision',
'issuedAt',
'expiresAt',
'appKey',
'appName',
'packageName',
'iosBundleId',
'harmonyBundleName',
'serverUrl',
'signingKey',
])
const unknownField = Object.keys(config).find(field => !allowedFields.has(field))
if (unknownField) throw new Error(`配置包含不受支持字段：${unknownField}`)
if (config.schemaVersion !== 2) throw new Error('配置 schemaVersion 必须为 2')
if (
typeof config.configId !== 'string' ||
!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
config.configId,
)
) {
throw new Error('配置 configId 不是有效 UUID')
}
if (!Number.isInteger(config.revision) || config.revision <= 0) {
throw new Error('配置 revision 必须为正整数')
}
for (const field of ['issuedAt', 'appKey', 'appName', 'serverUrl', 'signingKey']) {
if (typeof config[field] !== 'string' || !config[field].trim()) {
throw new Error(`配置 ${field} 不能为空`)
}
}
if (!config.issuedAt.endsWith('Z') || Number.isNaN(Date.parse(config.issuedAt))) {
throw new Error('配置 issuedAt 必须为 RFC3339 UTC 时间')
}
if (config.expiresAt !== undefined) {
const expiresAt = Date.parse(config.expiresAt)
if (!config.expiresAt.endsWith('Z') || Number.isNaN(expiresAt)) {
throw new Error('配置 expiresAt 必须为 RFC3339 UTC 时间')
}
if (expiresAt <= Date.now()) throw new Error('配置文件已过期，请从租户平台重新生成')
}
if (canonicalJson(config) !== plaintext) {
throw new Error('配置正文不是规范 canonical JSON')
}
}
function decryptConfigAtBuildTime(content, trustedKeys = TRUSTED_CONFIG_KEYS) {
const parts = content.trim().split('.')
if (parts.length !== 6 || parts[0] !== CONFIG_MAGIC) {
throw new Error('仅支持 XUQM-CONFIG-V2；请从租户平台重新下载配置文件')
}
const keyId = parts[1]
const publicKeyBase64 = trustedKeys[keyId]
if (!publicKeyBase64) throw new Error(`配置签名 keyId 不受信任：${keyId}`)
const unsignedToken = parts.slice(0, 5).join('.')
const signatureValid = crypto.verify(
null,
Buffer.from(unsignedToken, 'ascii'),
{
key: Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(publicKeyBase64, 'base64')]),
format: 'der',
type: 'spki',
},
decodeBase64Url(parts[5]),
)
if (!signatureValid) throw new Error('配置文件签名验证失败')
const salt = decodeBase64Url(parts[2])
const iv = decodeBase64Url(parts[3])
const encrypted = decodeBase64Url(parts[4])
if (salt.length === 0 || iv.length !== 12 || encrypted.length <= 16) {
throw new Error('配置文件加密参数无效')
}
const body = encrypted.subarray(0, -16)
const authTag = encrypted.subarray(-16)
const key = crypto.pbkdf2Sync(CONFIG_PASSPHRASE, salt, PBKDF2_ITERATIONS, 32, 'sha256')
const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv)
decipher.setAuthTag(authTag)
try {
const plaintext = Buffer.concat([decipher.update(body), decipher.final()])
const text = plaintext.toString('utf8')
const config = JSON.parse(text)
assertConfigPayload(config, text)
return config
} catch {
throw new Error('配置文件解密或内容校验失败')
}
}
function findConfigFile(projectRoot) { function findConfigFile(projectRoot) {
const configDirectory = path.resolve(projectRoot, CONFIG_DIRECTORY_RELATIVE_PATH) for (const dir of CONFIG_DIR_CANDIDATES) {
if (!fs.existsSync(configDirectory)) return null const absDir = path.resolve(projectRoot, dir)
const candidates = fs if (!fs.existsSync(absDir)) continue
.readdirSync(configDirectory, { withFileTypes: true })
.filter(entry => entry.isFile() && entry.name.toLowerCase().endsWith('.xuqmconfig')) const files = fs.readdirSync(absDir)
.map(entry => path.join(configDirectory, entry.name)) // 优先 config.xuqmconfig 或 config.xuqm
.sort() const preferred = files.find(f => f === 'config.xuqmconfig' || f === 'config.xuqm')
if (candidates.length === 0) return null if (preferred) {
if (candidates.length > 1) { return path.join(absDir, preferred)
throw new Error( }
`[XuqmConfig] ${configDirectory}: 只能存在一个 .xuqmconfig 文件，当前发现 ${candidates.length} 个`, // 否则取第一个 .xuqmconfig
) const fallback = files.find(f => f.endsWith('.xuqmconfig'))
if (fallback) {
return path.join(absDir, fallback)
}
} }
return candidates[0] return null
} }
function applyBugCollect(metroConfig) { function applyBugCollect(metroConfig) {
@ -153,6 +51,56 @@ function applyBugCollect(metroConfig) {
return metroConfig return metroConfig
} }
/** 写入目标文件（仅在缺失或内容不一致时），返回是否发生写入。 */
function syncFile(content, destPath, label) {
try {
if (fs.existsSync(destPath) && fs.readFileSync(destPath, 'utf-8').trim() === content) {
return false
}
fs.mkdirSync(path.dirname(destPath), { recursive: true })
fs.writeFileSync(destPath, content, 'utf-8')
console.log(`[XuqmConfig] 已同步 .xuqmconfig → ${label}`)
return true
} catch (e) {
console.warn(`[XuqmConfig] 同步 .xuqmconfig 到 ${label} 失败：${e.message}`)
return false
}
}
/**
* 单点放置：宿主只在 RN 侧放置一份 .xuqmconfig，构建/运行时自动同步到
* 原生位置（Android assets/config，供 XuqmMergedProvider 自动初始化；iOS 资源目录）。
* 缺失或内容不一致才复制，幂等。
*/
function syncNativeConfig(projectRoot, content) {
const fileName = 'config.xuqmconfig'
// Android：原生 ContentProvider 扫描 assets/config 下的 .xuqmconfig
if (fs.existsSync(path.resolve(projectRoot, 'android'))) {
syncFile(
content,
path.resolve(projectRoot, 'android/app/src/main/assets/config', fileName),
'android assets/config',
)
}
// iOS：复制到 app 资源目录（需在 Xcode「Copy Bundle Resources」中引用一次）
const iosDir = path.resolve(projectRoot, 'ios')
if (fs.existsSync(iosDir)) {
try {
const appDir = fs
.readdirSync(iosDir, { withFileTypes: true })
.filter(d => d.isDirectory() && fs.existsSync(path.join(iosDir, d.name, 'Info.plist')))
.map(d => d.name)[0]
if (appDir) {
syncFile(content, path.join(iosDir, appDir, 'config', fileName), `ios ${appDir}/config`)
}
} catch {
// 忽略 iOS 同步异常，不阻断打包
}
}
}
function withXuqmConfig(metroConfig) { function withXuqmConfig(metroConfig) {
const projectRoot = metroConfig.projectRoot ?? process.cwd() const projectRoot = metroConfig.projectRoot ?? process.cwd()
const configFile = findConfigFile(projectRoot) const configFile = findConfigFile(projectRoot)
@ -165,14 +113,10 @@ function withXuqmConfig(metroConfig) {
// 读取加密配置内容 // 读取加密配置内容
const encryptedContent = fs.readFileSync(configFile, 'utf-8').trim() const encryptedContent = fs.readFileSync(configFile, 'utf-8').trim()
let resolvedConfig // 单点放置：自动同步到原生 Android/iOS（缺失或不一致才复制）
try { syncNativeConfig(projectRoot, encryptedContent)
resolvedConfig = decryptConfigAtBuildTime(encryptedContent)
} catch (error) {
throw new Error(`[XuqmConfig] ${configFile}: ${error.message}`)
}
// 生成临时 TS 文件作为虚拟模块。这里只传输已解析对象，移动端不再解密。 // 生成临时 TS 文件作为虚拟模块
// Metro 0.84+ only hashes files under projectRoot/watchFolders. Keep the // Metro 0.84+ only hashes files under projectRoot/watchFolders. Keep the
// generated transport module in the ignored package-manager cache instead // generated transport module in the ignored package-manager cache instead
// of the system temp directory; the .xuqmconfig file remains the sole source. // of the system temp directory; the .xuqmconfig file remains the sole source.
@ -181,11 +125,11 @@ function withXuqmConfig(metroConfig) {
const virtualFile = path.join(generatedDir, 'autoinit-config.ts') const virtualFile = path.join(generatedDir, 'autoinit-config.ts')
fs.writeFileSync( fs.writeFileSync(
virtualFile, virtualFile,
`// Auto-generated by @xuqm/rn-common/metro — do not edit\nexport const RESOLVED_CONFIG = ${JSON.stringify(resolvedConfig)} as const;\nexport const BUILD_OPTIONS = ${JSON.stringify({ bugCollectMode: process.env.XUQM_BUGCOLLECT_MODE ?? 'platform' })} as const;\n`, `// Auto-generated by @xuqm/rn-common/metro — do not edit\nexport const ENCRYPTED_CONFIG = ${JSON.stringify(encryptedContent)};\n`,
'utf-8', 'utf-8',
) )
// 拦截默认空实现，将 @xuqm/rn-common/auto-init-config 指向虚拟文件 // 拦截模块解析，将 @xuqm/autoinit-config 指向虚拟文件
const existingResolveRequest = metroConfig.resolver?.resolveRequest const existingResolveRequest = metroConfig.resolver?.resolveRequest
const existingGetModulesRunBeforeMainModule = const existingGetModulesRunBeforeMainModule =
metroConfig.serializer?.getModulesRunBeforeMainModule metroConfig.serializer?.getModulesRunBeforeMainModule
@ -221,4 +165,4 @@ function withXuqmConfig(metroConfig) {
}) })
} }
module.exports = { decryptConfigAtBuildTime, findConfigFile, withXuqmConfig } module.exports = { withXuqmConfig }

19
packages/common/package.json
查看文件

@ -8,22 +8,18 @@
"types": "src/index.ts", "types": "src/index.ts",
"exports": { "exports": {
".": "./src/index.ts", ".": "./src/index.ts",
"./auto-init-config": "./src/autoInitConfig.ts",
"./crypto": "./src/crypto.ts", "./crypto": "./src/crypto.ts",
"./download": "./src/download.ts", "./download": "./src/download.ts",
"./file-name": "./src/fileName.ts", "./file-name": "./src/fileName.ts",
"./internal": "./src/internal.ts", "./internal": "./src/internal.ts",
"./internal-security": "./src/internalSecurity.ts",
"./metro": "./metro/index.js", "./metro": "./metro/index.js",
"./package.json": "./package.json", "./package.json": "./package.json",
"./secure-cache": "./src/secureCache.ts",
"./version": "./src/version.ts" "./version": "./src/version.ts"
}, },
"metro": "metro/index.js", "metro": "metro/index.js",
"files": [ "files": [
"src", "src",
"metro", "metro"
"security"
], ],
"private": false, "private": false,
"publishConfig": { "publishConfig": {
@ -35,7 +31,6 @@
}, },
"dependencies": { "dependencies": {
"@noble/ciphers": "2.2.0", "@noble/ciphers": "2.2.0",
"@noble/curves": "2.2.0",
"@noble/hashes": "2.2.0", "@noble/hashes": "2.2.0",
"@types/semver": "7.7.1", "@types/semver": "7.7.1",
"react-native-blob-util": "0.24.10", "react-native-blob-util": "0.24.10",
@ -43,18 +38,18 @@
"zod": "4.4.3" "zod": "4.4.3"
}, },
"peerDependencies": { "peerDependencies": {
"@react-native-async-storage/async-storage": ">=1.21.0",
"axios": ">=1.0.0",
"react": ">=18.0.0", "react": ">=18.0.0",
"react-native": ">=0.76.0" "react-native": ">=0.76.0",
"@react-native-async-storage/async-storage": ">=1.21.0",
"axios": ">=1.0.0"
}, },
"devDependencies": { "devDependencies": {
"@react-native-async-storage/async-storage": "^3.1.1", "typescript": "catalog:",
"@types/react": "^19.2.14", "@types/react": "^19.2.14",
"@react-native-async-storage/async-storage": "^3.1.1",
"axios": "^1.18.0", "axios": "^1.18.0",
"react": "19.2.7", "react": "19.2.7",
"react-native": "0.86.0", "react-native": "0.86.0",
"tsx": "^4.23.1", "tsx": "^4.23.1"
"typescript": "catalog:"
} }
} }

5
packages/common/security/base64.d.ts vendored
查看文件

@ -1,5 +0,0 @@
export function decodeBase64(value: string): Uint8Array
export function encodeBase64(
value: Uint8Array,
options?: { urlSafe?: boolean; padding?: boolean },
): string

85
packages/common/security/base64.js
查看文件

@ -1,85 +0,0 @@
'use strict'
const STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
const URL_SAFE_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_'
/**
* 纯 JS Base64 编码，默认输出带填充的标准 Base64。
* 协议调用方必须显式声明 URL-safe 与是否保留填充，避免现场字符串替换。
*/
function encodeBase64(value, options = {}) {
if (!(value instanceof Uint8Array)) throw new TypeError('Base64 value must be Uint8Array')
const alphabet = options.urlSafe ? URL_SAFE_ALPHABET : STANDARD_ALPHABET
const padding = options.padding !== false
let output = ''
for (let offset = 0; offset < value.length; offset += 3) {
const first = value[offset]
const hasSecond = offset + 1 < value.length
const hasThird = offset + 2 < value.length
const second = hasSecond ? value[offset + 1] : 0
const third = hasThird ? value[offset + 2] : 0
output += alphabet[first >>> 2]
output += alphabet[((first & 0x03) << 4) | (second >>> 4)]
if (hasSecond) {
output += alphabet[((second & 0x0f) << 2) | (third >>> 6)]
} else if (padding) {
output += '='
}
if (hasThird) {
output += alphabet[third & 0x3f]
} else if (padding) {
output += '='
}
}
return output
}
/**
* 严格解码标准 Base64 或 Base64URL，不依赖浏览器/Hermes 的 atob。
* 接受有填充或无填充形式，但拒绝混合字母表、非法长度、非法填充和非零尾随位。
*/
function decodeBase64(value) {
if (typeof value !== 'string') throw new TypeError('Base64 value must be a string')
if (value.length === 0) return new Uint8Array(0)
if (/[^A-Za-z0-9+/_=-]/.test(value)) throw new Error('Base64 contains invalid characters')
if (/[+\/]/.test(value) && /[-_]/.test(value)) {
throw new Error('Base64 cannot mix standard and URL-safe alphabets')
}
const firstPadding = value.indexOf('=')
const data = firstPadding === -1 ? value : value.slice(0, firstPadding)
const padding = firstPadding === -1 ? '' : value.slice(firstPadding)
if (padding !== '' && padding !== '=' && padding !== '==') {
throw new Error('Base64 padding is invalid')
}
if (data.includes('=')) throw new Error('Base64 padding is invalid')
const remainder = data.length % 4
if (remainder === 1) throw new Error('Base64 length is invalid')
const expectedPadding = remainder === 0 ? 0 : 4 - remainder
if (padding.length !== 0 && padding.length !== expectedPadding) {
throw new Error('Base64 padding length is invalid')
}
const normalized = data.replace(/-/g, '+').replace(/_/g, '/')
const outputLength = Math.floor((normalized.length * 6) / 8)
const output = new Uint8Array(outputLength)
let accumulator = 0
let bitCount = 0
let outputIndex = 0
for (const character of normalized) {
const sextet = STANDARD_ALPHABET.indexOf(character)
if (sextet < 0) throw new Error('Base64 contains invalid characters')
accumulator = (accumulator << 6) | sextet
bitCount += 6
if (bitCount >= 8) {
bitCount -= 8
output[outputIndex] = (accumulator >>> bitCount) & 0xff
outputIndex += 1
accumulator &= (1 << bitCount) - 1
}
}
if (accumulator !== 0) throw new Error('Base64 has non-zero trailing bits')
return output
}
module.exports = { decodeBase64, encodeBase64 }

1
packages/common/security/canonical-json.d.ts vendored
查看文件

@ -1 +0,0 @@
export function canonicalJson(value: unknown): string

46
packages/common/security/canonical-json.js
查看文件

@ -1,46 +0,0 @@
'use strict'
/**
* 安全协议唯一使用的 canonical JSON。对象键按字典序排列，null/undefined 字段省略；
* 非 JSON 协议值、数组空位和不确定的对象形态直接拒绝。
*/
function canonicalJson(value) {
if (value === null) return 'null'
if (typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value)
if (typeof value === 'number') {
if (!Number.isFinite(value)) throw new TypeError('Canonical JSON requires finite numbers')
return JSON.stringify(value)
}
if (Array.isArray(value)) {
for (let index = 0; index < value.length; index += 1) {
if (!Object.prototype.hasOwnProperty.call(value, index) || value[index] === undefined) {
throw new TypeError('Canonical JSON arrays cannot contain holes or undefined')
}
}
return `[${value.map(canonicalJson).join(',')}]`
}
if (value && typeof value === 'object') {
const prototype = Object.getPrototypeOf(value)
if (prototype !== Object.prototype && prototype !== null) {
throw new TypeError('Canonical JSON only supports plain objects')
}
const keys = Reflect.ownKeys(value)
if (keys.some(key => typeof key === 'symbol')) {
throw new TypeError('Canonical JSON does not support symbol keys')
}
for (const key of keys) {
const descriptor = Object.getOwnPropertyDescriptor(value, key)
if (!descriptor?.enumerable || !('value' in descriptor)) {
throw new TypeError('Canonical JSON only supports enumerable data properties')
}
}
return `{${keys
.filter(key => value[key] !== null && value[key] !== undefined)
.sort()
.map(key => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
.join(',')}}`
}
throw new TypeError(`Canonical JSON does not support ${typeof value}`)
}
module.exports = { canonicalJson }

3
packages/common/security/trusted-signing-keys.json
查看文件

@ -1,3 +0,0 @@
{
"xuqm-config-dev-2026-07": "Ft9MBN8jNwCfalex4wg7kuy2DRAbXkGxZyA/Jaz+6YA="
}

56
packages/common/src/api/diagnostics.ts
查看文件

@ -1,7 +1,5 @@
import type { AxiosError, AxiosResponse } from 'axios' import type { AxiosError, AxiosResponse } from 'axios'
import { isAxiosError } from 'axios'
import type { z } from 'zod' import type { z } from 'zod'
import type { RequestError } from './errors'
type SafeIssue = { type SafeIssue = {
code: string code: string
@ -18,29 +16,15 @@ export type SafeApiDiagnostic = {
type: 'AxiosError' | 'Response' | 'ValidationError' type: 'AxiosError' | 'Response' | 'ValidationError'
} }
export type SafeApiErrorReport = {
diagnostic?: SafeApiDiagnostic
requestType: RequestError['type']
}
/** /**
* 网络诊断只能描述请求形态，不得复制请求/响应 body、headers 或完整 URL。 * 网络诊断只能描述请求形态，不得复制请求/响应 body、headers 或完整 URL。
* 这些字段可能包含手机号、userId、sessionId、签名和其它业务数据。 * 这些字段可能包含手机号、userId、sessionId、签名和其它业务数据。
*/ */
export function safeRequestPath(input?: string): string | undefined {
if (!input) return undefined
try {
return new URL(input, 'https://xuqm.invalid').pathname
} catch {
return input.split(/[?#]/, 1)[0]
}
}
function requestShape(response: AxiosResponse<unknown>) { function requestShape(response: AxiosResponse<unknown>) {
return { return {
httpStatus: response.status, httpStatus: response.status,
method: response.config.method?.toUpperCase(), method: response.config.method?.toUpperCase(),
path: safeRequestPath(response.config.url), path: response.config.url,
} }
} }
@ -69,42 +53,6 @@ export function createAxiosDiagnostic(error: AxiosError): SafeApiDiagnostic {
code: error.code, code: error.code,
httpStatus: error.response?.status, httpStatus: error.response?.status,
method: error.config?.method?.toUpperCase(), method: error.config?.method?.toUpperCase(),
path: safeRequestPath(error.config?.url), path: error.config?.url,
} }
} }
/**
* 非 axios 异常只允许记录构造名与截断消息。
* 不接触 cause、stack、config 或任何可能持有业务数据的对象。
*/
export function createUnexpectedDiagnostic(error: unknown): string {
if (error instanceof Error) {
return `${error.name}: ${error.message.slice(0, 200)}`
}
return typeof error
}
type ValidationCause = {
issues: z.ZodIssue[]
response: AxiosResponse<unknown>
}
function isValidationCause(value: unknown): value is ValidationCause {
if (!value || typeof value !== 'object') return false
const candidate = value as Partial<ValidationCause>
return Array.isArray(candidate.issues) && Boolean(candidate.response?.config)
}
/**
* 全局错误采集只接收不可逆的安全摘要，绝不暴露 RequestError.cause。
* cause 可能持有 Axios config、headers、请求体和完整响应，只能留在调用现场。
*/
export function createSafeApiErrorReport(error: RequestError): SafeApiErrorReport {
const cause = error.cause
const diagnostic = isValidationCause(cause)
? createValidationDiagnostic(cause.response, cause.issues)
: isAxiosError(cause)
? createAxiosDiagnostic(cause)
: undefined
return { diagnostic, requestType: error.type }
}

3
packages/common/src/api/errors.ts
查看文件

@ -1,8 +1,7 @@
export class RequestError<TData = unknown> extends Error { export class RequestError<TData = unknown> extends Error {
constructor( constructor(
message: string, message: string,
public readonly type: public readonly type: 'Cancel' | 'ValidationError' | 'AxiosError' | 'OtherError',
'Cancel' | 'ValidationError' | 'BusinessError' | 'AxiosError' | 'OtherError',
public readonly cause?: unknown, public readonly cause?: unknown,
public readonly response?: { data?: TData; status?: number }, public readonly response?: { data?: TData; status?: number },
) { ) {

5
packages/common/src/api/globalErrorHandler.ts
查看文件

@ -1,7 +1,6 @@
import { RequestError } from './errors' import { RequestError } from './errors'
import { createSafeApiErrorReport, type SafeApiErrorReport } from './diagnostics'
type ApiErrorHandler = (report: SafeApiErrorReport) => void type ApiErrorHandler = (error: RequestError) => void
let _handler: ApiErrorHandler | null = null let _handler: ApiErrorHandler | null = null
@ -12,5 +11,5 @@ export function setGlobalApiErrorHandler(handler: ApiErrorHandler): void {
/** 内部调用：在 useRequest 的 catch 分支中触发。*/ /** 内部调用：在 useRequest 的 catch 分支中触发。*/
export function _notifyApiError(error: RequestError): void { export function _notifyApiError(error: RequestError): void {
_handler?.(createSafeApiErrorReport(error)) _handler?.(error)
} }

1
packages/common/src/api/index.ts
查看文件

@ -3,7 +3,6 @@ export { useApi } from './useApi'
export { usePageApi } from './usePageApi' export { usePageApi } from './usePageApi'
export { RequestError } from './errors' export { RequestError } from './errors'
export { setGlobalApiErrorHandler } from './globalErrorHandler' export { setGlobalApiErrorHandler } from './globalErrorHandler'
export type { SafeApiDiagnostic, SafeApiErrorReport } from './diagnostics'
export type { RequestOptions } from './useRequest' export type { RequestOptions } from './useRequest'
export type { ApiMethod } from './useApi' export type { ApiMethod } from './useApi'
export type { PageOptions } from './usePageApi' export type { PageOptions } from './usePageApi'

31
packages/common/src/api/useApi.ts
查看文件

@ -10,13 +10,12 @@ import { z } from 'zod'
import { import {
createAxiosDiagnostic, createAxiosDiagnostic,
createResponseDiagnostic, createResponseDiagnostic,
createUnexpectedDiagnostic,
createValidationDiagnostic, createValidationDiagnostic,
} from './diagnostics' } from './diagnostics'
import { RequestError } from './errors' import { RequestError } from './errors'
import { type RequestOptions, useRequest, ValidationError } from './useRequest' import { type RequestOptions, useRequest, ValidationError } from './useRequest'
const SUCCESS_STATUS = '0' const SUCCESS_STATUS = /^0$/
type ApiResponse<T> = { type ApiResponse<T> = {
status: string status: string
@ -43,14 +42,12 @@ export const useApi = <S extends z.ZodTypeAny, T extends z.infer<S> = z.infer<S>
requestInterceptors: AxiosInterceptorManager<AxiosRequestConfig<unknown>> requestInterceptors: AxiosInterceptorManager<AxiosRequestConfig<unknown>>
responseInterceptors: AxiosInterceptorManager<AxiosResponse<ApiResponse<T>, unknown>> responseInterceptors: AxiosInterceptorManager<AxiosResponse<ApiResponse<T>, unknown>>
} => { } => {
// schema 只校验响应结构，不强制 status==='0'；
// 业务状态码非 '0' 属于正常业务响应，由 transformedFetchAsync 统一处理。
const responseSchema = useMemo( const responseSchema = useMemo(
() => () =>
z.object({ z.object({
status: z.string(), status: z.string().regex(SUCCESS_STATUS),
message: z.string(), message: z.string(),
data: (validationSchema ?? z.unknown()).optional(), data: validationSchema ?? z.unknown(),
}), }),
[validationSchema], [validationSchema],
) )
@ -109,6 +106,12 @@ export const useApi = <S extends z.ZodTypeAny, T extends z.infer<S> = z.infer<S>
} }
const firstIssue = e.issues[0] const firstIssue = e.issues[0]
if (firstIssue.path.length > 0 && firstIssue.path[0] === 'status') {
return Promise.reject(
new RequestError(e.response.data?.message ?? '接口返回失败', 'ValidationError', e),
)
}
return Promise.reject(new RequestError(firstIssue.message, 'ValidationError', e)) return Promise.reject(new RequestError(firstIssue.message, 'ValidationError', e))
} }
@ -120,13 +123,7 @@ export const useApi = <S extends z.ZodTypeAny, T extends z.infer<S> = z.infer<S>
return Promise.reject(new RequestError('网络请求失败', 'AxiosError', thrownError)) return Promise.reject(new RequestError('网络请求失败', 'AxiosError', thrownError))
} }
console.error( console.error('[XuqmAPI] unexpected request failure')
'[XuqmAPI] unexpected request failure',
createUnexpectedDiagnostic(thrownError),
)
if (thrownError instanceof Error && thrownError.stack) {
console.error('[XuqmAPI] unexpected request failure stack', thrownError.stack)
}
return Promise.reject(new RequestError('网络请求失败', 'OtherError', thrownError)) return Promise.reject(new RequestError('网络请求失败', 'OtherError', thrownError))
}, },
) )
@ -139,13 +136,7 @@ export const useApi = <S extends z.ZodTypeAny, T extends z.infer<S> = z.infer<S>
async (nextConfig?: AxiosRequestConfig<D>) => { async (nextConfig?: AxiosRequestConfig<D>) => {
try { try {
const requestResponse = await fetchAsync(nextConfig) const requestResponse = await fetchAsync(nextConfig)
const body = (requestResponse as unknown as AxiosResponse<ApiResponse<T>>).data return (requestResponse as unknown as AxiosResponse<ApiResponse<T>>).data.data
// 业务状态码非 '0' 时，抛出 RequestError 而非 ValidationError，
// 避免业务错误被误报为"校验失败"并影响调用方。
if (body.status !== SUCCESS_STATUS) {
throw new RequestError(body.message || '接口返回失败', 'BusinessError', body)
}
return body.data
} catch (requestError) { } catch (requestError) {
return Promise.reject(requestError) return Promise.reject(requestError)
} }

14
packages/common/src/api/useRequest.ts
查看文件

@ -15,27 +15,19 @@ export interface RequestOptions {
loadingDelay?: number loadingDelay?: number
/** 请求标签，用于日志或错误追踪。*/ /** 请求标签，用于日志或错误追踪。*/
tag?: string tag?: string
/** true = 在响应拦截器中打印不含请求体、响应体和 headers 的安全摘要。*/ /** true = 在响应拦截器中打印完整响应。*/
log?: boolean log?: boolean
} }
// ─── 内部 ValidationError（对齐 @szyx-mobile/use-axios 的 ValidationError）──── // ─── 内部 ValidationError（对齐 @szyx-mobile/use-axios 的 ValidationError）────
// 不能 extends z.ZodError：zod v4 的 ZodError 是 $constructor 工厂函数， export class ValidationError<T = unknown, D = unknown> extends z.ZodError {
// 其自定义 Symbol.hasInstance 要求实例已初始化 _zod.traits。Babel 转译的子类
// 在 super() 之前先执行 _classCallCheck(this, ValidationError)，此时 _zod 尚不
// 存在，instanceof 返回 false，直接抛 “Cannot call a class as a function”，
// 把真实的校验失败掩盖成非预期错误。
export class ValidationError<T = unknown, D = unknown> extends Error {
public readonly issues: z.ZodIssue[]
constructor( constructor(
issues: z.ZodIssue[], issues: z.ZodIssue[],
public readonly response: AxiosResponse<T, D>, public readonly response: AxiosResponse<T, D>,
) { ) {
super(issues[0]?.message ?? 'ValidationError') super(issues)
this.name = 'ValidationError' this.name = 'ValidationError'
this.issues = issues
} }
} }

32
packages/common/src/autoInit.ts
查看文件

@ -8,31 +8,20 @@
* 2. metro.config.js 使用 withXuqmConfig(metroConfig) 包装 * 2. metro.config.js 使用 withXuqmConfig(metroConfig) 包装
* 3. Metro 在业务入口前加载本模块并完成一次共享初始化 * 3. Metro 在业务入口前加载本模块并完成一次共享初始化
* *
* 未使用 withXuqmConfig 时解析到包内空实现，静默跳过且仍可完成 Metro Bundle。 * 如果配置未找到（require 失败），静默跳过，不崩溃。
*/ */
import { isInitialized } from './config' import { isInitialized } from './config'
import type { DecryptedConfig } from './crypto' import { _initializeFromConfigFile } from './sdk'
import { _initializeFromResolvedConfig } from './sdk'
let _autoInitAttempted = false let _autoInitAttempted = false
interface AutoInitPayload { function tryRequireConfig(): string | null {
config: DecryptedConfig
buildOptions?: { bugCollectMode?: 'platform' | 'disabled' }
}
function tryRequireConfig(): AutoInitPayload | null {
try { try {
// withXuqmConfig 将此模块映射到构建期已解密、已校验的配置传输模块。 // withXuqmConfig 将此模块映射到构建期生成的配置传输模块
// eslint-disable-next-line @typescript-eslint/no-require-imports // eslint-disable-next-line @typescript-eslint/no-require-imports
const mod = require('@xuqm/rn-common/auto-init-config') as { const mod = require('@xuqm/autoinit-config') as { ENCRYPTED_CONFIG?: string; default?: string }
RESOLVED_CONFIG?: DecryptedConfig return mod?.ENCRYPTED_CONFIG ?? mod?.default ?? null
default?: DecryptedConfig
BUILD_OPTIONS?: { bugCollectMode?: 'platform' | 'disabled'; buildId?: string }
}
const config = mod?.RESOLVED_CONFIG ?? mod?.default ?? null
return config ? { config, buildOptions: mod.BUILD_OPTIONS } : null
} catch { } catch {
return null return null
} }
@ -49,13 +38,10 @@ export function tryAutoInit(): void {
_autoInitAttempted = true _autoInitAttempted = true
if (isInitialized()) return if (isInitialized()) return
const payload = tryRequireConfig() const encrypted = tryRequireConfig()
if (!payload) return if (!encrypted) return
void _initializeFromResolvedConfig(payload.config, { void _initializeFromConfigFile(encrypted, { debug: __DEV__ }).catch(() => undefined)
debug: __DEV__,
bugCollectMode: payload.buildOptions?.bugCollectMode,
}).catch(() => undefined)
} }
tryAutoInit() tryAutoInit()

6
packages/common/src/autoInitConfig.ts
查看文件

@ -1,6 +0,0 @@
/**
* common-only 宿主的真实空实现。withXuqmConfig 会在 Metro 解析阶段把该公开子路径
* 精确替换为构建期配置模块；未使用 Metro 包装器时仍可正常完成静态依赖解析。
*/
export const RESOLVED_CONFIG = undefined
export const BUILD_OPTIONS = undefined

28
packages/common/src/bundleIdentity.ts
查看文件

@ -1,28 +0,0 @@
export interface XuqmBundleIdentity {
buildId: string
moduleId: string
moduleVersion: string
bundleHash: string
}
export type XuqmBundleIdentityProvider = (stacktrace: string) => Promise<XuqmBundleIdentity | null>
let provider: { owner: string; resolve: XuqmBundleIdentityProvider } | null = null
/** @internal update 是 Bundle 状态唯一事实源，只允许注册一个解析器。 */
export function _registerBundleIdentityProvider(
owner: string,
next: XuqmBundleIdentityProvider,
): void {
if (provider && provider.owner !== owner) {
throw new Error('[XuqmSDK] A bundle identity provider is already registered.')
}
provider = { owner, resolve: next }
}
/** @internal 无法精确归属时返回 null，调用方不得猜测 latest 或 app Bundle。 */
export async function _resolveBundleIdentity(
stacktrace: string,
): Promise<XuqmBundleIdentity | null> {
return provider ? provider.resolve(stacktrace) : null
}

97
packages/common/src/config.ts
查看文件

@ -1,23 +1,11 @@
/** @internal 仅由 Metro 已验签配置驱动，不属于宿主公开契约。 */ export interface XuqmInitOptions {
export interface InternalInitOptions {
appKey: string appKey: string
platformUrl?: string // 不传则使用内置默认公有平台地址 platformUrl?: string // 不传则使用内置默认公有平台地址
debug?: boolean debug?: boolean
/** 构建工具只允许将 BugCollect 降级为 disabled，不能反向覆盖平台关闭状态。 */
bugCollectMode?: 'platform' | 'disabled'
/** 自动配置内部使用。 */
packageName?: string
/** @internal 远程配置来源，用于扩展判断缓存是否有权覆盖服务端停用锁。 */
configSource?: 'remote' | 'cache'
} }
export interface XuqmConfig { export interface XuqmConfig {
appKey: string appKey: string
/** 已验签配置中的宿主包名，用于绑定插件签名，禁止由业务运行时改写。 */
packageName: string
/** 租户平台地址：配置、更新、插件发布等 Xuqm 平台接口统一使用该地址。 */
platformUrl: string
/** 业务扩展服务地址，由租户平台远程配置返回，不能代替 platformUrl。 */
apiUrl: string apiUrl: string
imWsUrl: string imWsUrl: string
fileServiceUrl: string fileServiceUrl: string
@ -28,26 +16,10 @@ export interface XuqmConfig {
// 崩溃采集服务（rn-bugcollect 使用） // 崩溃采集服务（rn-bugcollect 使用）
bugCollectApiUrl: string bugCollectApiUrl: string
bugCollectEnabled: boolean bugCollectEnabled: boolean
/** Update 服务必须由平台明确开启；缺失时安全关闭。 */
updateEnabled: boolean
/** Update 灰度检查是否要求共享登录态；由租户平台动态配置。 */
updateRequiresLogin: boolean
configurationSource: 'remote' | 'cache'
// 请求签名密钥（从配置文件读取） // 请求签名密钥（从配置文件读取）
signingKey?: string signingKey?: string
} }
export type XuqmInitializationState = 'idle' | 'initializing' | 'ready' | 'degraded' | 'failed'
export interface XuqmInitializationSnapshot {
state: XuqmInitializationState
source?: 'remote' | 'cache'
error?: {
code: string
message: string
}
}
export interface XuqmUserInfo { export interface XuqmUserInfo {
userId: string userId: string
userSig?: string // IM 登录凭证；未开通 IM 时可不传 userSig?: string // IM 登录凭证；未开通 IM 时可不传
@ -64,17 +36,13 @@ export interface XuqmLoginOptions extends XuqmUserInfo {
export type XuqmUserInfoHandler = (info: XuqmUserInfo | null) => void | Promise<void> export type XuqmUserInfoHandler = (info: XuqmUserInfo | null) => void | Promise<void>
export type XuqmInitializationHandler = (config: Readonly<XuqmConfig>) => void | Promise<void> export type XuqmInitializationHandler = (config: Readonly<XuqmConfig>) => void | Promise<void>
export type XuqmPrivacyConsentHandler = (consented: boolean) => void | Promise<void>
// ─── Internal state ──────────────────────────────────────────────────────────── // ─── Internal state ────────────────────────────────────────────────────────────
let _config: XuqmConfig | null = null let _config: XuqmConfig | null = null
let _userInfo: XuqmUserInfo | null = null let _userInfo: XuqmUserInfo | null = null
let _privacyConsented = false
let _initializationSnapshot: XuqmInitializationSnapshot = { state: 'idle' }
const _userInfoHandlers = new Map<string, XuqmUserInfoHandler>() const _userInfoHandlers = new Map<string, XuqmUserInfoHandler>()
const _initializationHandlers = new Map<string, XuqmInitializationHandler>() const _initializationHandlers = new Map<string, XuqmInitializationHandler>()
const _privacyConsentHandlers = new Map<string, XuqmPrivacyConsentHandler>()
// ─── Config ──────────────────────────────────────────────────────────────────── // ─── Config ────────────────────────────────────────────────────────────────────
@ -87,21 +55,16 @@ export interface XuqmRemoteConfig {
pushEnabled?: boolean pushEnabled?: boolean
bugCollectApiUrl?: string bugCollectApiUrl?: string
bugCollectEnabled?: boolean bugCollectEnabled?: boolean
updateEnabled?: boolean
updateRequiresLogin?: boolean
} }
export function initConfigFromRemote( export function initConfigFromRemote(
options: InternalInitOptions, options: XuqmInitOptions,
remote: XuqmRemoteConfig, remote: XuqmRemoteConfig,
signingKey?: string, signingKey?: string,
): void { ): void {
const platformUrl = (options.platformUrl ?? '').replace(/\/$/, '')
const apiUrl = remote.apiUrl ?? remote.imApiUrl ?? '' const apiUrl = remote.apiUrl ?? remote.imApiUrl ?? ''
_config = { _config = {
appKey: options.appKey, appKey: options.appKey,
packageName: options.packageName?.trim() ?? '',
platformUrl,
apiUrl, apiUrl,
imWsUrl: remote.imWsUrl ?? '', imWsUrl: remote.imWsUrl ?? '',
fileServiceUrl: remote.fileServiceUrl ?? apiUrl, fileServiceUrl: remote.fileServiceUrl ?? apiUrl,
@ -109,19 +72,13 @@ export function initConfigFromRemote(
imEnabled: remote.imEnabled ?? !!remote.imWsUrl, imEnabled: remote.imEnabled ?? !!remote.imWsUrl,
pushEnabled: remote.pushEnabled ?? true, pushEnabled: remote.pushEnabled ?? true,
bugCollectApiUrl: remote.bugCollectApiUrl ?? '', bugCollectApiUrl: remote.bugCollectApiUrl ?? '',
bugCollectEnabled: options.bugCollectMode !== 'disabled' && (remote.bugCollectEnabled ?? false), bugCollectEnabled: remote.bugCollectEnabled ?? false,
updateEnabled: remote.updateEnabled ?? false,
// 服务端未下发匿名策略时按安全默认禁止匿名更新检查。
updateRequiresLogin: remote.updateRequiresLogin ?? true,
configurationSource: options.configSource ?? 'remote',
signingKey, signingKey,
} }
} }
export function getConfig(): XuqmConfig { export function getConfig(): XuqmConfig {
if (!_config) { if (!_config) throw new Error('[XuqmSDK] Not initialized — call XuqmSDK.initialize() first.')
throw new Error('[XuqmSDK] Not initialized — verify the signed config and Metro integration.')
}
return _config return _config
} }
@ -137,42 +94,6 @@ export function isInitialized(): boolean {
return _config !== null return _config !== null
} }
export function getInitializationSnapshot(): Readonly<XuqmInitializationSnapshot> {
return _initializationSnapshot
}
export function _setInitializationSnapshot(snapshot: XuqmInitializationSnapshot): void {
_initializationSnapshot = snapshot
}
export function hasPrivacyConsent(): boolean {
return _privacyConsented
}
export async function _setPrivacyConsent(consented: boolean): Promise<void> {
if (_privacyConsented === consented) return
_privacyConsented = consented
const results = await Promise.allSettled(
Array.from(_privacyConsentHandlers.values(), handler => Promise.resolve(handler(consented))),
)
for (const result of results) {
if (result.status === 'rejected') {
console.warn('[XuqmSDK] Privacy consent handler failed:', result.reason)
}
}
}
export function _registerPrivacyConsentHandler(
name: string,
handler: XuqmPrivacyConsentHandler,
): () => void {
if (_privacyConsentHandlers.has(name)) {
throw new Error(`[XuqmSDK] Privacy consent handler "${name}" is already registered.`)
}
_privacyConsentHandlers.set(name, handler)
return () => _privacyConsentHandlers.delete(name)
}
export function _registerInitializationHandler( export function _registerInitializationHandler(
name: string, name: string,
handler: XuqmInitializationHandler, handler: XuqmInitializationHandler,
@ -236,11 +157,11 @@ export async function _setUserInfo(info: XuqmUserInfo | null): Promise<void> {
} }
}), }),
) )
for (const result of results) { const failures = results
if (result.status === 'rejected') { .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
// 扩展登录失败不能反向破坏宿主已经完成的业务登录。 .map(result => String(result.reason))
console.warn('[XuqmSDK] Session propagation failed:', result.reason) if (failures.length > 0) {
} throw new Error(`[XuqmSDK] Session propagation failed: ${failures.join('; ')}`)
} }
} }

104
packages/common/src/crypto.ts
查看文件

@ -1,30 +1,77 @@
import { gcm } from '@noble/ciphers/aes.js'
import { hmac } from '@noble/hashes/hmac.js' import { hmac } from '@noble/hashes/hmac.js'
import { pbkdf2Async } from '@noble/hashes/pbkdf2.js'
import { sha256 } from '@noble/hashes/sha2.js' import { sha256 } from '@noble/hashes/sha2.js'
import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js' import { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'
import { encodeBase64 } from '../security/base64.js'
const MAGIC_CONFIG = 'XUQM-CONFIG-V1'
const PASSPHRASES = {
[MAGIC_CONFIG]: 'xuqm-config-file-v1.2026.internal',
} as const
const PBKDF2_ITERATIONS = 120_000
const AES_KEY_BYTES = 32
export type XuqmEncryptedFileMagic = keyof typeof PASSPHRASES
export interface DecryptedConfig { export interface DecryptedConfig {
schemaVersion: 2
configId: string
revision: number
appKey: string appKey: string
appName: string appName?: string
packageName?: string companyName?: string
iosBundleId?: string baseUrl?: string
harmonyBundleName?: string serverUrl?: string
serverUrl: string signingKey?: string
signingKey: string issuedAt?: string
issuedAt: string
expiresAt?: string expiresAt?: string
} }
/** Encode arbitrary binary data without exceeding Hermes argument-count limits. */ function base64UrlDecode(value: string): Uint8Array {
export function bytesToBase64(value: Uint8Array): string { const padded =
return encodeBase64(value) value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4)
const binary = atob(padded)
return Uint8Array.from({ length: binary.length }, (_, index) => binary.charCodeAt(index))
} }
function base64UrlEncode(value: Uint8Array): string { function base64UrlEncode(value: Uint8Array): string {
return encodeBase64(value, { urlSafe: true, padding: false }) let binary = ''
value.forEach(byte => {
binary += String.fromCharCode(byte)
})
return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
}
/**
* Decode UTF-8 without relying on the optional TextDecoder implementation in
* the React Native runtime. Hermes versions and third-party polyfills have
* returned invalid text for Uint8Array views in real applications.
*/
function utf8BytesToString(value: Uint8Array): string {
let encoded = ''
for (const byte of value) {
encoded += `%${byte.toString(16).padStart(2, '0')}`
}
return decodeURIComponent(encoded)
}
function parseEncryptedFile(content: string): {
magic: XuqmEncryptedFileMagic
salt: Uint8Array
iv: Uint8Array
ciphertext: Uint8Array
} {
const parts = content.trim().split('.')
const magic = parts[0] as XuqmEncryptedFileMagic
if (parts.length !== 4 || !(magic in PASSPHRASES)) {
throw new Error('[XuqmSDK] Invalid config file format')
}
const salt = base64UrlDecode(parts[1])
const iv = base64UrlDecode(parts[2])
const ciphertext = base64UrlDecode(parts[3])
if (salt.length === 0 || iv.length !== 12 || ciphertext.length <= 16) {
throw new Error('[XuqmSDK] Invalid config cryptographic parameters')
}
return { magic, salt, iv, ciphertext }
} }
export function hmacSha256Base64Url(secret: string, data: string): string { export function hmacSha256Base64Url(secret: string, data: string): string {
@ -35,3 +82,30 @@ export function hmacSha256Base64Url(secret: string, data: string): string {
export function sha256Hex(value: string | Uint8Array): string { export function sha256Hex(value: string | Uint8Array): string {
return bytesToHex(sha256(typeof value === 'string' ? utf8ToBytes(value) : value)) return bytesToHex(sha256(typeof value === 'string' ? utf8ToBytes(value) : value))
} }
export async function decryptXuqmFile<T extends object = DecryptedConfig>(
content: string,
): Promise<T> {
const { magic, salt, iv, ciphertext } = parseEncryptedFile(content)
const key = await pbkdf2Async(sha256, PASSPHRASES[magic], salt, {
c: PBKDF2_ITERATIONS,
dkLen: AES_KEY_BYTES,
})
let plaintext: Uint8Array
try {
plaintext = gcm(key, iv).decrypt(ciphertext)
} catch {
throw new Error('[XuqmSDK] Config decryption failed')
}
try {
return JSON.parse(utf8BytesToString(plaintext)) as T
} catch {
throw new Error('[XuqmSDK] Config content is not valid JSON')
}
}
export function decryptConfigFile(content: string): Promise<DecryptedConfig> {
return decryptXuqmFile<DecryptedConfig>(content)
}

20
packages/common/src/errors.ts
查看文件

@ -1,20 +0,0 @@
export type XuqmErrorCode =
| 'XUQM_NOT_READY'
| 'XUQM_NOT_LOGGED_IN'
| 'XUQM_CONFIG_INVALID'
| 'XUQM_CONFIG_EXPIRED'
| 'XUQM_CONFIG_REVOKED'
| 'XUQM_SERVICE_DISABLED'
/** SDK 公共结构化错误。宿主可以按 code 决定提示方式，无需解析错误文案。 */
export class XuqmError extends Error {
readonly name = 'XuqmError'
constructor(
public readonly code: XuqmErrorCode,
message: string,
public readonly cause?: unknown,
) {
super(message)
}
}

42
packages/common/src/http.ts
查看文件

@ -2,7 +2,6 @@ import AsyncStorage from '@react-native-async-storage/async-storage'
import { DEFAULT_TENANT_PLATFORM_URL } from './constants' import { DEFAULT_TENANT_PLATFORM_URL } from './constants'
import { getOptionalConfig, getUserId } from './config' import { getOptionalConfig, getUserId } from './config'
import { hmacSha256Base64Url } from './crypto' import { hmacSha256Base64Url } from './crypto'
import { safeRequestPath } from './api/diagnostics'
const TOKEN_KEY = '@xuqm:token' const TOKEN_KEY = '@xuqm:token'
let _baseUrl = DEFAULT_TENANT_PLATFORM_URL let _baseUrl = DEFAULT_TENANT_PLATFORM_URL
@ -45,10 +44,6 @@ export async function apiRequest<T>(
body?: unknown body?: unknown
params?: Record<string, string> params?: Record<string, string>
skipAuth?: boolean skipAuth?: boolean
/** 调用方取消信号；版本检查等可在页面退出时立即停止。 */
signal?: AbortSignal
/** 默认 30 秒，必须为正数；防止网络异常永久阻塞扩展入口。 */
timeoutMs?: number
} = {}, } = {},
): Promise<T> { ): Promise<T> {
let url = path.startsWith('http://') || path.startsWith('https://') ? path : `${_baseUrl}${path}` let url = path.startsWith('http://') || path.startsWith('https://') ? path : `${_baseUrl}${path}`
@ -84,44 +79,25 @@ export async function apiRequest<T>(
if (_debugHttp) { if (_debugHttp) {
console.debug('[XuqmSDK][HTTP] request', { console.debug('[XuqmSDK][HTTP] request', {
method: options.method ?? 'GET', method: options.method ?? 'GET',
path: safeRequestPath(url), url,
hasBody: Boolean(options.body), hasBody: Boolean(options.body),
}) })
} }
const timeoutMs = options.timeoutMs ?? 30_000 const res = await fetch(url, {
if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) { method: options.method ?? 'GET',
throw new Error('[XuqmSDK][HTTP] timeoutMs must be a positive number') headers,
} body: options.body ? JSON.stringify(options.body) : undefined,
})
const controller = new AbortController()
const abortFromCaller = () => controller.abort(options.signal?.reason)
if (options.signal?.aborted) abortFromCaller()
else options.signal?.addEventListener('abort', abortFromCaller, { once: true })
const timeout = setTimeout(() => {
controller.abort(new Error(`[XuqmSDK][HTTP] Request timed out after ${timeoutMs}ms`))
}, timeoutMs)
let res: Response
try {
res = await fetch(url, {
method: options.method ?? 'GET',
headers,
body: options.body ? JSON.stringify(options.body) : undefined,
signal: controller.signal,
})
} finally {
clearTimeout(timeout)
options.signal?.removeEventListener('abort', abortFromCaller)
}
if (!res.ok) { if (!res.ok) {
const err = await res.json().catch(() => ({ message: res.statusText })) const err = await res.json().catch(() => ({ message: res.statusText }))
if (_debugHttp) { if (_debugHttp) {
console.debug('[XuqmSDK][HTTP] response', { console.debug('[XuqmSDK][HTTP] response', {
path: safeRequestPath(url), url,
status: res.status, status: res.status,
ok: false, ok: false,
message: (err as { message?: string }).message ?? res.statusText,
}) })
} }
throw new Error((err as { message?: string }).message ?? `HTTP ${res.status}`) throw new Error((err as { message?: string }).message ?? `HTTP ${res.status}`)
@ -130,7 +106,7 @@ export async function apiRequest<T>(
const json = await res.json() const json = await res.json()
if (_debugHttp) { if (_debugHttp) {
console.debug('[XuqmSDK][HTTP] response', { console.debug('[XuqmSDK][HTTP] response', {
path: safeRequestPath(url), url,
status: res.status, status: res.status,
ok: true, ok: true,
}) })

50
packages/common/src/index.ts
查看文件

@ -1,27 +1,10 @@
export { XuqmSDK } from './sdk' export { XuqmSDK } from './sdk'
export type { export type { XuqmInitOptions, XuqmConfig, XuqmLoginOptions, XuqmUserInfo } from './config'
XuqmConfig, export { getConfig, isInitialized, getUserId, getUserInfo } from './config'
XuqmInitializationSnapshot,
XuqmInitializationState,
XuqmLoginOptions,
XuqmUserInfo,
} from './config'
export {
getConfig,
getInitializationSnapshot,
hasPrivacyConsent,
isInitialized,
getUserId,
getUserInfo,
} from './config'
export { XuqmError } from './errors'
export type { XuqmErrorCode } from './errors'
export { retryWithBackoff } from './retry'
export type { RetryOptions } from './retry'
export { awaitInitialization } from './sdk' export { awaitInitialization } from './sdk'
export { apiRequest, configureHttp } from './http' export { apiRequest, configureHttp } from './http'
export { bytesToBase64, hmacSha256Base64Url, sha256Hex } from './crypto' export { decryptConfigFile, decryptXuqmFile, hmacSha256Base64Url, sha256Hex } from './crypto'
export type { DecryptedConfig } from './crypto' export type { DecryptedConfig, XuqmEncryptedFileMagic } from './crypto'
export { DEFAULT_TENANT_PLATFORM_URL, DEFAULT_IM_WS_URL } from './constants' export { DEFAULT_TENANT_PLATFORM_URL, DEFAULT_IM_WS_URL } from './constants'
export { getDeviceId, getDeviceInfo, detectPushVendor } from './device' export { getDeviceId, getDeviceInfo, detectPushVendor } from './device'
export type { DeviceInfo, PushVendor } from './device' export type { DeviceInfo, PushVendor } from './device'
@ -63,6 +46,30 @@ export {
satisfiesVersion, satisfiesVersion,
} from './version' } from './version'
export { ScaledImage } from './components/ScaledImage' export { ScaledImage } from './components/ScaledImage'
export {
XWebViewControl,
getXWebViewConfig,
openXWebView,
setXWebViewController,
setXWebViewNavigationRef,
setXWebViewScanQRCodeHandler,
processJSBridgeMessage,
} from './xwebview/XWebViewBridge'
export type { XWebViewNavigationRef, ScanQRCodeHandler } from './xwebview/XWebViewBridge'
export type {
XWebViewClickMenu,
XWebViewConfig,
XWebViewControllerAPI,
XWebViewNavigationState,
XWebViewDownloadDecision,
XWebViewDownloadDestination,
XWebViewDownloadProgress,
XWebViewDownloadRequest,
XWebViewDownloadResult,
XWebViewMessageEvent,
XWebViewPermissionRequest,
} from './xwebview/types'
// api/ 子模块 // api/ 子模块
export { export {
RequestError, RequestError,
@ -73,7 +80,6 @@ export {
ValidationError, ValidationError,
} from './api' } from './api'
export type { RequestOptions as UseRequestOptions, ApiMethod } from './api' export type { RequestOptions as UseRequestOptions, ApiMethod } from './api'
export type { SafeApiDiagnostic, SafeApiErrorReport } from './api'
export type { PageOptions } from './api' export type { PageOptions } from './api'
export type { AxiosRequestConfig } from 'axios' export type { AxiosRequestConfig } from 'axios'

8
packages/common/src/internal.ts
查看文件

@ -6,11 +6,5 @@
*/ */
import './autoInit' import './autoInit'
export { _registerBundleIdentityProvider, _resolveBundleIdentity } from './bundleIdentity' export { _registerInitializationHandler, _registerUserInfoHandler } from './config'
export {
_registerInitializationHandler,
_registerPrivacyConsentHandler,
_registerUserInfoHandler,
} from './config'
export type { XuqmBundleIdentity, XuqmBundleIdentityProvider } from './bundleIdentity'
export type { XuqmInitializationHandler } from './config' export type { XuqmInitializationHandler } from './config'

68
packages/common/src/internalSecurity.ts
查看文件

@ -1,68 +0,0 @@
import { ed25519 } from '@noble/curves/ed25519.js'
import { utf8ToBytes } from '@noble/hashes/utils.js'
import { decodeBase64 } from '../security/base64.js'
import { canonicalJson } from '../security/canonical-json.js'
const TRUSTED_SIGNING_KEYS = require('../security/trusted-signing-keys.json') as Readonly<
Record<string, string>
>
export interface SignedPluginManifest {
appKey: string
packageName: string
platform: 'ANDROID' | 'IOS'
moduleId: string
type: 'common' | 'app' | 'buz'
version: string
appVersionRange: string
builtAgainstNativeBaselineId: string
buildId: string
bundleFormat: 'hermes-bytecode' | 'javascript'
commonVersionRange?: string
minNativeApiLevel: number
bundleSha256: string
archiveSha256: string
}
export class PluginManifestSignatureError extends Error {
readonly name = 'PluginManifestSignatureError'
constructor(
message: string,
public readonly code: 'UNKNOWN_SIGNING_KEY' | 'INVALID_SIGNATURE',
) {
super(message)
}
}
/** @internal 插件候选必须在生成计划和下载前通过同一可信密钥集合验签。 */
export function verifySignedPluginManifest(
manifest: SignedPluginManifest,
keyId: string,
signature: string,
trustedKeys: Readonly<Record<string, string>> = TRUSTED_SIGNING_KEYS,
): void {
const publicKey = trustedKeys[keyId]
if (!publicKey) {
throw new PluginManifestSignatureError(
`[XuqmSecurity] Untrusted plugin signing key: ${keyId}`,
'UNKNOWN_SIGNING_KEY',
)
}
let valid = false
try {
valid = ed25519.verify(
decodeBase64(signature),
utf8ToBytes(canonicalJson(manifest)),
decodeBase64(publicKey),
)
} catch {
valid = false
}
if (!valid) {
throw new PluginManifestSignatureError(
`[XuqmSecurity] Invalid plugin manifest signature: ${manifest.moduleId}@${manifest.version}`,
'INVALID_SIGNATURE',
)
}
}

55
packages/common/src/remoteConfig.ts
查看文件

@ -1,55 +0,0 @@
import { z } from 'zod'
import type { XuqmRemoteConfig } from './config'
const flatRemoteConfigSchema = z.object({
apiUrl: z.string().optional(),
imApiUrl: z.string().optional(),
imWsUrl: z.string().optional(),
fileServiceUrl: z.string().optional(),
imEnabled: z.boolean().optional(),
pushEnabled: z.boolean().optional(),
bugCollectApiUrl: z.string().optional(),
bugCollectEnabled: z.boolean().optional(),
updateEnabled: z.boolean().optional(),
updateRequiresLogin: z.boolean().optional(),
})
const remoteConfigResponseSchema = flatRemoteConfigSchema
.extend({
allowAnonymousUpdateCheck: z.boolean().optional(),
features: z
.object({
im: z.boolean().optional(),
push: z.boolean().optional(),
bugCollect: z.boolean().optional(),
update: z.boolean().optional(),
})
.optional(),
})
.loose()
/** 平台远程配置的唯一归一化入口；features 字段优先于历史 flat 字段。 */
export function normalizeRemoteConfig(value: unknown): XuqmRemoteConfig {
const raw = remoteConfigResponseSchema.parse(value)
const features = raw.features ?? {}
return {
apiUrl: raw.apiUrl,
imApiUrl: raw.imApiUrl,
imWsUrl: raw.imWsUrl,
fileServiceUrl: raw.fileServiceUrl,
imEnabled: features.im ?? raw.imEnabled,
pushEnabled: features.push ?? raw.pushEnabled,
bugCollectApiUrl: raw.bugCollectApiUrl,
bugCollectEnabled: features.bugCollect ?? raw.bugCollectEnabled,
updateEnabled: features.update ?? raw.updateEnabled,
updateRequiresLogin:
raw.updateRequiresLogin ??
(raw.allowAnonymousUpdateCheck === undefined ? undefined : !raw.allowAnonymousUpdateCheck),
}
}
/** 旧缓存允许缺少 updateEnabled，最终由 XuqmConfig 按安全默认 false 收敛。 */
export function parseCachedRemoteConfig(value: unknown): XuqmRemoteConfig | null {
const parsed = flatRemoteConfigSchema.safeParse(value)
return parsed.success ? parsed.data : null
}

57
packages/common/src/retry.ts
查看文件

@ -1,57 +0,0 @@
export interface RetryOptions {
maxAttempts?: number
baseDelayMs?: number
maxDelayMs?: number
jitterRatio?: number
signal?: AbortSignal
shouldRetry?: (error: unknown) => boolean
}
function abortError(): Error {
const error = new Error('Operation aborted')
error.name = 'AbortError'
return error
}
function wait(delayMs: number, signal?: AbortSignal): Promise<void> {
if (signal?.aborted) return Promise.reject(abortError())
return new Promise((resolve, reject) => {
const timer = setTimeout(resolve, delayMs)
signal?.addEventListener(
'abort',
() => {
clearTimeout(timer)
reject(abortError())
},
{ once: true },
)
})
}
/** 后台网络任务统一使用三次指数退避并加入抖动，禁止各扩展自行无限重试。 */
export async function retryWithBackoff<T>(
action: (attempt: number) => Promise<T>,
options: RetryOptions = {},
): Promise<T> {
const {
maxAttempts = 3,
baseDelayMs = 500,
maxDelayMs = 8_000,
jitterRatio = 0.2,
signal,
shouldRetry = () => true,
} = options
let lastError: unknown
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
try {
return await action(attempt)
} catch (error) {
lastError = error
if (attempt >= maxAttempts || !shouldRetry(error)) throw error
const base = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1))
const jitter = base * jitterRatio * (Math.random() * 2 - 1)
await wait(Math.max(0, Math.round(base + jitter)), signal)
}
}
throw lastError
}

251
packages/common/src/sdk.ts
查看文件

@ -1,110 +1,33 @@
import AsyncStorage from '@react-native-async-storage/async-storage'
import { import {
_notifyInitialized, _notifyInitialized,
_setInitializationSnapshot,
_setPrivacyConsent,
_setUserInfo, _setUserInfo,
getInitializationSnapshot,
getUserId as getCommonUserId, getUserId as getCommonUserId,
getUserInfo as getCommonUserInfo, getUserInfo as getCommonUserInfo,
initConfigFromRemote, initConfigFromRemote,
isInitialized, isInitialized,
type InternalInitOptions, type XuqmInitOptions,
type XuqmLoginOptions, type XuqmLoginOptions,
type XuqmRemoteConfig,
type XuqmUserInfo, type XuqmUserInfo,
} from './config' } from './config'
import { DEFAULT_TENANT_PLATFORM_URL } from './constants' import { DEFAULT_TENANT_PLATFORM_URL } from './constants'
import { sha256Hex } from './crypto'
import { XuqmError } from './errors'
import { _clearAccessToken, _saveAccessToken, configureHttp } from './http' import { _clearAccessToken, _saveAccessToken, configureHttp } from './http'
import { retryWithBackoff } from './retry' import { decryptConfigFile } from './crypto'
import { isCacheRecordFresh, openLocalCache, sealLocalCache } from './secureCache'
import type { DecryptedConfig } from './crypto'
import { normalizeRemoteConfig, parseCachedRemoteConfig } from './remoteConfig'
let _initPromise: Promise<void> | null = null let _initPromise: Promise<void> | null = null
let _resolvedConfigInitPromise: Promise<void> | null = null let _configFileInitPromise: Promise<void> | null = null
let _resolvedConfigRequest: { let _configFileRequest: {
config: DecryptedConfig encryptedContent: string
options?: { debug?: boolean; bugCollectMode?: 'platform' | 'disabled' } options?: { debug?: boolean }
} | null = null } | null = null
let _initializationKey: string | null = null let _initializationKey: string | null = null
let _sessionTransition: Promise<void> = Promise.resolve() let _sessionTransition: Promise<void> = Promise.resolve()
let _activeSessionKey: string | null = null let _activeSessionKey: string | null = null
const REMOTE_CONFIG_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1_000
const REMOTE_CONFIG_CACHE_PREFIX = '@xuqm_common:remote_config:v1:' function initializationKey(options: XuqmInitOptions): string {
interface CachedRemoteConfig { return `${options.appKey.trim()}\n${(options.platformUrl ?? DEFAULT_TENANT_PLATFORM_URL).replace(/\/$/, '')}`
cachedAt: number
remote: XuqmRemoteConfig
} }
function runtimePlatform(): 'ANDROID' | 'IOS' { function startInitialization(options: XuqmInitOptions, signingKey?: string): Promise<void> {
try {
// 延迟加载避免 common 的纯 Node 工具与测试被 React Native 的 Flow 源码绑定。
// Metro 仍能静态发现该依赖，移动端运行时以 React Native Platform 为唯一事实。
const reactNative = require('react-native') as {
Platform?: { OS?: string }
}
return reactNative.Platform?.OS === 'ios' ? 'IOS' : 'ANDROID'
} catch {
return 'ANDROID'
}
}
function initializationKey(options: InternalInitOptions): string {
return `${options.appKey.trim()}\n${(options.platformUrl ?? DEFAULT_TENANT_PLATFORM_URL).replace(/\/$/, '')}\n${options.packageName ?? ''}`
}
function storageKey(options: InternalInitOptions): string {
return `${REMOTE_CONFIG_CACHE_PREFIX}${sha256Hex(initializationKey(options))}`
}
async function readCachedRemoteConfig(
options: InternalInitOptions,
signingKey?: string,
): Promise<CachedRemoteConfig | null> {
if (!signingKey) return null
try {
const encrypted = await AsyncStorage.getItem(storageKey(options))
if (!encrypted) return null
const raw = openLocalCache(encrypted, signingKey, initializationKey(options))
const cached = JSON.parse(raw) as CachedRemoteConfig
const parsedRemote = parseCachedRemoteConfig(cached?.remote)
if (
!cached ||
!isCacheRecordFresh(cached.cachedAt, Date.now(), REMOTE_CONFIG_CACHE_TTL_MS) ||
!parsedRemote
) {
await AsyncStorage.removeItem(storageKey(options))
return null
}
return { cachedAt: cached.cachedAt, remote: parsedRemote }
} catch {
await AsyncStorage.removeItem(storageKey(options)).catch(() => undefined)
return null
}
}
async function writeCachedRemoteConfig(
options: InternalInitOptions,
remote: CachedRemoteConfig['remote'],
signingKey?: string,
): Promise<void> {
if (!signingKey) return
try {
const encrypted = sealLocalCache(
JSON.stringify({ cachedAt: Date.now(), remote } satisfies CachedRemoteConfig),
signingKey,
initializationKey(options),
)
await AsyncStorage.setItem(storageKey(options), encrypted)
} catch {
// 安全随机数或沙箱存储不可用时跳过缓存，不能降级为明文，也不能阻断初始化。
}
}
function startInitialization(options: InternalInitOptions, signingKey?: string): Promise<void> {
const nextKey = initializationKey(options) const nextKey = initializationKey(options)
if (isInitialized()) { if (isInitialized()) {
if (_initializationKey !== nextKey) { if (_initializationKey !== nextKey) {
@ -123,73 +46,36 @@ function startInitialization(options: InternalInitOptions, signingKey?: string):
_initializationKey = nextKey _initializationKey = nextKey
_initPromise = (async () => { _initPromise = (async () => {
_setInitializationSnapshot({ state: 'initializing' }) const baseUrl = options.platformUrl ?? DEFAULT_TENANT_PLATFORM_URL
const platformUrl = (options.platformUrl ?? DEFAULT_TENANT_PLATFORM_URL).replace(/\/$/, '') const configUrl = `${baseUrl.replace(/\/$/, '')}/api/sdk/config?appKey=${encodeURIComponent(options.appKey)}`
const configParams = new URLSearchParams({ const res = await fetch(configUrl)
appKey: options.appKey, if (!res.ok) {
platform: runtimePlatform(), throw new Error(`[XuqmSDK] Platform config request failed: ${res.status}`)
})
if (options.packageName) configParams.set('packageName', options.packageName)
const configUrl = `${platformUrl}/api/sdk/config?${configParams.toString()}`
let remote: CachedRemoteConfig['remote']
let source: 'remote' | 'cache' = 'remote'
try {
const res = await retryWithBackoff(
async () => {
const response = await fetch(configUrl)
if (response.ok) return response
if (response.status >= 500) {
throw new Error(`[XuqmSDK] Platform config request failed: ${response.status}`)
}
throw new XuqmError(
'XUQM_NOT_READY',
`[XuqmSDK] Platform config request failed: ${response.status}`,
)
},
{
maxAttempts: 3,
shouldRetry: error => !(error instanceof XuqmError),
},
)
const json = (await res.json()) as Record<string, unknown>
remote = normalizeRemoteConfig(json.data ?? json)
await writeCachedRemoteConfig(options, remote, signingKey)
} catch (error) {
const cached = await readCachedRemoteConfig(options, signingKey)
if (!cached) {
throw new XuqmError(
'XUQM_NOT_READY',
'[XuqmSDK] Tenant configuration is unavailable and no valid cache exists.',
error,
)
}
remote = cached.remote
source = 'cache'
} }
initConfigFromRemote({ ...options, platformUrl, configSource: source }, remote, signingKey) const json = (await res.json()) as Record<string, unknown>
// Xuqm 平台接口始终回到租户平台。remote.apiUrl 是业务扩展服务地址， const remote = (json.data ?? json) as Record<string, unknown>
// 二者职责不同；混用会把版本检查错误地发送到 App 自身的业务服务。 initConfigFromRemote(
options,
{
apiUrl: remote.apiUrl as string | undefined,
imWsUrl: remote.imWsUrl as string | undefined,
fileServiceUrl: remote.fileServiceUrl as string | undefined,
imEnabled: remote.imEnabled as boolean | undefined,
pushEnabled: remote.pushEnabled as boolean | undefined,
bugCollectApiUrl: remote.bugCollectApiUrl as string | undefined,
bugCollectEnabled: remote.bugCollectEnabled as boolean | undefined,
},
signingKey,
)
configureHttp({ configureHttp({
baseUrl: platformUrl, baseUrl: (remote.apiUrl as string | undefined) ?? baseUrl,
debug: options.debug, debug: options.debug,
}) })
await _notifyInitialized() await _notifyInitialized()
_setInitializationSnapshot({
state: source === 'remote' ? 'ready' : 'degraded',
source,
})
})().catch(error => { })().catch(error => {
_initPromise = null _initPromise = null
_initializationKey = null _initializationKey = null
const structured = throw error
error instanceof XuqmError
? error
: new XuqmError('XUQM_NOT_READY', '[XuqmSDK] Initialization failed.', error)
_setInitializationSnapshot({
state: 'failed',
error: { code: structured.code, message: structured.message },
})
throw structured
}) })
return _initPromise return _initPromise
} }
@ -201,6 +87,23 @@ function enqueueSessionTransition(action: () => Promise<void>): Promise<void> {
} }
export const XuqmSDK = { export const XuqmSDK = {
/**
* 方式 B：手动初始化。
*
* 请求平台获取该 appKey 的完整服务配置（IM、Push、文件服务等 URL 及开通状态）。
* 失败时直接抛出，不降级。
*
* @param options.appKey 应用标识
* @param options.platformUrl 平台地址；不传则使用内置默认公有平台地址
* @param options.debug 是否开启调试日志
*/
async initialize(options: XuqmInitOptions): Promise<void> {
if (!options.appKey.trim()) {
throw new Error('[XuqmSDK] appKey is required.')
}
await startInitialization(options)
},
/** /**
* 等待初始化完成。在任意子 SDK 内部调用以确保 XuqmSDK 已就绪。 * 等待初始化完成。在任意子 SDK 内部调用以确保 XuqmSDK 已就绪。
*/ */
@ -208,17 +111,6 @@ export const XuqmSDK = {
await awaitInitialization() await awaitInitialization()
}, },
getInitializationState() {
return getInitializationSnapshot()
},
/**
* 宿主隐私声明的唯一同步入口。SDK 不弹隐私提示，也不自行推断用户是否同意。
*/
async setPrivacyConsent(consented: boolean): Promise<void> {
await _setPrivacyConsent(consented)
},
getUserId(): string | null { getUserId(): string | null {
return getCommonUserId() return getCommonUserId()
}, },
@ -260,47 +152,38 @@ export const XuqmSDK = {
export async function awaitInitialization(): Promise<void> { export async function awaitInitialization(): Promise<void> {
if (isInitialized()) return if (isInitialized()) return
const pendingInitialization = const pendingInitialization =
_resolvedConfigInitPromise ?? _configFileInitPromise ??
_initPromise ?? _initPromise ??
(_resolvedConfigRequest (_configFileRequest
? _initializeFromResolvedConfig(_resolvedConfigRequest.config, _resolvedConfigRequest.options) ? _initializeFromConfigFile(_configFileRequest.encryptedContent, _configFileRequest.options)
: null) : null)
if (!pendingInitialization) { if (!pendingInitialization) {
throw new XuqmError( throw new Error(
'XUQM_NOT_READY', '[XuqmSDK] Automatic initialization did not start. Place config.xuqmconfig in src/assets/config and wrap Metro with withXuqmConfig(), or call XuqmSDK.initialize().',
'[XuqmSDK] Automatic initialization did not start. Place exactly one .xuqmconfig file in src/assets/config and wrap Metro with withXuqmConfig().',
) )
} }
await pendingInitialization await pendingInitialization
} }
/** Metro 自动初始化专用入口；配置已在可信构建进程中完成解密和格式校验。 */ /** Internal entry used only by the Metro auto-init module. */
export function _initializeFromResolvedConfig( export function _initializeFromConfigFile(
config: DecryptedConfig, encryptedContent: string,
options?: { debug?: boolean; bugCollectMode?: 'platform' | 'disabled' }, options?: { debug?: boolean },
): Promise<void> { ): Promise<void> {
_resolvedConfigRequest = { config, options } _configFileRequest = { encryptedContent, options }
if (_resolvedConfigInitPromise) return _resolvedConfigInitPromise if (_configFileInitPromise) return _configFileInitPromise
_resolvedConfigInitPromise = (async () => { _configFileInitPromise = (async () => {
const platformUrl = config.serverUrl const file = await decryptConfigFile(encryptedContent)
const platformUrl = file.serverUrl ?? file.baseUrl ?? undefined
await startInitialization( await startInitialization(
{ { appKey: file.appKey, platformUrl, debug: options?.debug },
appKey: config.appKey, file.signingKey,
platformUrl,
debug: options?.debug,
bugCollectMode: options?.bugCollectMode,
packageName:
runtimePlatform() === 'IOS'
? (config.iosBundleId ?? config.packageName)
: config.packageName,
},
config.signingKey,
) )
})().catch(error => { })().catch(error => {
_resolvedConfigInitPromise = null _configFileInitPromise = null
throw error throw error
}) })
return _resolvedConfigInitPromise return _configFileInitPromise
} }

60
packages/common/src/secureCache.ts
查看文件

@ -1,60 +0,0 @@
import { gcm } from '@noble/ciphers/aes.js'
import { sha256 } from '@noble/hashes/sha2.js'
import { utf8ToBytes } from '@noble/hashes/utils.js'
import { decodeBase64, encodeBase64 } from '../security/base64.js'
const CACHE_FORMAT = 'XUQM-CACHE-V1'
const NONCE_BYTES = 12
function bytesToBase64Url(value: Uint8Array): string {
return encodeBase64(value, { urlSafe: true, padding: false })
}
function cacheKey(secret: string, context: string): Uint8Array {
return sha256(utf8ToBytes(`xuqm-lkg-cache\0${context}\0${secret}`))
}
function utf8BytesToString(value: Uint8Array): string {
let encoded = ''
for (const byte of value) encoded += `%${byte.toString(16).padStart(2, '0')}`
return decodeURIComponent(encoded)
}
function randomNonce(): Uint8Array {
const nonce = new Uint8Array(NONCE_BYTES)
const cryptoApi = globalThis.crypto
if (!cryptoApi?.getRandomValues) {
throw new Error('[XuqmSDK] Secure random source is unavailable; LKG cache was not written.')
}
cryptoApi.getRandomValues(nonce)
return nonce
}
/**
* 应用沙箱内的带完整性加密。密钥由平台签发配置中的 signingKey 派生但不落缓存；
* 这是防止缓存明文与离线篡改的边界，不宣称具备硬件 Keystore 保密性。
*/
export function sealLocalCache(plaintext: string, secret: string, context: string): string {
const nonce = randomNonce()
const ciphertext = gcm(cacheKey(secret, context), nonce, utf8ToBytes(context)).encrypt(
utf8ToBytes(plaintext),
)
return `${CACHE_FORMAT}.${bytesToBase64Url(nonce)}.${bytesToBase64Url(ciphertext)}`
}
export function openLocalCache(payload: string, secret: string, context: string): string {
const parts = payload.split('.')
if (parts.length !== 3 || parts[0] !== CACHE_FORMAT) {
throw new Error('[XuqmSDK] LKG cache format is invalid.')
}
const nonce = decodeBase64(parts[1])
if (nonce.length !== NONCE_BYTES) throw new Error('[XuqmSDK] LKG cache nonce is invalid.')
const plaintext = gcm(cacheKey(secret, context), nonce, utf8ToBytes(context)).decrypt(
decodeBase64(parts[2]),
)
return utf8BytesToString(plaintext)
}
export function isCacheRecordFresh(cachedAt: number, now: number, ttlMs: number): boolean {
return Number.isFinite(cachedAt) && cachedAt <= now && ttlMs > 0 && now - cachedAt <= ttlMs
}

222
packages/common/src/xwebview/XWebViewBridge.ts 普通文件
查看文件

@ -0,0 +1,222 @@
import { Alert, Platform, ToastAndroid } from 'react-native'
import { getDeviceInfo } from '../device'
import { getUserInfo } from '../config'
import { _getAccessToken } from '../http'
import type { XWebViewConfig, XWebViewControllerAPI } from './types'
export type { XWebViewControllerAPI } from './types'
// ─── Navigation ref (宿主注入) ─────────────────────────────────────────────────
export type XWebViewNavigationRef = {
navigate: (route: string, params?: Record<string, unknown>) => void
goBack: () => void
}
let _navigationRef: XWebViewNavigationRef | null = null
/**
* 注入导航能力（宿主在 App 初始化时调用）。
* 供 JSBridge 的 `xuqm.openNativePage` / `xuqm.closeWebView` 使用。
*/
export function setXWebViewNavigationRef(ref: XWebViewNavigationRef | null): void {
_navigationRef = ref
}
// ─── ScanQRCode handler (宿主注入) ────────────────────────────────────────────
export type ScanQRCodeHandler = () => Promise<string>
let _scanQRCodeHandler: ScanQRCodeHandler | null = null
/**
* 注入扫码能力（宿主在 App 初始化时调用）。
* 供 JSBridge 的 `xuqm.scanQRCode` 使用。
* handler 应打开原生扫码页并返回扫码结果字符串。
*/
export function setXWebViewScanQRCodeHandler(handler: ScanQRCodeHandler | null): void {
_scanQRCodeHandler = handler
}
// ─── JSBridge response helpers ─────────────────────────────────────────────────
type BridgeResponse = { code: 0; data: unknown } | { code: -1; message: string }
function ok(data: unknown): BridgeResponse {
return { code: 0, data }
}
function fail(message: string): BridgeResponse {
return { code: -1, message }
}
function showToast(message: string): void {
if (Platform.OS === 'android') {
ToastAndroid.show(message, ToastAndroid.SHORT)
} else {
Alert.alert('', message)
}
}
// ─── JSBridge message processor ───────────────────────────────────────────────
/**
* 处理来自 WebView 的 JSBridge 消息（action 以 `xuqm.` 开头）。
*
* 在 WebView 的 `onMessage` 回调中调用此函数。若消息被本 bridge 处理，
* 返回 `true`（上层不必再转发给 userOnMessage）；否则返回 `false`。
*
* @param rawData WebViewMessageEvent.nativeEvent.data
* @param postMessageToWeb 向 WebView 回传字符串的函数（injectJavaScript 封装）
*/
export async function processJSBridgeMessage(
rawData: string,
postMessageToWeb: (js: string) => void,
): Promise<boolean> {
let parsed: {
__xuqm?: string
id?: string | number
params?: Record<string, unknown>
}
try {
parsed = JSON.parse(rawData)
} catch {
return false
}
const action = parsed.__xuqm
if (typeof action !== 'string' || !action.startsWith('xuqm.')) {
return false
}
const id = parsed.id
const params = parsed.params ?? {}
function respond(result: BridgeResponse): void {
const js = `
(function(){
var e = new CustomEvent('xuqm_bridge_response_${String(id ?? '')}', { detail: ${JSON.stringify(result)} });
window.dispatchEvent(e);
if (window.__xuqmBridgeCallback) {
window.__xuqmBridgeCallback(${JSON.stringify(String(id ?? ''))}, ${JSON.stringify(result)});
}
})();
true;`.trim()
postMessageToWeb(js)
}
try {
switch (action) {
case 'xuqm.getDeviceInfo': {
const info = await getDeviceInfo()
respond(ok(info))
break
}
case 'xuqm.getToken': {
const token = await _getAccessToken()
respond(ok(token))
break
}
case 'xuqm.getUserInfo': {
const info = getUserInfo()
respond(ok(info))
break
}
case 'xuqm.openNativePage': {
const route = params.route
if (typeof route !== 'string') {
respond(fail('params.route is required'))
break
}
const navParams = params.params as Record<string, unknown> | undefined
if (!_navigationRef) {
respond(fail('navigation not available — call setXWebViewNavigationRef() in host app'))
break
}
_navigationRef.navigate(route, navParams)
respond(ok(null))
break
}
case 'xuqm.closeWebView': {
if (!_navigationRef) {
respond(fail('navigation not available — call setXWebViewNavigationRef() in host app'))
break
}
_navigationRef.goBack()
respond(ok(null))
break
}
case 'xuqm.showToast': {
const message = params.message
if (typeof message !== 'string') {
respond(fail('params.message is required'))
break
}
showToast(message)
respond(ok(null))
break
}
case 'xuqm.scanQRCode': {
if (!_scanQRCodeHandler) {
respond(
fail('scanQRCode not available — call setXWebViewScanQRCodeHandler() in host app'),
)
break
}
const result = await _scanQRCodeHandler()
respond(ok(result))
break
}
default:
// Unknown xuqm.* action — not handled by built-in bridge
return false
}
} catch (err) {
respond(fail(err instanceof Error ? err.message : String(err)))
}
return true
}
// ─── Config + Controller ───────────────────────────────────────────────────────
let _config: XWebViewConfig = {}
let _controller: XWebViewControllerAPI | null = null
export function openXWebView(navigate: (pluginId: string) => void, config: XWebViewConfig) {
_config = { ...config }
navigate('xwebview')
}
export function getXWebViewConfig(): XWebViewConfig {
return _config
}
export function setXWebViewController(controller: XWebViewControllerAPI | null) {
_controller = controller
}
export const XWebViewControl: XWebViewControllerAPI = {
refresh: () => _controller?.refresh(),
close: () => _controller?.close(),
goBack: () => _controller?.goBack(),
goForward: () => _controller?.goForward(),
copyUrl: () => _controller?.copyUrl(),
postMessageToWeb: js => _controller?.postMessageToWeb(js),
getTitle: () => _controller?.getTitle() ?? '',
getNavigationState: () =>
_controller?.getNavigationState() ?? {
canGoBack: false,
canGoForward: false,
title: '',
url: '',
},
}

99
packages/common/src/xwebview/types.ts 普通文件
查看文件

@ -0,0 +1,99 @@
import type React from 'react'
export type XWebViewClickMenu = {
view?: React.ReactNode
onClick: () => void
}
export type XWebViewMessageEvent = {
nativeEvent: { data: string }
}
export type XWebViewPermissionRequest = {
origin: string
resources: string[]
grant: (resources?: string[]) => void
deny: () => void
}
export type XWebViewDownloadRequest = {
url: string
suggestedFilename: string
mimeType?: string
fileSize?: number
}
export type XWebViewDownloadDecision = {
allowed: boolean
filename?: string
savePath?: string
}
export type XWebViewDownloadProgress = {
url: string
filename: string
received: number
total: number
percentage: number
}
export type XWebViewDownloadResult = {
url: string
filename: string
filePath: string
fileSize: number
}
export type XWebViewNavigationState = {
canGoBack: boolean
canGoForward: boolean
title: string
url: string
}
export type XWebViewControllerAPI = {
refresh: () => void
close: () => void
goBack: () => void
goForward: () => void
copyUrl: () => void
postMessageToWeb: (jsString: string) => void
getTitle: () => string
getNavigationState: () => XWebViewNavigationState
}
export type XWebViewDownloadDestination = 'sandbox' | 'publicDownloads'
export type XWebViewConfig = {
showTopBar?: boolean
showStatusBar?: boolean
doubleBackExit?: boolean
title?: string
showTitle?: boolean
autoTitle?: boolean
showMenu?: boolean
openForBrowser?: boolean
clickMenu?: XWebViewClickMenu
url?: string
/** 首次加载 URL 时携带的请求头，适用于需要会话鉴权的业务 H5。 */
headers?: Record<string, string>
content?: string
onMessage?: (event: XWebViewMessageEvent) => void
onNavigationStateChange?: (state: XWebViewNavigationState) => void
injectedJavaScript?: string
onPermissionRequest?: (request: XWebViewPermissionRequest) => void
autoDownload?: boolean
onDownloadStart?: (request: XWebViewDownloadRequest) => void
onDownloadProgress?: (progress: XWebViewDownloadProgress) => void
onDownloadComplete?: (result: XWebViewDownloadResult) => void
onDownloadError?: (url: string, error: string) => void
onDownloadDecide?: (
request: XWebViewDownloadRequest,
) => XWebViewDownloadDecision | Promise<XWebViewDownloadDecision>
downloadConflict?: 'rename' | 'overwrite'
/** 下载保存位置；与原生 Android SDK FileDownloadDestination 对齐。 */
downloadDestination?: XWebViewDownloadDestination
/** 非空时显示状态栏下载进度通知。 */
downloadNotificationTitle?: string
onClose?: () => void
}

42
packages/common/tests/api-diagnostics.test.ts
查看文件

@ -2,13 +2,7 @@ import assert from 'node:assert/strict'
import test from 'node:test' import test from 'node:test'
import type { AxiosResponse } from 'axios' import type { AxiosResponse } from 'axios'
import { import { createResponseDiagnostic, createValidationDiagnostic } from '../src/api/diagnostics'
createResponseDiagnostic,
createSafeApiErrorReport,
createValidationDiagnostic,
safeRequestPath,
} from '../src/api/diagnostics'
import { RequestError } from '../src/api/errors'
function sensitiveResponse(): AxiosResponse<unknown> { function sensitiveResponse(): AxiosResponse<unknown> {
return { return {
@ -42,14 +36,6 @@ test('API diagnostics only retain non-sensitive request shape', () => {
assert.doesNotMatch(serialized, /secret|phone|token|authorization|example\.com/) assert.doesNotMatch(serialized, /secret|phone|token|authorization|example\.com/)
}) })
test('request paths remove hosts, query parameters and fragments', () => {
assert.equal(
safeRequestPath('https://api.example.com/am/example?phone=13800000000#secret'),
'/am/example',
)
assert.equal(safeRequestPath('/am/example?token=secret'), '/am/example')
})
test('validation diagnostics retain issue paths without response data', () => { test('validation diagnostics retain issue paths without response data', () => {
const diagnostic = createValidationDiagnostic(sensitiveResponse(), [ const diagnostic = createValidationDiagnostic(sensitiveResponse(), [
{ {
@ -64,29 +50,3 @@ test('validation diagnostics retain issue paths without response data', () => {
const serialized = JSON.stringify(diagnostic) const serialized = JSON.stringify(diagnostic)
assert.doesNotMatch(serialized, /secret|13800000000|authorization|example\.com/) assert.doesNotMatch(serialized, /secret|13800000000|authorization|example\.com/)
}) })
test('global API error reports never expose RequestError causes', () => {
const response = sensitiveResponse()
const cause = {
issues: [
{
code: 'invalid_type',
expected: 'string',
message: 'Invalid input: expected string, received number',
path: ['data', 'userId'],
},
],
response,
}
const report = createSafeApiErrorReport(
new RequestError('server message may contain private data', 'ValidationError', cause),
)
assert.equal(report.requestType, 'ValidationError')
assert.equal(report.diagnostic?.type, 'ValidationError')
const serialized = JSON.stringify(report)
assert.doesNotMatch(
serialized,
/private|secret|13800000000|authorization|example\.com|server message/,
)
})

47
packages/common/tests/crypto.test.ts
查看文件

@ -1,15 +1,50 @@
import assert from 'node:assert/strict' import assert from 'node:assert/strict'
import test from 'node:test' import test from 'node:test'
import { decryptXuqmFile, hmacSha256Base64Url } from '../src/crypto'
import { hmacSha256Base64Url, sha256Hex } from '../src/crypto' const CONFIG_VECTOR =
'XUQM-CONFIG-V1.AAECAwQFBgcICQoLDA0ODw.EBESExQVFhcYGRob.vhdKh3AhEdeftXCdXp9KusVySkrBNAzmdaA747uf1tVWGFnAsJeCLe2mHKk0dxxez8SRTknIbk1UuRibnXY0Gbot1fmkR-jSN2ssMJO0_zQ8dUu8'
test('sha256Hex uses the canonical lowercase digest', () => { test('hmacSha256Base64Url matches the standard HMAC-SHA256 vector', () => {
assert.equal( assert.equal(
sha256Hex('xuqm'), hmacSha256Base64Url('key', 'The quick brown fox jumps over the lazy dog'),
'8d7c5b94129df39d6bec13e9fed29bb15fd1715f2e75a506436d9464bd38250c', '97yD9DBThCSxMpjmqm-xQ-9NWaFJRhdZl0edvC0aPNg',
) )
}) })
test('hmacSha256Base64Url returns an unpadded URL-safe value', () => { test('decryptXuqmFile remains compatible with existing PBKDF2 + AES-256-GCM files', async () => {
assert.match(hmacSha256Base64Url('secret', 'payload'), /^[A-Za-z0-9_-]+$/) await assert.doesNotReject(async () => {
const result = await decryptXuqmFile(CONFIG_VECTOR)
assert.deepEqual(result, {
appKey: 'test-app',
appName: '兼容向量',
signingKey: 'secret',
})
})
})
test('decryptXuqmFile does not depend on a React Native TextDecoder polyfill', async () => {
const original = globalThis.TextDecoder
Object.defineProperty(globalThis, 'TextDecoder', {
configurable: true,
value: class BrokenTextDecoder {
decode(): string {
return '[object Uint8Array]'
}
},
})
try {
const result = await decryptXuqmFile(CONFIG_VECTOR)
assert.equal(result.appName, '兼容向量')
} finally {
Object.defineProperty(globalThis, 'TextDecoder', {
configurable: true,
value: original,
})
}
})
test('decryptXuqmFile rejects invalid authentication tags', async () => {
await assert.rejects(() => decryptXuqmFile(`${CONFIG_VECTOR.slice(0, -1)}A`), /decryption failed/)
}) })

13
packages/common/tests/fixtures/README.md vendored
查看文件

@ -1,13 +0,0 @@
# 测试夹具
`rn-release-signature-vector.generated.json` 由 Server 仓库的
`update-service/src/test/resources/rn-release-signature-vector.json` 生成。
**GENERATED / DO NOT EDIT**：禁止手工修改。Server 是唯一规范源，更新时执行：
```bash
node scripts/sync-server-signature-vector.mjs --write
node scripts/sync-server-signature-vector.mjs --check
```
该文件只位于测试目录，不进入 `@xuqm/rn-common` 发布包。

4
packages/common/tests/fixtures/common-only.js vendored
查看文件

@ -1,4 +0,0 @@
// 真实 Metro fixture：不使用 withXuqmConfig，也不提供 .xuqmconfig。
const config = require('@xuqm/rn-common/auto-init-config')
module.exports = config.RESOLVED_CONFIG === undefined

6
packages/common/tests/fixtures/public-api.ts vendored
查看文件

@ -1,6 +0,0 @@
import { XuqmSDK } from '@xuqm/rn-common'
void XuqmSDK.awaitInitialization()
// @ts-expect-error 平台签发配置 + Metro 是唯一初始化入口。
void XuqmSDK.initialize({ appKey: 'manual-init-is-not-public' })

6
packages/common/tests/fixtures/rn-release-signature-vector.generated.json vendored
查看文件

@ -1,6 +0,0 @@
{
"keyId": "xuqm-rn-vector-2026-07",
"publicKeyRawBase64": "jkw/1R5aVg2NAwB7+xw2fR9i8phXi+2jt9l8QzuG8pU=",
"canonicalJson": "{\"appKey\":\"ak_vector\",\"appVersionRange\":\">=8.0.0 <9.0.0\",\"archiveSha256\":\"1111111111111111111111111111111111111111111111111111111111111111\",\"buildId\":\"build-42\",\"builtAgainstNativeBaselineId\":\"android-sha256:abc\",\"bundleFormat\":\"hermes-bytecode\",\"bundleSha256\":\"0000000000000000000000000000000000000000000000000000000000000000\",\"minNativeApiLevel\":2,\"moduleId\":\"common\",\"packageName\":\"com.xuqm.vector\",\"platform\":\"ANDROID\",\"type\":\"common\",\"version\":\"1.2.3\"}",
"signatureBase64Url": "p5GHekcL-wqM9yC7xNGRLMEwNVy7ECwVGwIdWkMJ9G85Pgr4XXca3kBXm3G-hLB0XZa76_tVmBNJhHkUuse6AQ"
}

7
packages/common/tests/fixtures/tsconfig.json vendored
查看文件

@ -1,7 +0,0 @@
{
"extends": "../../../../tsconfig.json",
"compilerOptions": {
"noEmit": true
},
"include": ["./public-api.ts"]
}

26
packages/common/tests/http.test.ts
查看文件

@ -1,26 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { apiRequest, configureHttp } from '../src/http'
test('apiRequest aborts a stalled request at the shared timeout boundary', async () => {
const originalFetch = globalThis.fetch
configureHttp({ baseUrl: 'https://platform.example.test' })
globalThis.fetch = async (_input, init) =>
new Promise((_resolve, reject) => {
init?.signal?.addEventListener(
'abort',
() => reject(init.signal?.reason ?? new Error('aborted')),
{ once: true },
)
})
try {
await assert.rejects(
() => apiRequest('/api/v1/rn/release-set/check', { skipAuth: true, timeoutMs: 5 }),
/Request timed out after 5ms/,
)
} finally {
globalThis.fetch = originalFetch
}
})

7
packages/common/tests/lifecycle.test.ts
查看文件

@ -15,10 +15,7 @@ test('all extensions observe the same initialized config exactly once', async ()
}) })
initConfigFromRemote( initConfigFromRemote(
{ { appKey: 'shared-app' },
appKey: 'shared-app',
platformUrl: 'https://platform.example.test',
},
{ {
apiUrl: 'https://api.example.test', apiUrl: 'https://api.example.test',
imApiUrl: 'https://im.example.test', imApiUrl: 'https://im.example.test',
@ -27,8 +24,6 @@ test('all extensions observe the same initialized config exactly once', async ()
await _notifyInitialized() await _notifyInitialized()
assert.equal(getConfig().apiUrl, 'https://api.example.test') assert.equal(getConfig().apiUrl, 'https://api.example.test')
assert.equal(getConfig().platformUrl, 'https://platform.example.test')
assert.equal(getConfig().updateEnabled, false)
assert.deepEqual(observed, ['shared-app:https://api.example.test']) assert.deepEqual(observed, ['shared-app:https://api.example.test'])
unregister() unregister()
}) })

44
packages/common/tests/metro-bundle.test.cjs
查看文件

@ -1,44 +0,0 @@
const assert = require('node:assert/strict')
const { execFileSync } = require('node:child_process')
const { createRequire } = require('node:module')
const fs = require('node:fs')
const os = require('node:os')
const path = require('node:path')
const test = require('node:test')
test('common-only host bundles the default auto-init module with real Metro', async () => {
const workspaceRoot = path.resolve(__dirname, '../../..')
const outputDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-common-only-'))
const output = path.join(outputDirectory, 'common-only.bundle.js')
try {
const reactNativeRequire = createRequire(
require.resolve('react-native/package.json', { paths: [workspaceRoot] }),
)
const metro = reactNativeRequire('metro')
const metroConfig = reactNativeRequire('metro-config')
const config = await metroConfig.getDefaultConfig(workspaceRoot)
config.watchFolders = [workspaceRoot]
config.resolver.extraNodeModules = {
'metro-runtime': path.dirname(reactNativeRequire.resolve('metro-runtime/package.json')),
}
await metro.runBuild(config, {
dev: false,
entry: 'packages/common/tests/fixtures/common-only.js',
minify: false,
out: output,
platform: 'android',
})
assert.equal(fs.statSync(output).size > 0, true)
} finally {
fs.rmSync(outputDirectory, { recursive: true, force: true })
}
})
test('public types expose no manual initialization entry', () => {
const workspaceRoot = path.resolve(__dirname, '../../..')
execFileSync(
path.join(workspaceRoot, 'node_modules/.bin/tsc'),
['-p', path.join(__dirname, 'fixtures/tsconfig.json')],
{ cwd: workspaceRoot, stdio: 'pipe' },
)
})

66
packages/common/tests/metro.test.cjs
查看文件

@ -6,9 +6,6 @@ const test = require('node:test')
const { withXuqmConfig } = require('../metro') const { withXuqmConfig } = require('../metro')
const CONFIG_VECTOR =
'XUQM-CONFIG-V2.xuqm-config-dev-2026-07.AAECAwQFBgcICQoLDA0ODw.EBESExQVFhcYGRob.MYRqE2BtQG0PvSnG3TLrr4PXd10C1cHhNA2iJLfy60XmQ5ixQBTCpn4e2g2YN0QQbZY0LVnou1rGONIzMrT7VidOMi_lHSfUf2BXnqlCIRm4yKcYCvALvrIF-Llv2xQWla0BTpKNq2Yuejpsw0oGTZGjNkvmlbBu8JJHAckHi-wP1sAgZuKVjjtJnjc7venWzaa75KwsqOYiNOkhIjWqTLNMG1siCMbX96d2A15KJYRUpwd-rBSpgjmOFLdH6DDaj2ZqCqQg6NRJprjsEorrCAnDjRjwoMKqHiIwHErfihw3v0AO19MJUzCeYzCzU2WfFw.Z-NMbyec47P4K_lfx3l7s3jZJVpd7ru8ySj2eBvXfteU4tVBoJ_3N7IRPMeiv1lUxMchsvNg8okxYpcBs4_2CQ'
test('withXuqmConfig schedules automatic initialization before the app entry', () => { test('withXuqmConfig schedules automatic initialization before the app entry', () => {
const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-metro-')) const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-metro-'))
const configDir = path.join(projectRoot, 'src/assets/config') const configDir = path.join(projectRoot, 'src/assets/config')
@ -16,7 +13,7 @@ test('withXuqmConfig schedules automatic initialization before the app entry', (
try { try {
fs.mkdirSync(configDir, { recursive: true }) fs.mkdirSync(configDir, { recursive: true })
fs.writeFileSync(path.join(configDir, 'app.xuqmconfig'), CONFIG_VECTOR, 'utf8') fs.writeFileSync(path.join(configDir, 'app.xuqmconfig'), 'XUQM-CONFIG-V1.test', 'utf8')
const config = withXuqmConfig({ const config = withXuqmConfig({
projectRoot, projectRoot,
@ -32,52 +29,11 @@ test('withXuqmConfig schedules automatic initialization before the app entry', (
const virtualModule = config.resolver.resolveRequest( const virtualModule = config.resolver.resolveRequest(
{ resolveRequest: () => assert.fail('fallback resolver should not run') }, { resolveRequest: () => assert.fail('fallback resolver should not run') },
'@xuqm/rn-common/auto-init-config', '@xuqm/autoinit-config',
'android', 'android',
) )
assert.equal(virtualModule.type, 'sourceFile') assert.equal(virtualModule.type, 'sourceFile')
const generatedSource = fs.readFileSync(virtualModule.filePath, 'utf8') assert.match(fs.readFileSync(virtualModule.filePath, 'utf8'), /XUQM-CONFIG-V1\.test/)
assert.match(generatedSource, /RESOLVED_CONFIG/)
assert.match(generatedSource, /"appKey":"test-app"/)
assert.equal(generatedSource.includes('XUQM-CONFIG-V2'), false)
} finally {
fs.rmSync(projectRoot, { recursive: true, force: true })
}
})
test('withXuqmConfig rejects legacy V1 files with a migration instruction', () => {
const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-metro-'))
const configDir = path.join(projectRoot, 'src/assets/config')
try {
fs.mkdirSync(configDir, { recursive: true })
fs.writeFileSync(
path.join(configDir, 'config.xuqmconfig'),
'XUQM-CONFIG-V1.invalid.invalid.invalid',
'utf8',
)
assert.throws(
() => withXuqmConfig({ projectRoot }),
/仅支持 XUQM-CONFIG-V2；请从租户平台重新下载配置文件/,
)
} finally {
fs.rmSync(projectRoot, { recursive: true, force: true })
}
})
test('withXuqmConfig rejects a modified V2 signature before decrypting content', () => {
const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-metro-'))
const configDir = path.join(projectRoot, 'src/assets/config')
try {
fs.mkdirSync(configDir, { recursive: true })
const parts = CONFIG_VECTOR.split('.')
parts[5] = `${parts[5][0] === 'A' ? 'B' : 'A'}${parts[5].slice(1)}`
const tampered = parts.join('.')
fs.writeFileSync(path.join(configDir, 'config.xuqmconfig'), tampered, 'utf8')
assert.throws(() => withXuqmConfig({ projectRoot }), /配置文件签名验证失败/)
assert.equal(
fs.existsSync(path.join(projectRoot, 'android/app/src/main/assets/config/config.xuqmconfig')),
false,
)
} finally { } finally {
fs.rmSync(projectRoot, { recursive: true, force: true }) fs.rmSync(projectRoot, { recursive: true, force: true })
} }
@ -98,19 +54,3 @@ test('withXuqmConfig leaves common-only hosts unchanged without a config file',
fs.rmSync(projectRoot, { recursive: true, force: true }) fs.rmSync(projectRoot, { recursive: true, force: true })
} }
}) })
test('withXuqmConfig rejects ambiguous config directories instead of choosing a file', () => {
const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xuqm-metro-'))
const configDir = path.join(projectRoot, 'src/assets/config')
try {
fs.mkdirSync(configDir, { recursive: true })
fs.writeFileSync(path.join(configDir, 'app.xuqmconfig'), CONFIG_VECTOR, 'utf8')
fs.writeFileSync(path.join(configDir, 'tenant.xuqmconfig'), CONFIG_VECTOR, 'utf8')
assert.throws(
() => withXuqmConfig({ projectRoot }),
/只能存在一个 \.xuqmconfig 文件，当前发现 2 个/,
)
} finally {
fs.rmSync(projectRoot, { recursive: true, force: true })
}
})

74
packages/common/tests/plugin-signature.test.ts
查看文件

@ -1,74 +0,0 @@
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import test from 'node:test'
import { decodeBase64 } from '../security/base64.js'
import {
PluginManifestSignatureError,
verifySignedPluginManifest,
type SignedPluginManifest,
} from '../src/internalSecurity'
import { canonicalJson } from '../security/canonical-json.js'
interface ServerSignatureVector {
keyId: string
publicKeyRawBase64: string
canonicalJson: string
signatureBase64Url: string
}
const vectorPath = new URL('./fixtures/rn-release-signature-vector.generated.json', import.meta.url)
const vector = JSON.parse(readFileSync(vectorPath, 'utf8')) as ServerSignatureVector
const manifest = JSON.parse(vector.canonicalJson) as SignedPluginManifest
const trustedKeys = { [vector.keyId]: vector.publicKeyRawBase64 }
test('accepts the Server-owned Ed25519 verification vector byte-for-byte', () => {
assert.deepEqual(
Buffer.from(canonicalJson(manifest), 'utf8'),
Buffer.from(vector.canonicalJson, 'utf8'),
)
assert.equal(decodeBase64(vector.publicKeyRawBase64).length, 32)
assert.equal(decodeBase64(vector.signatureBase64Url).length, 64)
assert.doesNotThrow(() =>
verifySignedPluginManifest(manifest, vector.keyId, vector.signatureBase64Url, trustedKeys),
)
})
test('canonical manifest omits null fields used only by non-common modules', () => {
assert.equal(
canonicalJson({ moduleId: 'common', commonVersionRange: null }),
'{"moduleId":"common"}',
)
})
test('rejects an unknown plugin signing key', () => {
assert.throws(
() => verifySignedPluginManifest(manifest, 'unknown', vector.signatureBase64Url, trustedKeys),
(error: unknown) =>
error instanceof PluginManifestSignatureError && error.code === 'UNKNOWN_SIGNING_KEY',
)
})
test('rejects any immutable manifest field tampering', () => {
assert.throws(
() =>
verifySignedPluginManifest(
{ ...manifest, bundleSha256: 'b'.repeat(64) },
vector.keyId,
vector.signatureBase64Url,
trustedKeys,
),
(error: unknown) =>
error instanceof PluginManifestSignatureError && error.code === 'INVALID_SIGNATURE',
)
assert.throws(
() =>
verifySignedPluginManifest(
{ ...manifest, archiveSha256: 'd'.repeat(64) },
vector.keyId,
vector.signatureBase64Url,
trustedKeys,
),
(error: unknown) =>
error instanceof PluginManifestSignatureError && error.code === 'INVALID_SIGNATURE',
)
})

24
packages/common/tests/remote-config.test.ts
查看文件

@ -1,24 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { normalizeRemoteConfig, parseCachedRemoteConfig } from '../src/remoteConfig'
test('platform update feature is authoritative over the flat compatibility field', () => {
assert.equal(
normalizeRemoteConfig({ features: { update: false }, updateEnabled: true }).updateEnabled,
false,
)
assert.equal(normalizeRemoteConfig({ updateEnabled: true }).updateEnabled, true)
})
test('missing update feature stays absent so XuqmConfig can safely default it off', () => {
assert.equal(normalizeRemoteConfig({}).updateEnabled, undefined)
assert.deepEqual(parseCachedRemoteConfig({ apiUrl: 'https://api.example.test' }), {
apiUrl: 'https://api.example.test',
})
})
test('cached update availability is preserved exactly', () => {
assert.equal(parseCachedRemoteConfig({ updateEnabled: true })?.updateEnabled, true)
assert.equal(parseCachedRemoteConfig({ updateEnabled: false })?.updateEnabled, false)
})

34
packages/common/tests/retry.test.ts
查看文件

@ -1,34 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { retryWithBackoff } from '../src/retry'
test('retryWithBackoff succeeds within the bounded three-attempt policy', async () => {
let attempts = 0
const value = await retryWithBackoff(
async () => {
attempts += 1
if (attempts < 3) throw new Error('temporary')
return 'ok'
},
{ baseDelayMs: 0, jitterRatio: 0 },
)
assert.equal(value, 'ok')
assert.equal(attempts, 3)
})
test('retryWithBackoff stops immediately for non-retryable errors', async () => {
let attempts = 0
await assert.rejects(
() =>
retryWithBackoff(
async () => {
attempts += 1
throw new Error('disabled')
},
{ baseDelayMs: 0, shouldRetry: () => false },
),
/disabled/,
)
assert.equal(attempts, 1)
})

52
packages/common/tests/sdk.test.ts
查看文件

@ -1,30 +1,19 @@
import assert from 'node:assert/strict' import assert from 'node:assert/strict'
import test from 'node:test' import test from 'node:test'
import { apiRequest } from '../src/http' import { _initializeFromConfigFile, awaitInitialization } from '../src/sdk'
import { getConfig, getInitializationSnapshot } from '../src/config'
import { _initializeFromResolvedConfig, awaitInitialization, XuqmSDK } from '../src/sdk'
test('public SDK has no second manual initialization entry', () => { const CONFIG_VECTOR =
assert.equal('initialize' in XuqmSDK, false) 'XUQM-CONFIG-V1.AAECAwQFBgcICQoLDA0ODw.EBESExQVFhcYGRob.vhdKh3AhEdeftXCdXp9KusVySkrBNAzmdaA747uf1tVWGFnAsJeCLe2mHKk0dxxez8SRTknIbk1UuRibnXY0Gbot1fmkR-jSN2ssMJO0_zQ8dUu8'
})
test('awaitInitialization retries a transient config request without leaking failure to the host', async () => { test('awaitInitialization observes in-flight work and retries a transient config request failure', async () => {
const originalFetch = globalThis.fetch const originalFetch = globalThis.fetch
let requestCount = 0 let requestCount = 0
const requestedUrls: string[] = [] globalThis.fetch = async () => {
globalThis.fetch = async input => {
requestCount += 1 requestCount += 1
requestedUrls.push(String(input))
if (requestCount === 1) { if (requestCount === 1) {
throw new TypeError('Network request failed') throw new TypeError('Network request failed')
} }
if (requestCount === 3) {
return new Response(JSON.stringify({ data: { available: true } }), {
headers: { 'content-type': 'application/json' },
status: 200,
})
}
return new Response( return new Response(
JSON.stringify({ JSON.stringify({
data: { data: {
@ -39,32 +28,15 @@ test('awaitInitialization retries a transient config request without leaking fai
} }
try { try {
const autoInitialization = _initializeFromResolvedConfig( const autoInitialization = _initializeFromConfigFile(CONFIG_VECTOR, {
{ debug: true,
appKey: 'test-app', })
appName: '测试应用', await assert.rejects(() => awaitInitialization(), /Network request failed/)
configId: '123e4567-e89b-42d3-a456-426614174000', await assert.rejects(() => autoInitialization, /Network request failed/)
issuedAt: '2026-07-26T00:00:00Z',
revision: 1, // 配置内容由 common 保存，扩展包再次等待时可以自行重试，无需宿主传递配置。
schemaVersion: 2,
serverUrl: 'https://dev.xuqinmin.com',
signingKey: 'secret',
},
{ debug: true },
)
await assert.doesNotReject(() => autoInitialization)
await assert.doesNotReject(() => awaitInitialization()) await assert.doesNotReject(() => awaitInitialization())
assert.equal(requestCount, 2) assert.equal(requestCount, 2)
assert.deepEqual(getInitializationSnapshot(), { state: 'ready', source: 'remote' })
assert.equal(getConfig().updateEnabled, false)
assert.equal(getConfig().updateRequiresLogin, true)
const result = await apiRequest<{ available: boolean }>('/api/v1/rn/release-set/check', {
skipAuth: true,
})
assert.deepEqual(result, { available: true })
assert.equal(requestedUrls[2], 'https://dev.xuqinmin.com/api/v1/rn/release-set/check')
assert.equal(requestedUrls[2]?.includes('api.example.test'), false)
} finally { } finally {
globalThis.fetch = originalFetch globalThis.fetch = originalFetch
} }

28
packages/common/tests/secureCache.test.ts
查看文件

@ -1,28 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { isCacheRecordFresh, openLocalCache, sealLocalCache } from '../src/secureCache'
test('LKG cache round-trips with context-bound authenticated encryption', () => {
const encrypted = sealLocalCache('{"enabled":true}', 'signed-secret', 'app|package|environment')
assert.equal(
openLocalCache(encrypted, 'signed-secret', 'app|package|environment'),
'{"enabled":true}',
)
assert.equal(encrypted.includes('enabled'), false)
})
test('LKG cache rejects tampering and a different package/environment context', () => {
const encrypted = sealLocalCache('payload', 'signed-secret', 'app|package|environment')
const parts = encrypted.split('.')
parts[2] = `${parts[2][0] === 'A' ? 'B' : 'A'}${parts[2].slice(1)}`
assert.throws(() => openLocalCache(parts.join('.'), 'signed-secret', 'app|package|environment'))
assert.throws(() => openLocalCache(encrypted, 'signed-secret', 'app|other|environment'))
})
test('LKG freshness rejects future timestamps and expired records', () => {
const now = 1_000_000
assert.equal(isCacheRecordFresh(now - 1_000, now, 2_000), true)
assert.equal(isCacheRecordFresh(now - 2_001, now, 2_000), false)
assert.equal(isCacheRecordFresh(now + 1, now, 2_000), false)
})

64
packages/common/tests/security-primitives.test.ts
查看文件

@ -1,64 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { decodeBase64, encodeBase64 } from '../security/base64.js'
import { canonicalJson } from '../security/canonical-json.js'
test('strict Base64 decoder supports padded, unpadded and URL-safe inputs without atob', () => {
assert.deepEqual([...decodeBase64('TQ==')], [77])
assert.deepEqual([...decodeBase64('TWE=')], [77, 97])
assert.deepEqual([...decodeBase64('TWFu')], [77, 97, 110])
assert.deepEqual([...decodeBase64('AQIDBA==')], [1, 2, 3, 4])
assert.deepEqual([...decodeBase64('AQIDBA')], [1, 2, 3, 4])
assert.deepEqual([...decodeBase64('-_8=')], [251, 255])
})
test('strict Base64 decoder rejects invalid alphabets, lengths, padding and trailing bits', () => {
for (const value of [
'A',
'A+_-',
'AA=A',
'AA===',
'AAA==',
'TQ=',
'TWE==',
'TQ===',
'TQ==AA',
'TR==',
'TWF=',
'AA!A',
]) {
assert.throws(() => decodeBase64(value), /Base64/)
}
})
test('pure JS Base64 encoder emits canonical standard and URL-safe forms', () => {
assert.equal(encodeBase64(new Uint8Array()), '')
assert.equal(encodeBase64(Uint8Array.of(77)), 'TQ==')
assert.equal(encodeBase64(Uint8Array.of(77, 97)), 'TWE=')
assert.equal(encodeBase64(Uint8Array.of(77, 97, 110)), 'TWFu')
assert.equal(encodeBase64(Uint8Array.of(251, 255), { urlSafe: true }), '-_8=')
assert.equal(encodeBase64(Uint8Array.of(251, 255), { urlSafe: true, padding: false }), '-_8')
assert.throws(() => encodeBase64([1, 2, 3] as unknown as Uint8Array), /Uint8Array/)
})
test('Base64 codec round-trips chunk boundaries and matches the Node reference', () => {
for (const length of [0, 1, 2, 3, 4, 31, 32, 33, 255, 256, 257]) {
const input = Uint8Array.from({ length }, (_, index) => (index * 197 + 31) & 0xff)
const standard = encodeBase64(input)
const urlSafe = encodeBase64(input, { urlSafe: true, padding: false })
assert.equal(standard, Buffer.from(input).toString('base64'))
assert.equal(urlSafe, Buffer.from(input).toString('base64url'))
assert.deepEqual(decodeBase64(standard), input)
assert.deepEqual(decodeBase64(urlSafe), input)
}
})
test('canonical JSON rejects values that have no cross-runtime protocol representation', () => {
assert.throws(() => canonicalJson(Number.NaN), /finite numbers/)
assert.throws(() => canonicalJson(Number.POSITIVE_INFINITY), /finite numbers/)
assert.throws(() => canonicalJson(() => undefined), /does not support function/)
assert.throws(() => canonicalJson(Symbol('value')), /does not support symbol/)
assert.throws(() => canonicalJson([undefined]), /cannot contain holes or undefined/)
assert.throws(() => canonicalJson(new Array(1)), /cannot contain holes or undefined/)
assert.throws(() => canonicalJson(new Date(0)), /only supports plain objects/)
})

91
packages/update/README.md
查看文件

@ -13,39 +13,13 @@ pnpm exec xuqm-rn init
pnpm run xuqm:doctor pnpm run xuqm:doctor
``` ```
`xuqm-rn init` 生成 schema v3 `xuqm.modules.json` 并补充最少脚本。版本只有两条明确来源： `xuqm-rn init` 生成 schema v3 `xuqm.config.json` 并补充最少脚本。版本只有两条明确来源：
- 完整 App 版本来自宿主 `package.json.version`，医网信新包从 `8.0.0` 开始。 - 完整 App 版本来自宿主 `package.json.version`，医网信新包从 `8.0.0` 开始。
- 插件默认版本来自 `xuqm.modules.json.pluginVersion`，从 `1.0.0` 开始；仅独立发布的模块覆盖 `moduleVersion`。 - 插件默认版本来自 `xuqm.config.json.pluginVersion`，从 `1.0.0` 开始；仅独立发布的模块覆盖 `moduleVersion`。
`xuqm.modules.json` 分别使用 Android `packageName` 和 iOS `iosBundleId` 保存平台宿主
身份，只在目标平台 build/package/release 时要求相应字段。ZIP wire 字段仍统一为
`packageName`；CLI 通过唯一平台解析器写入对应身份，发布前从 ZIP 内重新读取并与同一
解析结果精确比较，缺失或不一致时在联网前拒绝发布。
Debug 启动只注册并校验插件，不访问远程更新服务。开发页如需验证平台能力，显式调用
`UpdateSDK.developer.checkStartupOnce()` 或
`UpdateSDK.developer.checkAndInstallPluginOnce(moduleId)`；该状态不会跨重启保留。
`xuqm-rn package android` 会为每次 Release 自动生成递增 `versionCode` 与不可变
`buildId`，并同时注入 APK、插件 manifest 和 Source Map 身份。宿主不得手工维护
versionCode；Jenkins 可通过 `XUQM_VERSION_CODE`、`XUQM_BUILD_ID` 固定本次流水线身份。
同一 `versionName` 的重复测试包仍会获得新的 versionCode/buildId，从而正常覆盖安装并
加载本次 Bundle。
app/buz 使用 `commonVersionRange` 声明 SemVer 兼容范围，并使用 `minNativeApiLevel` 声明最低原生能力。Bundle 只接受 SHA-256，不使用 MD5。 app/buz 使用 `commonVersionRange` 声明 SemVer 兼容范围，并使用 `minNativeApiLevel` 声明最低原生能力。Bundle 只接受 SHA-256，不使用 MD5。
宿主的唯一 Metro 配置使用 update 组合器；它已经包含 common 的自动初始化配置：
```js
const { getDefaultConfig } = require('@react-native/metro-config')
const { withXuqmModuleConfig } = require('@xuqm/rn-update/metro')
module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))
```
日常 `start/android` 没有模块构建上下文，保持标准 Metro 行为。构建 app/buz 时 CLI 自动先生成 startup/common 共享模块表，并为每个插件分配互不重叠的稳定区间；宿主不得复制模块 ID 缓存或维护多份 Metro 配置。
## 开发与打包 ## 开发与打包
- `pnpm android`：安装 Debug 包、连接 Metro、支持热刷新。 - `pnpm android`：安装 Debug 包、连接 Metro、支持热刷新。
@ -53,11 +27,6 @@ module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname))
- `pnpm release:android -- --apk`：生成包含同一批插件的 Release APK。 - `pnpm release:android -- --apk`：生成包含同一批插件的 Release APK。
- `pnpm publish:android`：上传插件产物；SDK npm 制品发布只能通过 Jenkins。 - `pnpm publish:android`：上传插件产物；SDK npm 制品发布只能通过 Jenkins。
发布使用的 `XUQM_API_TOKEN` 只能由 Jenkins Credentials 注入环境变量，不属于
`xuqm.modules.json` 或 `config.xuqmconfig`。CLI 不读取项目文件中的 Token，避免可用凭据
进入源码、插件包或构建日志。
配置校验会直接拒绝 `release.apiToken`；发布凭据只能来自 `XUQM_API_TOKEN`。
Android 宿主只应用一次 SDK 脚本： Android 宿主只应用一次 SDK 脚本：
```groovy ```groovy
@ -66,47 +35,13 @@ apply from: file("../../node_modules/@xuqm/rn-update/android/xuqm-bundles.gradle
该脚本关闭 React Native 默认单体 Bundle，避免宿主同时维护两套启动产物。 该脚本关闭 React Native 默认单体 Bundle，避免宿主同时维护两套启动产物。
多 Bundle 启动壳只需要查询原生分包路径时使用轻量子路径，禁止为了两个原生调用导入完整更新、网络与 release-set 实现：
```ts
import { NativeBundle } from '@xuqm/rn-update/native-bundle'
await NativeBundle.preparePendingRelease()
const commonPath = await NativeBundle.getLaunchPath('common')
const appPath = await NativeBundle.getLaunchPath('app')
```
启动壳只能依次准备并装载 common、app，不得读取 manifest 后枚举或释放 buz。普通业务继续从 `@xuqm/rn-update` 根入口使用 `UpdateSDK`/`XuqmRuntime`；该子路径只用于首屏启动壳和底层宿主编排，不是第二套状态或兼容 API。
多 bundle 宿主还必须在 common 入口保留轻量注册表：
```ts
import '@xuqm/rn-update/plugin-registry'
```
`app` 与各 `buz` 拥有隔离的模块编号区间，common 中预注册的 `plugin-registry` 保证插件执行 `definePlugin()` 后，宿主 `XuqmRuntime` 读取到同一份定义。SDK 的构建/脚手架应生成该入口，业务项目不得自行复制注册表。
同一规则适用于跨 Bundle React Context 和具有原生注册副作用的依赖：Provider 在 app 挂载、由 buz 消费的 Context，以及 app/buz 都会使用的原生 View/Module，必须由 common 入口静态持有并分配共享编号。禁止在插件中复制 Context、注册表，或让多个 Bundle 分别执行同名原生组件注册。
插件产物的引擎只有一个事实来源：Android 宿主的 `android/gradle.properties`。当 插件产物的引擎只有一个事实来源：Android 宿主的 `android/gradle.properties`。当
`hermesEnabled=true` 时，CLI 自动使用与宿主 React Native 匹配的 `hermes-compiler` 将每个 `hermesEnabled=true` 时，CLI 自动使用与宿主 React Native 匹配的 `hermes-compiler` 将每个
startup/common/app/buz 编译成 Hermes bytecode，并组合 Metro/Hermes source map；无需也不允许在 startup/common/app/buz 编译成 Hermes bytecode，并组合 Metro/Hermes source map；无需也不允许在
`xuqm.modules.json` 再声明一份引擎。manifest 和发布请求会记录 `bundleFormat`。 `xuqm.config.json` 再声明一份引擎。manifest 和发布请求会记录 `bundleFormat`。
## 运行时规则 ## 运行时规则
Android 启动只把 APK 内嵌版本当作可恢复基线，不会每次重新读取或复制大 Bundle：
- 原生模块每个进程只解析一次内嵌 `manifest.json`，随后以本地 `state.json` 为版本事实源。
- `getBundleState()` 是纯状态查询：已有本地状态时直接读取，尚未访问的模块只从 manifest 返回内嵌基线元数据，不创建目录、不复制 Bundle。安装/恢复只允许由目标模块的 launch path 请求触发。
- 本地下载版本 SemVer 大于等于内嵌版本，且 `nativeBaselineId`、`minNativeApiLevel` 和文件长度仍兼容时，直接返回现有 `active.bundle`。
- 本地文件由当前 APK 内嵌基线产生时，版本相同仍比较 manifest SHA-256；这样开发期同版本的新 APK 可以替换旧基线，完全相同的 APK 则直接短路。
- 只有首次安装、本地版本落后、原生基线不兼容、摘要/长度异常或 APK 内嵌内容变化时，才读取 APK 中的 Bundle，校验 SHA-256，并连同资源原子恢复。
因此“版本检查”不等于每次网络检查，也不等于解析 Bundle 内容。启动路径只做小状态读取；插件网络更新仍按下述入口策略执行。
上述恢复是严格的单模块按需操作：冷启动只触发 common、app；buz 在用户进入相应功能时才调用 `checkAndInstallPlugin(moduleId)` 和 `XuqmRuntime.activate(moduleId)`。健康的本地 buz 直接执行，缺失或不兼容时只处理目标 buz 与其 common 依赖，未访问插件不复制、不解压、不执行。
安装仅包含 buz 的 release set 后，使用 安装仅包含 buz 的 release set 后，使用
`XuqmRuntime.activate(moduleId, { reloadBundle: true })` 重新求值并激活新 bundle。若 release set `XuqmRuntime.activate(moduleId, { reloadBundle: true })` 重新求值并激活新 bundle。若 release set
包含 common，宿主必须冷启动，不能在同一 JavaScript VM 中混用新旧 common。 包含 common，宿主必须冷启动，不能在同一 JavaScript VM 中混用新旧 common。
@ -153,25 +88,7 @@ const plan = await UpdateSDK.checkAndInstallPlugin('prescription', {
}) })
``` ```
SDK 会验证所有已安装模块在目标 common 下仍兼容，并拒绝 `builtAgainstNativeBaselineId` 与当前完整包不一致的候选，然后整组下载、校验、staging、激活、确认或回滚。Bundle 版本与事务状态只保存在原生 state；宿主不得另建 AsyncStorage 版本表，也不得逐层传递版本或路径状态。 SDK 会验证所有已安装模块在目标 common 下仍兼容，然后整组下载、校验、staging、激活、确认或回滚。Bundle 版本与事务状态只保存在原生 state；宿主不得另建 AsyncStorage 版本表，也不得逐层传递版本或路径状态。
所有公开检查、下载和安装 API 都要求平台明确开启 `features.update`。关闭时在任何网络
或原生操作前抛出 `UpdateDisabledError`（`code: UPDATE_DISABLED`）；登录、启动等自动
后台路径会吞掉该状态并正常返回，不影响宿主使用。
release-set 检查请求必须携带当前 `appVersion`、`nativeApiLevel` 和
`nativeBaselineId`；原生基线缺失时客户端在请求前阻断。服务端候选必须提供
`keyId/signature`，签名覆盖以下不可变 canonical manifest：
`appKey, packageName, platform, moduleId, type, version, appVersionRange, builtAgainstNativeBaselineId, buildId, bundleFormat, minNativeApiLevel, bundleSha256, archiveSha256`
app/buz 另包含 `commonVersionRange`；common 模块不构造该字段。canonical JSON 与
Config V2 一致：UTF-8、键按字典序、无空白、null/undefined 字段省略。
客户端在生成计划前及安装前各验签一次，未知 keyId、签名错误、宿主身份不匹配或任一
字段被篡改都会拒绝。响应 `sha256` 以 `archiveSha256` 进入签名清单，下载后使用同值
校验 ZIP；Android 解包层还会把已签名的
`buildId/bundleFormat/bundleSha256` 与包内 manifest 逐项比较。
需要先展示插件更新提示的项目，分别调用纯检查和安装 API： 需要先展示插件更新提示的项目，分别调用纯检查和安装 API：

3
packages/update/android/build.gradle
查看文件

@ -15,7 +15,7 @@ android {
} }
repositories { repositories {
maven { url = uri("https://nexus.xuqinmin.com/repository/android/") } maven { url "https://nexus.xuqinmin.com/repository/android/" }
mavenCentral() mavenCentral()
google() google()
} }
@ -23,5 +23,4 @@ repositories {
dependencies { dependencies {
implementation("com.facebook.react:react-android") implementation("com.facebook.react:react-android")
implementation("com.xuqm:sdk-update:2.0.0-SNAPSHOT") implementation("com.xuqm:sdk-update:2.0.0-SNAPSHOT")
testImplementation("junit:junit:4.13.2")
} }

457
packages/update/android/src/main/java/com/xuqm/update/XuqmBundleModule.java
查看文件

@ -1,8 +1,8 @@
package com.xuqm.update; package com.xuqm.update;
import android.content.Context; import android.content.Context;
import android.content.SharedPreferences; import android.system.ErrnoException;
import android.util.Base64; import android.system.Os;
import androidx.annotation.NonNull; import androidx.annotation.NonNull;
@ -21,29 +21,22 @@ import org.json.JSONObject;
import java.io.ByteArrayOutputStream; import java.io.ByteArrayOutputStream;
import java.io.File; import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException; import java.io.IOException;
import java.io.InputStream; import java.io.InputStream;
import java.nio.charset.StandardCharsets; import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.LinkedHashSet; import java.util.LinkedHashSet;
import java.util.Locale; import java.util.Locale;
import java.util.Set; import java.util.Set;
import static com.xuqm.update.XuqmBundleStorage.atomicWrite;
import static com.xuqm.update.XuqmBundleStorage.deleteIfExists;
import static com.xuqm.update.XuqmBundleStorage.deleteRecursively;
import static com.xuqm.update.XuqmBundleStorage.readBytes;
import static com.xuqm.update.XuqmBundleStorage.sha256;
import static com.xuqm.update.XuqmBundleStorage.verifySha256;
import static com.xuqm.update.XuqmPluginPackageStager.areAssetsPresent;
import static com.xuqm.update.XuqmPluginPackageStager.assetPaths;
import static com.xuqm.update.XuqmPluginPackageStager.validateAssetPath;
/** Owns embedded recovery and transactional activation for every RN plugin bundle. */ /** Owns embedded recovery and transactional activation for every RN plugin bundle. */
@ReactModule(name = XuqmBundleModule.NAME) @ReactModule(name = XuqmBundleModule.NAME)
public final class XuqmBundleModule extends ReactContextBaseJavaModule { public final class XuqmBundleModule extends ReactContextBaseJavaModule {
public static final String NAME = "XuqmBundleModule"; public static final String NAME = "XuqmBundleModule";
private static final int NATIVE_API_LEVEL = 2; private static final int NATIVE_API_LEVEL = 1;
private static final String BUNDLE_DIR = "rn-bundles"; private static final String BUNDLE_DIR = "rn-bundles";
private static final String EMBEDDED_DIR = "rn-bundles"; private static final String EMBEDDED_DIR = "rn-bundles";
private static final String ACTIVE_FILE = "active.bundle"; private static final String ACTIVE_FILE = "active.bundle";
@ -51,16 +44,6 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
private static final String ROLLBACK_FILE = "rollback.bundle"; private static final String ROLLBACK_FILE = "rollback.bundle";
private static final String STATE_FILE = "state.json"; private static final String STATE_FILE = "state.json";
private static final String RELEASE_STATE_FILE = "release-state.json"; private static final String RELEASE_STATE_FILE = "release-state.json";
private static final String ACTIVE_ASSETS_DIR = "active-assets";
private static final String STAGED_ASSETS_DIR = "staged-assets";
private static final String ROLLBACK_ASSETS_DIR = "rollback-assets";
private static final String PACKAGE_TEMP_DIR = "package-temp";
private static final String RESET_PREFERENCES = "xuqm-update-reset";
private static final String RESET_GENERATION = "generation";
private static final String CONFIRMED_RESET_GENERATION = "confirmed-generation";
/** APK 内嵌 manifest 很小且在进程生命周期内不可变，只解析一次。 */
private JSONObject embeddedManifestCache;
public XuqmBundleModule(ReactApplicationContext reactContext) { public XuqmBundleModule(ReactApplicationContext reactContext) {
super(reactContext); super(reactContext);
@ -77,52 +60,6 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
promise.resolve(NATIVE_API_LEVEL); promise.resolve(NATIVE_API_LEVEL);
} }
/**
* 原生恢复页的唯一清理入口。只删除 Update SDK 私有 rn-bundles 目录；
* 宿主账号、业务缓存和其它 SDK 数据均不在该目录中。
*/
@ReactMethod
public void resetToEmbedded(Promise promise) {
try {
deleteRecursively(getBundleDir());
embeddedManifestCache = null;
SharedPreferences preferences = getReactApplicationContext()
.getSharedPreferences(RESET_PREFERENCES, Context.MODE_PRIVATE);
int generation = preferences.getInt(RESET_GENERATION, 0) + 1;
preferences.edit().putInt(RESET_GENERATION, generation).apply();
promise.resolve(true);
} catch (Exception error) {
promise.reject("BUNDLE_RESET_ERROR", error.getMessage(), error);
}
}
@ReactMethod
public void getResetGeneration(Promise promise) {
SharedPreferences preferences = getReactApplicationContext()
.getSharedPreferences(RESET_PREFERENCES, Context.MODE_PRIVATE);
promise.resolve(preferences.getInt(RESET_GENERATION, 0));
}
@ReactMethod
public void getConfirmedResetGeneration(Promise promise) {
SharedPreferences preferences = getReactApplicationContext()
.getSharedPreferences(RESET_PREFERENCES, Context.MODE_PRIVATE);
promise.resolve(preferences.getInt(CONFIRMED_RESET_GENERATION, 0));
}
@ReactMethod
public void confirmResetGeneration(int generation, Promise promise) {
SharedPreferences preferences = getReactApplicationContext()
.getSharedPreferences(RESET_PREFERENCES, Context.MODE_PRIVATE);
int current = preferences.getInt(RESET_GENERATION, 0);
if (generation != current) {
promise.reject("BUNDLE_RESET_STALE", "Reset generation changed before confirmation");
return;
}
preferences.edit().putInt(CONFIRMED_RESET_GENERATION, generation).apply();
promise.resolve(true);
}
@ReactMethod @ReactMethod
public void bundleExists(String moduleId, Promise promise) { public void bundleExists(String moduleId, Promise promise) {
try { try {
@ -168,10 +105,8 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
@ReactMethod @ReactMethod
public void getBundleState(String moduleId, Promise promise) { public void getBundleState(String moduleId, Promise promise) {
try { try {
// 版本检查需要知道全部已交付模块的版本，但读取状态绝不能顺带安装它们。 ensureEmbeddedBundle(moduleId);
// 未访问的 buz 直接从小型内嵌 manifest 构造只读状态，真正进入插件时 promise.resolve(readState(moduleId).toString());
// getLaunchBundlePath(moduleId) 才按需恢复 Bundle 与资源。
promise.resolve(readBundleStateWithoutInstalling(moduleId).toString());
} catch (Exception error) { } catch (Exception error) {
promise.reject("BUNDLE_STATE_ERROR", error.getMessage(), error); promise.reject("BUNDLE_STATE_ERROR", error.getMessage(), error);
} }
@ -191,45 +126,6 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
} }
} }
@ReactMethod
public void getAssetIndex(Promise promise) {
try {
JSONObject index = new JSONObject();
File root = new File(getReactApplicationContext().getFilesDir(), BUNDLE_DIR);
// nativeApiLevel=1 曾把每个模块的 drawable-* 直接复制到模块根目录，
// 导致 app/szyx/miniapp 各自残留整套重复图片。新版资源只允许存在于
// active-assets 事务目录；首次刷新索引时顺带清理旧目录，不安装任何 buz。
cleanupLegacyAssetDirectories(root);
File[] modules = root.listFiles();
if (modules != null) {
for (File module : modules) {
if (!module.isDirectory()) continue;
collectAssetIndex(new File(module, ACTIVE_ASSETS_DIR), "", index);
}
}
promise.resolve(index.toString());
} catch (Exception error) {
promise.reject("ASSET_INDEX_ERROR", error.getMessage(), error);
}
}
private void cleanupLegacyAssetDirectories(File root) throws IOException {
File[] modules = root.listFiles();
if (modules == null) return;
for (File module : modules) {
if (!module.isDirectory()) continue;
File[] children = module.listFiles();
if (children == null) continue;
for (File child : children) {
if (!child.isDirectory()) continue;
String name = child.getName();
if (name.startsWith("drawable-") || "raw".equals(name)) {
deleteRecursively(child);
}
}
}
}
@ReactMethod @ReactMethod
public void writeManifest(String manifestJson, Promise promise) { public void writeManifest(String manifestJson, Promise promise) {
try { try {
@ -262,28 +158,17 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
if (module == null) throw new IllegalArgumentException("Invalid release module at " + index); if (module == null) throw new IllegalArgumentException("Invalid release module at " + index);
String moduleId = requiredString(module, "moduleId"); String moduleId = requiredString(module, "moduleId");
String version = requiredString(module, "version"); String version = requiredString(module, "version");
String archiveBase64 = requiredString(module, "archiveBase64"); String source = requiredString(module, "source");
String sha256 = requiredString(module, "sha256"); String sha256 = requiredString(module, "sha256");
validateModuleId(moduleId); validateModuleId(moduleId);
stagedModules.add(moduleId); verifyHash(source.getBytes(StandardCharsets.UTF_8), sha256);
byte[] archiveBytes = Base64.decode(archiveBase64, Base64.DEFAULT);
File moduleDirectory = getModuleDir(moduleId); File staged = new File(getModuleDir(moduleId), STAGED_FILE);
JSONObject packageManifest = XuqmPluginPackageStager.stage( atomicWrite(staged, source.getBytes(StandardCharsets.UTF_8));
moduleId,
archiveBytes,
sha256,
module,
new File(moduleDirectory, PACKAGE_TEMP_DIR),
new File(moduleDirectory, STAGED_FILE),
new File(moduleDirectory, STAGED_ASSETS_DIR));
JSONObject state = readState(moduleId); JSONObject state = readState(moduleId);
state.put("moduleId", moduleId); state.put("moduleId", moduleId);
state.put("pendingVersion", version); state.put("pendingVersion", version);
state.put("pendingBuildId", packageManifest.getString("buildId")); state.put("pendingHash", sha256.toLowerCase(Locale.ROOT));
state.put("pendingHash", packageManifest.getString("bundleSha256").toLowerCase(Locale.ROOT));
state.put("pendingPackageHash", sha256.toLowerCase(Locale.ROOT));
state.put("pendingByteLength", packageManifest.getLong("bundleByteLength"));
state.put("pendingAssetFiles", assetPaths(packageManifest));
state.put("pendingType", requiredString(module, "type")); state.put("pendingType", requiredString(module, "type"));
state.put("pendingAppVersionRange", requiredString(module, "appVersionRange")); state.put("pendingAppVersionRange", requiredString(module, "appVersionRange"));
copyOptionalString(module, "builtAgainstNativeBaselineId", state, "pendingBuiltAgainstNativeBaselineId"); copyOptionalString(module, "builtAgainstNativeBaselineId", state, "pendingBuiltAgainstNativeBaselineId");
@ -292,6 +177,7 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
state.put("releaseId", releaseId); state.put("releaseId", releaseId);
state.put("status", "staged"); state.put("status", "staged");
writeState(moduleId, state); writeState(moduleId, state);
stagedModules.add(moduleId);
moduleIds.put(moduleId); moduleIds.put(moduleId);
} }
@ -383,8 +269,8 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
JSONObject release = readReleaseStateOrNull(); JSONObject release = readReleaseStateOrNull();
if (release != null) { if (release != null) {
if ("pending_confirmation".equals(release.optString("status")) if ("pending_confirmation".equals(release.optString("status"))
&& release.optInt("launchAttempts", 0) < 2) { && release.optInt("launchAttempts", 0) == 0) {
release.put("launchAttempts", release.optInt("launchAttempts", 0) + 1); release.put("launchAttempts", 1);
writeReleaseState(release); writeReleaseState(release);
} else { } else {
JSONArray modules = release.getJSONArray("modules"); JSONArray modules = release.getJSONArray("modules");
@ -422,9 +308,7 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
private void activateModule(String moduleId, String releaseId) throws Exception { private void activateModule(String moduleId, String releaseId) throws Exception {
File directory = getModuleDir(moduleId); File directory = getModuleDir(moduleId);
File staged = new File(directory, STAGED_FILE); File staged = new File(directory, STAGED_FILE);
File stagedAssets = new File(directory, STAGED_ASSETS_DIR);
if (!staged.exists()) throw new IOException("No staged bundle for " + moduleId); if (!staged.exists()) throw new IOException("No staged bundle for " + moduleId);
if (!stagedAssets.isDirectory()) throw new IOException("No staged assets for " + moduleId);
JSONObject state = readState(moduleId); JSONObject state = readState(moduleId);
if (!releaseId.equals(state.optString("releaseId"))) { if (!releaseId.equals(state.optString("releaseId"))) {
throw new IOException("Staged bundle does not belong to release " + releaseId); throw new IOException("Staged bundle does not belong to release " + releaseId);
@ -432,29 +316,15 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
File active = new File(directory, ACTIVE_FILE); File active = new File(directory, ACTIVE_FILE);
File rollback = new File(directory, ROLLBACK_FILE); File rollback = new File(directory, ROLLBACK_FILE);
File activeAssets = new File(directory, ACTIVE_ASSETS_DIR);
File rollbackAssets = new File(directory, ROLLBACK_ASSETS_DIR);
boolean hadActive = active.exists(); boolean hadActive = active.exists();
deleteIfExists(rollback); deleteIfExists(rollback);
deleteRecursively(rollbackAssets);
if (hadActive && !active.renameTo(rollback)) { if (hadActive && !active.renameTo(rollback)) {
throw new IOException("Unable to preserve active bundle for " + moduleId); throw new IOException("Unable to preserve active bundle for " + moduleId);
} }
if (activeAssets.exists() && !activeAssets.renameTo(rollbackAssets)) {
if (rollback.exists()) rollback.renameTo(active);
throw new IOException("Unable to preserve active assets for " + moduleId);
}
if (!staged.renameTo(active)) { if (!staged.renameTo(active)) {
if (rollback.exists()) rollback.renameTo(active); if (rollback.exists()) rollback.renameTo(active);
if (rollbackAssets.exists()) rollbackAssets.renameTo(activeAssets);
throw new IOException("Unable to activate staged bundle for " + moduleId); throw new IOException("Unable to activate staged bundle for " + moduleId);
} }
if (!stagedAssets.renameTo(activeAssets)) {
deleteIfExists(active);
if (rollback.exists()) rollback.renameTo(active);
if (rollbackAssets.exists()) rollbackAssets.renameTo(activeAssets);
throw new IOException("Unable to activate staged assets for " + moduleId);
}
if (hadActive) copyActiveToRollbackMetadata(state); if (hadActive) copyActiveToRollbackMetadata(state);
else clearRollbackMetadata(state); else clearRollbackMetadata(state);
@ -472,213 +342,41 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
state.put("status", "active"); state.put("status", "active");
state.put("launchAttempts", 0); state.put("launchAttempts", 0);
deleteIfExists(new File(getModuleDir(moduleId), ROLLBACK_FILE)); deleteIfExists(new File(getModuleDir(moduleId), ROLLBACK_FILE));
deleteRecursively(new File(getModuleDir(moduleId), ROLLBACK_ASSETS_DIR));
writeState(moduleId, state); writeState(moduleId, state);
} }
private File ensureEmbeddedBundle(String moduleId) throws Exception { private File ensureEmbeddedBundle(String moduleId) throws Exception {
validateModuleId(moduleId); validateModuleId(moduleId);
File moduleDirectory = getModuleDir(moduleId); File active = new File(getModuleDir(moduleId), ACTIVE_FILE);
File active = new File(moduleDirectory, ACTIVE_FILE); if (active.exists()) return active;
JSONObject manifest = readEmbeddedManifest(); JSONObject manifest = readEmbeddedManifest();
JSONObject modules = manifest.optJSONObject("modules"); JSONObject modules = manifest.optJSONObject("modules");
JSONObject entry = modules == null ? null : modules.optJSONObject(moduleId); JSONObject entry = modules == null ? null : modules.optJSONObject(moduleId);
if (entry == null) return active; if (entry == null) return active;
String bundleFile = entry.optString("bundleFile", moduleId + ".android.bundle"); String bundleFile = entry.optString("bundleFile", moduleId + ".android.bundle");
String embeddedHash = entry.optString("sha256", "");
if (active.exists()) {
JSONObject state = readState(moduleId);
if (canLaunchInstalledBundle(moduleId, active, state, manifest, entry, embeddedHash)) {
return active;
}
}
// 只有首次安装、内嵌基线升级、完整性异常或本地插件不兼容时才读取 APK
// 中的大 Bundle。正常冷启动只解析一次小 manifest 和本地 state。
byte[] bytes = readAsset(EMBEDDED_DIR + "/" + bundleFile); byte[] bytes = readAsset(EMBEDDED_DIR + "/" + bundleFile);
if (embeddedHash.isEmpty()) embeddedHash = sha256(bytes);
else verifySha256(bytes, embeddedHash);
atomicWrite(active, bytes); atomicWrite(active, bytes);
File activeAssets = new File(moduleDirectory, ACTIVE_ASSETS_DIR);
deleteRecursively(activeAssets);
restoreEmbeddedAssets(activeAssets, entry.optJSONArray("assetFiles"));
writeEmbeddedState(moduleId, manifest, entry, embeddedHash, bytes.length);
return active;
}
/**
* 本地下载版本不低于 APK 内嵌版本且仍兼容当前原生基线时优先启动本地版本；
* 由 APK 自己安装的版本则用 manifest 摘要短路，允许开发期同版本新构建替换。
*/
private boolean canLaunchInstalledBundle(
String moduleId,
File active,
JSONObject state,
JSONObject manifest,
JSONObject entry,
String embeddedHash) throws Exception {
boolean pendingConfirmation = "pending_confirmation".equals(state.optString("status"));
String metadataPrefix = pendingConfirmation ? "pending" : "active";
long recordedLength = state.optLong(metadataPrefix + "ByteLength", -1L);
if (recordedLength >= 0L && active.length() != recordedLength) return false;
JSONArray assetFiles = state.optJSONArray(metadataPrefix + "AssetFiles");
if (!areAssetsPresent(new File(getModuleDir(moduleId), ACTIVE_ASSETS_DIR), assetFiles)) return false;
boolean ownsEmbeddedBundle = "embedded".equals(state.optString("status"));
if (ownsEmbeddedBundle) {
if (!areAssetsPresent(
new File(getModuleDir(moduleId), ACTIVE_ASSETS_DIR),
entry.optJSONArray("assetFiles"))) return false;
if (embeddedHash.isEmpty()
|| !embeddedHash.equalsIgnoreCase(state.optString("activeHash", ""))) {
return false;
}
long embeddedLength = entry.optLong("byteLength", -1L);
if (embeddedLength >= 0L && active.length() != embeddedLength) return false;
if (!isEmbeddedStateCurrent(state, manifest, entry, embeddedHash, active.length())) {
// 新版 state 字段或兼容元数据变化时只刷新小状态文件，不读取/复制 Bundle。
writeEmbeddedState(moduleId, manifest, entry, embeddedHash, active.length());
}
return true;
}
String installedVersion = state.optString(metadataPrefix + "Version", "");
String embeddedVersion = entry.optString("moduleVersion", "0.0.0");
final int versionComparison;
try {
versionComparison = XuqmSemanticVersion.compare(installedVersion, embeddedVersion);
} catch (IllegalArgumentException invalidVersion) {
return false;
}
if (versionComparison < 0) return false;
if (versionComparison == 0
&& !embeddedHash.equalsIgnoreCase(state.optString(metadataPrefix + "Hash", ""))) {
// 相同展示版本的新版 APK 以摘要识别真实构建，覆盖旧本地副本；
// 真正更高且兼容当前原生基线的远程插件仍保留。
return false;
}
String currentBaseline = manifest.optString("nativeBaselineId", "");
String installedBaseline = state.optString(metadataPrefix + "BuiltAgainstNativeBaselineId", "");
if (!currentBaseline.isEmpty() && !currentBaseline.equals(installedBaseline)) {
return false;
}
if (state.optInt(metadataPrefix + "MinNativeApiLevel", 1) > NATIVE_API_LEVEL) return false;
if (recordedLength < 0L) {
state.put(metadataPrefix + "ByteLength", active.length());
writeState(moduleId, state);
}
return true;
}
private boolean isEmbeddedStateCurrent(
JSONObject state,
JSONObject manifest,
JSONObject entry,
String embeddedHash,
long byteLength) {
return entry.optString("moduleVersion", "0.0.0").equals(state.optString("activeVersion", ""))
&& manifest.optString("buildId", "").equals(state.optString("activeBuildId", ""))
&& embeddedHash.equalsIgnoreCase(state.optString("activeHash", ""))
&& byteLength == state.optLong("activeByteLength", -1L)
&& entry.optString("type", "buz").equals(state.optString("activeType", ""))
&& entry.optString("appVersionRange", "").equals(state.optString("activeAppVersionRange", ""))
&& entry.optString("commonVersionRange", "").equals(state.optString("activeCommonVersionRange", ""))
&& manifest.optString("nativeBaselineId", "")
.equals(state.optString("activeBuiltAgainstNativeBaselineId", ""))
&& entry.optInt("minNativeApiLevel", 1) == state.optInt("activeMinNativeApiLevel", 1)
&& jsonArraysEqual(entry.optJSONArray("assetFiles"), state.optJSONArray("activeAssetFiles"));
}
private void writeEmbeddedState(
String moduleId,
JSONObject manifest,
JSONObject entry,
String embeddedHash,
long byteLength) throws Exception {
writeState(
moduleId,
createEmbeddedState(
moduleId,
manifest.optString("buildId", ""),
entry,
embeddedHash,
byteLength));
}
private JSONObject createEmbeddedState(
String moduleId,
String buildId,
JSONObject entry,
String embeddedHash,
long byteLength) throws Exception {
JSONObject state = new JSONObject(); JSONObject state = new JSONObject();
state.put("moduleId", moduleId); state.put("moduleId", moduleId);
state.put("status", "embedded"); state.put("status", "embedded");
state.put("activeVersion", entry.optString("moduleVersion", "0.0.0")); state.put("activeVersion", entry.optString("moduleVersion", "0.0.0"));
if (!buildId.isEmpty()) state.put("activeBuildId", buildId);
if (!embeddedHash.isEmpty()) {
state.put("activeHash", embeddedHash.toLowerCase(Locale.ROOT));
}
if (byteLength >= 0L) state.put("activeByteLength", byteLength);
state.put("activeType", entry.optString("type", "buz")); state.put("activeType", entry.optString("type", "buz"));
copyJsonValue(entry, "commonVersionRange", state, "activeCommonVersionRange"); copyJsonValue(entry, "commonVersionRange", state, "activeCommonVersionRange");
copyJsonValue(entry, "appVersionRange", state, "activeAppVersionRange"); copyJsonValue(entry, "appVersionRange", state, "activeAppVersionRange");
copyJsonValue(entry, "builtAgainstNativeBaselineId", state, "activeBuiltAgainstNativeBaselineId"); copyJsonValue(entry, "builtAgainstNativeBaselineId", state, "activeBuiltAgainstNativeBaselineId");
copyJsonValue(entry, "minNativeApiLevel", state, "activeMinNativeApiLevel"); copyJsonValue(entry, "minNativeApiLevel", state, "activeMinNativeApiLevel");
state.put("activeAssetFiles", entry.optJSONArray("assetFiles") == null writeState(moduleId, state);
? new JSONArray() return active;
: entry.optJSONArray("assetFiles"));
return state;
} }
/** private JSONObject readEmbeddedManifest() throws Exception {
* 动态 loadBundle(file) 后，React Native 会从该 Bundle 所在目录解析
* drawable-* 资源；因此恢复 Bundle 与恢复其资源必须属于同一个原生职责。
*/
private void restoreEmbeddedAssets(File assetDirectory, JSONArray assetFiles) throws Exception {
if (assetFiles == null) return;
for (int index = 0; index < assetFiles.length(); index += 1) {
String relativePath = assetFiles.getString(index);
validateAssetPath(relativePath);
atomicWrite(
new File(assetDirectory, relativePath),
readAsset(EMBEDDED_DIR + "/" + relativePath));
}
}
private boolean jsonArraysEqual(JSONArray left, JSONArray right) {
JSONArray normalizedLeft = left == null ? new JSONArray() : left;
JSONArray normalizedRight = right == null ? new JSONArray() : right;
return normalizedLeft.toString().equals(normalizedRight.toString());
}
private void collectAssetIndex(File directory, String prefix, JSONObject index) throws Exception {
File[] children = directory.listFiles();
if (children == null) return;
for (File child : children) {
String relative = prefix.isEmpty() ? child.getName() : prefix + "/" + child.getName();
if (child.isDirectory()) {
collectAssetIndex(child, relative, index);
} else {
validateAssetPath(relative);
if (index.has(relative)) throw new IOException("Duplicate active plugin asset: " + relative);
index.put(relative, child.toURI().toString());
}
}
}
private synchronized JSONObject readEmbeddedManifest() throws Exception {
if (embeddedManifestCache != null) return embeddedManifestCache;
try { try {
embeddedManifestCache = new JSONObject( return new JSONObject(new String(readAsset(EMBEDDED_DIR + "/manifest.json"), StandardCharsets.UTF_8));
new String(readAsset(EMBEDDED_DIR + "/manifest.json"), StandardCharsets.UTF_8));
} catch (IOException missing) { } catch (IOException missing) {
embeddedManifestCache = new JSONObject(); return new JSONObject();
} }
return embeddedManifestCache;
} }
private JSONObject requireRelease(String releaseId) throws Exception { private JSONObject requireRelease(String releaseId) throws Exception {
@ -710,24 +408,16 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
File directory = getModuleDir(moduleId); File directory = getModuleDir(moduleId);
File active = new File(directory, ACTIVE_FILE); File active = new File(directory, ACTIVE_FILE);
File rollback = new File(directory, ROLLBACK_FILE); File rollback = new File(directory, ROLLBACK_FILE);
File activeAssets = new File(directory, ACTIVE_ASSETS_DIR);
File rollbackAssets = new File(directory, ROLLBACK_ASSETS_DIR);
JSONObject state = readState(moduleId); JSONObject state = readState(moduleId);
if (rollback.exists()) { if (rollback.exists()) {
deleteIfExists(active); deleteIfExists(active);
if (!rollback.renameTo(active)) throw new IOException("Unable to restore " + moduleId); if (!rollback.renameTo(active)) throw new IOException("Unable to restore " + moduleId);
deleteRecursively(activeAssets);
if (rollbackAssets.exists() && !rollbackAssets.renameTo(activeAssets)) {
throw new IOException("Unable to restore assets for " + moduleId);
}
moveRollbackToActiveMetadata(state); moveRollbackToActiveMetadata(state);
} else if ("pending_confirmation".equals(state.optString("status"))) { } else if ("pending_confirmation".equals(state.optString("status"))) {
deleteIfExists(active); deleteIfExists(active);
deleteRecursively(activeAssets);
clearActiveMetadata(state); clearActiveMetadata(state);
} }
deleteIfExists(new File(directory, STAGED_FILE)); deleteIfExists(new File(directory, STAGED_FILE));
deleteRecursively(new File(directory, STAGED_ASSETS_DIR));
clearPendingMetadata(state); clearPendingMetadata(state);
clearRollbackMetadata(state); clearRollbackMetadata(state);
state.remove("releaseId"); state.remove("releaseId");
@ -739,8 +429,6 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
private void cleanupStaged(String moduleId) { private void cleanupStaged(String moduleId) {
try { try {
deleteIfExists(new File(getModuleDir(moduleId), STAGED_FILE)); deleteIfExists(new File(getModuleDir(moduleId), STAGED_FILE));
deleteRecursively(new File(getModuleDir(moduleId), STAGED_ASSETS_DIR));
deleteRecursively(new File(getModuleDir(moduleId), PACKAGE_TEMP_DIR));
JSONObject state = readState(moduleId); JSONObject state = readState(moduleId);
clearPendingMetadata(state); clearPendingMetadata(state);
state.remove("releaseId"); state.remove("releaseId");
@ -776,29 +464,6 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
: new JSONObject().put("moduleId", moduleId).put("status", "embedded"); : new JSONObject().put("moduleId", moduleId).put("status", "embedded");
} }
/** Reads installed state, or describes the APK baseline without creating a module directory. */
private JSONObject readBundleStateWithoutInstalling(String moduleId) throws Exception {
validateModuleId(moduleId);
File moduleDirectory = new File(new File(getReactApplicationContext().getFilesDir(), BUNDLE_DIR), moduleId);
File stateFile = new File(moduleDirectory, STATE_FILE);
if (stateFile.exists()) {
return new JSONObject(new String(readBytes(stateFile), StandardCharsets.UTF_8));
}
JSONObject manifest = readEmbeddedManifest();
JSONObject modules = manifest.optJSONObject("modules");
JSONObject entry = modules == null ? null : modules.optJSONObject(moduleId);
if (entry == null) {
return new JSONObject().put("moduleId", moduleId).put("status", "missing");
}
return createEmbeddedState(
moduleId,
manifest.optString("buildId", ""),
entry,
entry.optString("sha256", ""),
entry.optLong("byteLength", -1L));
}
private void writeState(String moduleId, JSONObject state) throws Exception { private void writeState(String moduleId, JSONObject state) throws Exception {
atomicWrite(new File(getModuleDir(moduleId), STATE_FILE), state.toString().getBytes(StandardCharsets.UTF_8)); atomicWrite(new File(getModuleDir(moduleId), STATE_FILE), state.toString().getBytes(StandardCharsets.UTF_8));
} }
@ -847,44 +512,32 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
private void copyActiveToRollbackMetadata(JSONObject state) throws Exception { private void copyActiveToRollbackMetadata(JSONObject state) throws Exception {
copyJsonValue(state, "activeVersion", state, "rollbackVersion"); copyJsonValue(state, "activeVersion", state, "rollbackVersion");
copyJsonValue(state, "activeBuildId", state, "rollbackBuildId");
copyJsonValue(state, "activeHash", state, "rollbackHash"); copyJsonValue(state, "activeHash", state, "rollbackHash");
copyJsonValue(state, "activeByteLength", state, "rollbackByteLength");
copyJsonValue(state, "activeType", state, "rollbackType"); copyJsonValue(state, "activeType", state, "rollbackType");
copyJsonValue(state, "activeAppVersionRange", state, "rollbackAppVersionRange"); copyJsonValue(state, "activeAppVersionRange", state, "rollbackAppVersionRange");
copyJsonValue(state, "activeBuiltAgainstNativeBaselineId", state, "rollbackBuiltAgainstNativeBaselineId"); copyJsonValue(state, "activeBuiltAgainstNativeBaselineId", state, "rollbackBuiltAgainstNativeBaselineId");
copyJsonValue(state, "activeCommonVersionRange", state, "rollbackCommonVersionRange"); copyJsonValue(state, "activeCommonVersionRange", state, "rollbackCommonVersionRange");
copyJsonValue(state, "activeMinNativeApiLevel", state, "rollbackMinNativeApiLevel"); copyJsonValue(state, "activeMinNativeApiLevel", state, "rollbackMinNativeApiLevel");
copyJsonValue(state, "activePackageHash", state, "rollbackPackageHash");
copyJsonValue(state, "activeAssetFiles", state, "rollbackAssetFiles");
} }
private void movePendingToActiveMetadata(JSONObject state) throws Exception { private void movePendingToActiveMetadata(JSONObject state) throws Exception {
moveJsonValue(state, "pendingVersion", "activeVersion"); moveJsonValue(state, "pendingVersion", "activeVersion");
moveJsonValue(state, "pendingBuildId", "activeBuildId");
moveJsonValue(state, "pendingHash", "activeHash"); moveJsonValue(state, "pendingHash", "activeHash");
moveJsonValue(state, "pendingByteLength", "activeByteLength");
moveJsonValue(state, "pendingType", "activeType"); moveJsonValue(state, "pendingType", "activeType");
moveJsonValue(state, "pendingAppVersionRange", "activeAppVersionRange"); moveJsonValue(state, "pendingAppVersionRange", "activeAppVersionRange");
moveJsonValue(state, "pendingBuiltAgainstNativeBaselineId", "activeBuiltAgainstNativeBaselineId"); moveJsonValue(state, "pendingBuiltAgainstNativeBaselineId", "activeBuiltAgainstNativeBaselineId");
moveJsonValue(state, "pendingCommonVersionRange", "activeCommonVersionRange"); moveJsonValue(state, "pendingCommonVersionRange", "activeCommonVersionRange");
moveJsonValue(state, "pendingMinNativeApiLevel", "activeMinNativeApiLevel"); moveJsonValue(state, "pendingMinNativeApiLevel", "activeMinNativeApiLevel");
moveJsonValue(state, "pendingPackageHash", "activePackageHash");
moveJsonValue(state, "pendingAssetFiles", "activeAssetFiles");
} }
private void moveRollbackToActiveMetadata(JSONObject state) throws Exception { private void moveRollbackToActiveMetadata(JSONObject state) throws Exception {
moveJsonValue(state, "rollbackVersion", "activeVersion"); moveJsonValue(state, "rollbackVersion", "activeVersion");
moveJsonValue(state, "rollbackBuildId", "activeBuildId");
moveJsonValue(state, "rollbackHash", "activeHash"); moveJsonValue(state, "rollbackHash", "activeHash");
moveJsonValue(state, "rollbackByteLength", "activeByteLength");
moveJsonValue(state, "rollbackType", "activeType"); moveJsonValue(state, "rollbackType", "activeType");
moveJsonValue(state, "rollbackAppVersionRange", "activeAppVersionRange"); moveJsonValue(state, "rollbackAppVersionRange", "activeAppVersionRange");
moveJsonValue(state, "rollbackBuiltAgainstNativeBaselineId", "activeBuiltAgainstNativeBaselineId"); moveJsonValue(state, "rollbackBuiltAgainstNativeBaselineId", "activeBuiltAgainstNativeBaselineId");
moveJsonValue(state, "rollbackCommonVersionRange", "activeCommonVersionRange"); moveJsonValue(state, "rollbackCommonVersionRange", "activeCommonVersionRange");
moveJsonValue(state, "rollbackMinNativeApiLevel", "activeMinNativeApiLevel"); moveJsonValue(state, "rollbackMinNativeApiLevel", "activeMinNativeApiLevel");
moveJsonValue(state, "rollbackPackageHash", "activePackageHash");
moveJsonValue(state, "rollbackAssetFiles", "activeAssetFiles");
} }
private void moveJsonValue(JSONObject state, String source, String target) throws Exception { private void moveJsonValue(JSONObject state, String source, String target) throws Exception {
@ -893,15 +546,15 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
} }
private void clearActiveMetadata(JSONObject state) { private void clearActiveMetadata(JSONObject state) {
for (String key : new String[]{"activeVersion", "activeBuildId", "activeHash", "activeByteLength", "activeType", "activeAppVersionRange", "activeBuiltAgainstNativeBaselineId", "activeCommonVersionRange", "activeMinNativeApiLevel", "activePackageHash", "activeAssetFiles"}) state.remove(key); for (String key : new String[]{"activeVersion", "activeHash", "activeType", "activeAppVersionRange", "activeBuiltAgainstNativeBaselineId", "activeCommonVersionRange", "activeMinNativeApiLevel"}) state.remove(key);
} }
private void clearPendingMetadata(JSONObject state) { private void clearPendingMetadata(JSONObject state) {
for (String key : new String[]{"pendingVersion", "pendingBuildId", "pendingHash", "pendingByteLength", "pendingType", "pendingAppVersionRange", "pendingBuiltAgainstNativeBaselineId", "pendingCommonVersionRange", "pendingMinNativeApiLevel", "pendingPackageHash", "pendingAssetFiles"}) state.remove(key); for (String key : new String[]{"pendingVersion", "pendingHash", "pendingType", "pendingAppVersionRange", "pendingBuiltAgainstNativeBaselineId", "pendingCommonVersionRange", "pendingMinNativeApiLevel"}) state.remove(key);
} }
private void clearRollbackMetadata(JSONObject state) { private void clearRollbackMetadata(JSONObject state) {
for (String key : new String[]{"rollbackVersion", "rollbackBuildId", "rollbackHash", "rollbackByteLength", "rollbackType", "rollbackAppVersionRange", "rollbackBuiltAgainstNativeBaselineId", "rollbackCommonVersionRange", "rollbackMinNativeApiLevel", "rollbackPackageHash", "rollbackAssetFiles"}) state.remove(key); for (String key : new String[]{"rollbackVersion", "rollbackHash", "rollbackType", "rollbackAppVersionRange", "rollbackBuiltAgainstNativeBaselineId", "rollbackCommonVersionRange", "rollbackMinNativeApiLevel"}) state.remove(key);
} }
private void validateModuleId(String moduleId) { private void validateModuleId(String moduleId) {
@ -916,6 +569,23 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
} }
} }
private void verifyHash(byte[] bytes, String expected) throws Exception {
if (expected == null || !expected.matches("(?i)^[a-f0-9]{64}$")) {
throw new IOException("A valid SHA-256 is required");
}
String actual = digest("SHA-256", bytes);
if (!actual.equalsIgnoreCase(expected)) {
throw new IOException("Bundle SHA-256 mismatch. Expected " + expected + " but got " + actual);
}
}
private String digest(String algorithm, byte[] bytes) throws Exception {
byte[] result = MessageDigest.getInstance(algorithm).digest(bytes);
StringBuilder output = new StringBuilder(result.length * 2);
for (byte value : result) output.append(String.format(Locale.ROOT, "%02x", value));
return output.toString();
}
private byte[] readAsset(String path) throws IOException { private byte[] readAsset(String path) throws IOException {
try (InputStream input = getReactApplicationContext().getAssets().open(path); try (InputStream input = getReactApplicationContext().getAssets().open(path);
ByteArrayOutputStream output = new ByteArrayOutputStream()) { ByteArrayOutputStream output = new ByteArrayOutputStream()) {
@ -926,4 +596,41 @@ public final class XuqmBundleModule extends ReactContextBaseJavaModule {
} }
} }
private byte[] readBytes(File file) throws IOException {
try (FileInputStream input = new FileInputStream(file);
ByteArrayOutputStream output = new ByteArrayOutputStream((int) file.length())) {
byte[] buffer = new byte[8192];
int count;
while ((count = input.read(buffer)) != -1) output.write(buffer, 0, count);
return output.toByteArray();
}
}
private void atomicWrite(File target, byte[] bytes) throws IOException {
File parent = target.getParentFile();
if (parent != null && !parent.exists() && !parent.mkdirs()) throw new IOException("Unable to create " + parent);
File temporary = new File(target.getAbsolutePath() + ".tmp");
try (FileOutputStream output = new FileOutputStream(temporary)) {
output.write(bytes);
output.flush();
output.getFD().sync();
}
try {
Os.rename(temporary.getAbsolutePath(), target.getAbsolutePath());
} catch (ErrnoException error) {
deleteIfExists(temporary);
throw new IOException("Unable to atomically replace " + target, error);
}
}
private void deleteIfExists(File file) throws IOException {
if (file.exists() && !file.delete()) throw new IOException("Unable to delete " + file);
}
private void deleteRecursively(File file) throws IOException {
if (!file.exists()) return;
File[] children = file.listFiles();
if (children != null) for (File child : children) deleteRecursively(child);
deleteIfExists(file);
}
} }

91
packages/update/android/src/main/java/com/xuqm/update/XuqmBundleStorage.java
查看文件

@ -1,91 +0,0 @@
package com.xuqm.update;
import android.system.ErrnoException;
import android.system.Os;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.security.MessageDigest;
import java.util.Locale;
/**
* Bundle 文件系统的唯一底层实现。
*
* <p>发布事务、内嵌恢复和插件包暂存必须共用这里的摘要、路径与原子写入语义，避免不同流程
* 各自维护一套看似相同但边界不同的文件操作。
*/
final class XuqmBundleStorage {
private XuqmBundleStorage() {}
static void verifySha256(byte[] bytes, String expected) throws Exception {
if (expected == null || !expected.matches("(?i)^[a-f0-9]{64}$")) {
throw new IOException("A valid SHA-256 is required");
}
String actual = sha256(bytes);
if (!actual.equalsIgnoreCase(expected)) {
throw new IOException("Bundle SHA-256 mismatch. Expected " + expected + " but got " + actual);
}
}
static String sha256(byte[] bytes) throws Exception {
byte[] result = MessageDigest.getInstance("SHA-256").digest(bytes);
StringBuilder output = new StringBuilder(result.length * 2);
for (byte value : result) output.append(String.format(Locale.ROOT, "%02x", value));
return output.toString();
}
static File safeFile(File root, String relativePath) throws IOException {
File file = new File(root, relativePath).getCanonicalFile();
File canonicalRoot = root.getCanonicalFile();
if (!file.getPath().startsWith(canonicalRoot.getPath() + File.separator)) {
throw new IOException("Plugin package path escapes staging directory: " + relativePath);
}
return file;
}
static byte[] readBytes(File file) throws IOException {
try (FileInputStream input = new FileInputStream(file);
ByteArrayOutputStream output = new ByteArrayOutputStream((int) file.length())) {
byte[] buffer = new byte[8192];
int count;
while ((count = input.read(buffer)) != -1) output.write(buffer, 0, count);
return output.toByteArray();
}
}
static void atomicWrite(File target, byte[] bytes) throws IOException {
File parent = target.getParentFile();
if (parent != null && !parent.exists() && !parent.mkdirs()) {
throw new IOException("Unable to create " + parent);
}
File temporary = new File(target.getAbsolutePath() + ".tmp");
try (FileOutputStream output = new FileOutputStream(temporary)) {
output.write(bytes);
output.flush();
output.getFD().sync();
}
try {
Os.rename(temporary.getAbsolutePath(), target.getAbsolutePath());
} catch (ErrnoException error) {
deleteIfExists(temporary);
throw new IOException("Unable to atomically replace " + target, error);
}
}
static void deleteIfExists(File file) throws IOException {
if (file.exists() && !file.delete()) throw new IOException("Unable to delete " + file);
}
static void deleteRecursively(File file) throws IOException {
if (!file.exists()) return;
File[] children = file.listFiles();
if (children != null) {
for (File child : children) deleteRecursively(child);
}
deleteIfExists(file);
}
}

267
packages/update/android/src/main/java/com/xuqm/update/XuqmPluginPackageStager.java
查看文件

@ -1,267 +0,0 @@
package com.xuqm.update;
import com.facebook.react.bridge.ReadableMap;
import org.json.JSONArray;
import org.json.JSONObject;
import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashSet;
import java.util.Set;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
/** 校验并暂存一个完整的 Android RN 插件包，不参与发布集的激活与回滚编排。 */
final class XuqmPluginPackageStager {
private static final int MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
private static final long MAX_ENTRY_UNCOMPRESSED_BYTES = 100L * 1024L * 1024L;
private static final long MAX_UNCOMPRESSED_BYTES = 100L * 1024L * 1024L;
private static final int MAX_ARCHIVE_ENTRIES = 4096;
private XuqmPluginPackageStager() {}
static JSONObject stage(
String moduleId,
byte[] archiveBytes,
String expectedPackageHash,
ReadableMap candidate,
File packageDirectory,
File stagedBundle,
File stagedAssets) throws Exception {
if (archiveBytes.length == 0 || archiveBytes.length > MAX_ARCHIVE_BYTES) {
throw new IOException("Invalid plugin package size for " + moduleId);
}
XuqmBundleStorage.verifySha256(archiveBytes, expectedPackageHash);
XuqmBundleStorage.deleteRecursively(packageDirectory);
XuqmBundleStorage.deleteRecursively(stagedAssets);
if (!packageDirectory.mkdirs() || !stagedAssets.mkdirs()) {
throw new IOException("Unable to create plugin staging directories for " + moduleId);
}
Set<String> archiveEntries = extractArchive(moduleId, archiveBytes, packageDirectory);
JSONObject manifest = readAndValidateManifest(moduleId, packageDirectory, candidate);
stageBundle(moduleId, packageDirectory, stagedBundle, manifest);
stageAssets(packageDirectory, stagedAssets, archiveEntries, manifest);
XuqmBundleStorage.deleteRecursively(packageDirectory);
return manifest;
}
static JSONArray assetPaths(JSONObject manifest) throws Exception {
JSONArray paths = new JSONArray();
JSONArray assets = manifest.optJSONArray("assets");
if (assets == null) return paths;
for (int index = 0; index < assets.length(); index += 1) {
paths.put(assets.getJSONObject(index).getString("path"));
}
return paths;
}
static boolean areAssetsPresent(File root, JSONArray files) {
if (files == null) return true;
try {
for (int index = 0; index < files.length(); index += 1) {
String relativePath = files.getString(index);
validateAssetPath(relativePath);
if (!XuqmBundleStorage.safeFile(root, relativePath).isFile()) return false;
}
return true;
} catch (Exception error) {
return false;
}
}
static void validateAssetPath(String relativePath) {
if (relativePath == null
|| !relativePath.matches("^(?:drawable-[a-z0-9-]+|raw)/[a-z0-9_]+\\.[a-z0-9]+$")) {
throw new IllegalArgumentException("Invalid embedded asset path: " + relativePath);
}
}
private static Set<String> extractArchive(
String moduleId,
byte[] archiveBytes,
File packageDirectory) throws Exception {
Set<String> archiveEntries = new LinkedHashSet<>();
long uncompressedBytes = 0L;
int entryCount = 0;
try (ZipInputStream input = new ZipInputStream(new ByteArrayInputStream(archiveBytes))) {
ZipEntry entry;
byte[] buffer = new byte[8192];
while ((entry = input.getNextEntry()) != null) {
entryCount += 1;
validateArchiveEntryCount(entryCount);
// CLI 的 zipSync 只生成文件 entry；显式目录 entry 不属于 v1 协议，
// 与服务端保持一致拒绝，避免目录绕过 entry 数量和路径检查。
if (entry.isDirectory()) {
throw new IOException("Plugin package directory entries are not allowed");
}
String name = entry.getName();
validateArchiveEntry(moduleId, name);
if (!archiveEntries.add(name)) {
throw new IOException("Duplicate plugin package entry: " + name);
}
File destination = XuqmBundleStorage.safeFile(packageDirectory, name);
File parent = destination.getParentFile();
if (parent != null && !parent.exists() && !parent.mkdirs()) {
throw new IOException("Unable to create package directory " + parent);
}
try (FileOutputStream output = new FileOutputStream(destination)) {
long entryUncompressedBytes = 0L;
int count;
while ((count = input.read(buffer)) != -1) {
entryUncompressedBytes += count;
validateEntryUncompressedSize(entryUncompressedBytes);
uncompressedBytes += count;
if (uncompressedBytes > MAX_UNCOMPRESSED_BYTES) {
throw new IOException("Plugin package exceeds the uncompressed size limit");
}
output.write(buffer, 0, count);
}
}
}
}
return archiveEntries;
}
static void validateArchiveEntryCount(int entryCount) throws IOException {
if (entryCount > MAX_ARCHIVE_ENTRIES) {
throw new IOException("Plugin package has too many entries");
}
}
static void validateEntryUncompressedSize(long entryBytes) throws IOException {
if (entryBytes > MAX_ENTRY_UNCOMPRESSED_BYTES) {
throw new IOException("Plugin package entry exceeds the uncompressed size limit");
}
}
private static JSONObject readAndValidateManifest(
String moduleId,
File packageDirectory,
ReadableMap candidate) throws Exception {
File manifestFile = new File(packageDirectory, "rn-manifest.json");
if (!manifestFile.isFile()) throw new IOException("Plugin package manifest is missing");
JSONObject manifest = new JSONObject(
new String(XuqmBundleStorage.readBytes(manifestFile), StandardCharsets.UTF_8));
if (manifest.optInt("schemaVersion", 0) != 1) {
throw new IOException("Unsupported plugin package schema");
}
if (!moduleId.equals(manifest.optString("moduleId"))
|| !"android".equals(manifest.optString("platform"))) {
throw new IOException("Plugin package identity does not match " + moduleId + "/android");
}
if (manifest.optString("buildId").trim().isEmpty()) {
throw new IOException("Plugin package buildId is missing");
}
validateCandidate(candidate, manifest);
return manifest;
}
private static void stageBundle(
String moduleId,
File packageDirectory,
File stagedBundle,
JSONObject manifest) throws Exception {
String bundleFile = manifest.getString("bundleFile");
if (!bundleFile.equals(moduleId + ".android.bundle")) {
throw new IOException("Unexpected bundle file in plugin package: " + bundleFile);
}
File packagedBundle = XuqmBundleStorage.safeFile(packageDirectory, bundleFile);
if (!packagedBundle.isFile()) throw new IOException("Plugin bundle is missing: " + bundleFile);
byte[] bundleBytes = XuqmBundleStorage.readBytes(packagedBundle);
if (bundleBytes.length != manifest.getLong("bundleByteLength")) {
throw new IOException("Plugin bundle length does not match its manifest");
}
XuqmBundleStorage.verifySha256(bundleBytes, manifest.getString("bundleSha256"));
XuqmBundleStorage.atomicWrite(stagedBundle, bundleBytes);
}
private static void stageAssets(
File packageDirectory,
File stagedAssets,
Set<String> archiveEntries,
JSONObject manifest) throws Exception {
JSONArray assets = manifest.optJSONArray("assets");
if (assets == null) assets = new JSONArray();
Set<String> declaredAssets = new LinkedHashSet<>();
for (int index = 0; index < assets.length(); index += 1) {
JSONObject asset = assets.getJSONObject(index);
String relativePath = asset.getString("path");
validateAssetPath(relativePath);
if (!declaredAssets.add(relativePath)) {
throw new IOException("Duplicate plugin asset: " + relativePath);
}
File packagedAsset = XuqmBundleStorage.safeFile(packageDirectory, "assets/" + relativePath);
if (!packagedAsset.isFile()) throw new IOException("Plugin asset is missing: " + relativePath);
byte[] bytes = XuqmBundleStorage.readBytes(packagedAsset);
if (bytes.length != asset.getLong("byteLength")) {
throw new IOException("Plugin asset length mismatch: " + relativePath);
}
XuqmBundleStorage.verifySha256(bytes, asset.getString("sha256"));
XuqmBundleStorage.atomicWrite(new File(stagedAssets, relativePath), bytes);
}
for (String archiveEntry : archiveEntries) {
if (archiveEntry.startsWith("assets/")
&& !declaredAssets.contains(archiveEntry.substring("assets/".length()))) {
throw new IOException("Plugin package contains an undeclared asset: " + archiveEntry);
}
}
}
private static void validateCandidate(ReadableMap candidate, JSONObject manifest) throws Exception {
requireEqual(candidate, manifest, "moduleId");
requireEqual(candidate, manifest, "type");
requireEqual(candidate, manifest, "version");
requireEqual(candidate, manifest, "buildId");
requireEqual(candidate, manifest, "bundleFormat");
requireEqual(candidate, manifest, "bundleSha256");
requireEqual(candidate, manifest, "appVersionRange");
requireOptionalEqual(candidate, manifest, "builtAgainstNativeBaselineId");
requireOptionalEqual(candidate, manifest, "commonVersionRange");
if (candidate.hasKey("minNativeApiLevel") && !candidate.isNull("minNativeApiLevel")
&& candidate.getInt("minNativeApiLevel") != manifest.optInt("minNativeApiLevel", 1)) {
throw new IOException("Plugin package minNativeApiLevel does not match the release candidate");
}
}
private static void requireEqual(ReadableMap candidate, JSONObject manifest, String key) throws Exception {
String expected = requiredString(candidate, key);
if (!expected.equals(manifest.optString(key))) {
throw new IOException("Plugin package " + key + " does not match the release candidate");
}
}
private static void requireOptionalEqual(ReadableMap candidate, JSONObject manifest, String key)
throws Exception {
String expected = candidate.hasKey(key) && !candidate.isNull(key) ? candidate.getString(key) : null;
String actual = manifest.has(key) && !manifest.isNull(key) ? manifest.getString(key) : null;
if (expected == null ? actual != null : !expected.equals(actual)) {
throw new IOException("Plugin package " + key + " does not match the release candidate");
}
}
private static String requiredString(ReadableMap map, String key) {
if (!map.hasKey(key) || map.isNull(key)) {
throw new IllegalArgumentException("Missing required field: " + key);
}
String value = map.getString(key);
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException("Invalid required field: " + key);
}
return value;
}
private static void validateArchiveEntry(String moduleId, String name) {
if ("rn-manifest.json".equals(name) || (moduleId + ".android.bundle").equals(name)) return;
if (name != null && name.startsWith("assets/")) {
validateAssetPath(name.substring("assets/".length()));
return;
}
throw new IllegalArgumentException("Invalid plugin package entry: " + name);
}
}

85
packages/update/android/src/main/java/com/xuqm/update/XuqmSemanticVersion.java
查看文件

@ -1,85 +0,0 @@
package com.xuqm.update;
import java.math.BigInteger;
/**
* Android 原生 Bundle 启动门禁使用的唯一 SemVer 2.0 优先级实现。
*
* <p>版本判断属于存储协议，不应散落在 React Native Bridge 的安装流程中。构建元数据不参与
* 优先级；非法版本由调用方按“不可信本地 Bundle”处理并恢复 APK 基线。
*/
final class XuqmSemanticVersion {
private XuqmSemanticVersion() {}
static boolean isAtLeast(String installed, String baseline) {
try {
return compare(installed, baseline) >= 0;
} catch (IllegalArgumentException invalidVersion) {
return false;
}
}
/** SemVer 2.0 precedence comparison; build metadata does not affect precedence. */
static int compare(String left, String right) {
String[] leftVersion = parts(left);
String[] rightVersion = parts(right);
String[] leftCore = leftVersion[0].split("\\.", -1);
String[] rightCore = rightVersion[0].split("\\.", -1);
if (leftCore.length != 3 || rightCore.length != 3) {
throw new IllegalArgumentException("Semantic version requires major.minor.patch");
}
for (int index = 0; index < 3; index += 1) {
int compared = numericIdentifier(leftCore[index]).compareTo(numericIdentifier(rightCore[index]));
if (compared != 0) return compared;
}
String leftPreRelease = leftVersion[1];
String rightPreRelease = rightVersion[1];
if (leftPreRelease.isEmpty() && rightPreRelease.isEmpty()) return 0;
if (leftPreRelease.isEmpty()) return 1;
if (rightPreRelease.isEmpty()) return -1;
String[] leftIdentifiers = leftPreRelease.split("\\.", -1);
String[] rightIdentifiers = rightPreRelease.split("\\.", -1);
int sharedLength = Math.min(leftIdentifiers.length, rightIdentifiers.length);
for (int index = 0; index < sharedLength; index += 1) {
String leftIdentifier = leftIdentifiers[index];
String rightIdentifier = rightIdentifiers[index];
if (!leftIdentifier.matches("[0-9A-Za-z-]+")
|| !rightIdentifier.matches("[0-9A-Za-z-]+")) {
throw new IllegalArgumentException("Invalid semantic version pre-release identifier");
}
boolean leftNumeric = leftIdentifier.matches("[0-9]+");
boolean rightNumeric = rightIdentifier.matches("[0-9]+");
int compared;
if (leftNumeric && rightNumeric) {
compared = numericIdentifier(leftIdentifier).compareTo(numericIdentifier(rightIdentifier));
} else if (leftNumeric) {
compared = -1;
} else if (rightNumeric) {
compared = 1;
} else {
compared = leftIdentifier.compareTo(rightIdentifier);
}
if (compared != 0) return compared;
}
return Integer.compare(leftIdentifiers.length, rightIdentifiers.length);
}
private static String[] parts(String version) {
if (version == null || version.trim().isEmpty()) {
throw new IllegalArgumentException("Semantic version is required");
}
String withoutBuild = version.trim().split("\\+", 2)[0];
String[] versionParts = withoutBuild.split("-", 2);
return new String[]{versionParts[0], versionParts.length == 2 ? versionParts[1] : ""};
}
private static BigInteger numericIdentifier(String value) {
if (value == null || !value.matches("0|[1-9][0-9]*")) {
throw new IllegalArgumentException("Invalid numeric semantic version identifier");
}
return new BigInteger(value);
}
}

49
packages/update/android/src/test/java/com/xuqm/update/XuqmBundleStorageTest.java
查看文件

@ -1,49 +0,0 @@
package com.xuqm.update;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertTrue;
import static org.junit.Assert.assertThrows;
import org.junit.Test;
import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
public final class XuqmBundleStorageTest {
@Test
public void sha256UsesTheCanonicalLowercaseEncoding() throws Exception {
assertEquals(
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad",
XuqmBundleStorage.sha256("abc".getBytes(StandardCharsets.UTF_8)));
}
@Test
public void safeFileRejectsTraversalOutsideTheStagingRoot() throws Exception {
File root = new File(System.getProperty("java.io.tmpdir"), "xuqm-storage-test");
assertThrows(IOException.class, () -> XuqmBundleStorage.safeFile(root, "../outside.bundle"));
}
@Test
public void recursiveDeleteRemovesOnlyTheSelectedSdkDirectory() throws Exception {
File root = new File(System.getProperty("java.io.tmpdir"), "xuqm-reset-test-" + System.nanoTime());
File updateDirectory = new File(root, "rn-bundles/common");
File hostDirectory = new File(root, "host-business");
assertTrue(updateDirectory.mkdirs());
assertTrue(hostDirectory.mkdirs());
XuqmBundleStorage.atomicWrite(
new File(updateDirectory, "active.bundle"),
"bundle".getBytes(StandardCharsets.UTF_8));
XuqmBundleStorage.atomicWrite(
new File(hostDirectory, "account.json"),
"account".getBytes(StandardCharsets.UTF_8));
XuqmBundleStorage.deleteRecursively(new File(root, "rn-bundles"));
assertFalse(new File(root, "rn-bundles").exists());
assertTrue(new File(hostDirectory, "account.json").exists());
XuqmBundleStorage.deleteRecursively(root);
}
}

35
packages/update/android/src/test/java/com/xuqm/update/XuqmPluginPackageStagerTest.java
查看文件

@ -1,35 +0,0 @@
package com.xuqm.update;
import static org.junit.Assert.assertThrows;
import org.junit.Test;
public final class XuqmPluginPackageStagerTest {
@Test
public void acceptsOnlyPackagedAndroidResourcePaths() {
XuqmPluginPackageStager.validateAssetPath("drawable-xhdpi/logo.png");
XuqmPluginPackageStager.validateAssetPath("raw/plugin_data.json");
assertThrows(
IllegalArgumentException.class,
() -> XuqmPluginPackageStager.validateAssetPath("../drawable-xhdpi/logo.png"));
assertThrows(
IllegalArgumentException.class,
() -> XuqmPluginPackageStager.validateAssetPath("assets/free-form-name.png"));
}
@Test
public void enforcesTheV1ArchiveEntryBoundaries() throws Exception {
XuqmPluginPackageStager.validateArchiveEntryCount(4096);
assertThrows(
java.io.IOException.class,
() -> XuqmPluginPackageStager.validateArchiveEntryCount(4097));
XuqmPluginPackageStager.validateEntryUncompressedSize(100L * 1024L * 1024L);
assertThrows(
java.io.IOException.class,
() -> XuqmPluginPackageStager.validateEntryUncompressedSize(
100L * 1024L * 1024L + 1L));
}
}

42
packages/update/android/src/test/java/com/xuqm/update/XuqmSemanticVersionTest.java
查看文件

@ -1,42 +0,0 @@
package com.xuqm.update;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertTrue;
import org.junit.Test;
public final class XuqmSemanticVersionTest {
@Test
public void followsSemVerPrereleasePrecedence() {
String[] ordered = {
"1.0.0-alpha",
"1.0.0-alpha.1",
"1.0.0-alpha.beta",
"1.0.0-beta",
"1.0.0-beta.2",
"1.0.0-beta.11",
"1.0.0-rc.1",
"1.0.0"
};
for (int index = 1; index < ordered.length; index += 1) {
assertTrue(XuqmSemanticVersion.compare(ordered[index], ordered[index - 1]) > 0);
}
}
@Test
public void ignoresBuildMetadataAndSupportsLargeIdentifiers() {
assertTrue(XuqmSemanticVersion.compare("1.2.3+app4", "1.2.3+sdk") == 0);
assertTrue(
XuqmSemanticVersion.compare(
"999999999999999999999.0.0", "999999999999999999998.999.999")
> 0);
}
@Test
public void invalidInstalledVersionNeverPassesTheNativeGate() {
assertFalse(XuqmSemanticVersion.isAtLeast("", "1.0.0"));
assertFalse(XuqmSemanticVersion.isAtLeast("01.0.0", "1.0.0"));
assertFalse(XuqmSemanticVersion.isAtLeast("1.0", "1.0.0"));
}
}

139
packages/update/android/xuqm-bundles.gradle
查看文件

@ -1,13 +1,10 @@
import javax.inject.Inject import javax.inject.Inject
import groovy.json.JsonSlurper
import org.gradle.api.DefaultTask import org.gradle.api.DefaultTask
import org.gradle.api.file.ConfigurableFileCollection
import org.gradle.api.file.DirectoryProperty import org.gradle.api.file.DirectoryProperty
import org.gradle.api.file.RegularFileProperty import org.gradle.api.file.RegularFileProperty
import org.gradle.api.provider.Property import org.gradle.api.provider.Property
import org.gradle.api.tasks.Input import org.gradle.api.tasks.Input
import org.gradle.api.tasks.InputFile import org.gradle.api.tasks.InputFile
import org.gradle.api.tasks.InputFiles
import org.gradle.api.tasks.Internal import org.gradle.api.tasks.Internal
import org.gradle.api.tasks.OutputDirectory import org.gradle.api.tasks.OutputDirectory
import org.gradle.api.tasks.PathSensitive import org.gradle.api.tasks.PathSensitive
@ -40,47 +37,23 @@ abstract class GenerateXuqmBundlesTask extends DefaultTask {
@PathSensitive(PathSensitivity.RELATIVE) @PathSensitive(PathSensitivity.RELATIVE)
abstract RegularFileProperty getPackageFile() abstract RegularFileProperty getPackageFile()
@InputFile
@PathSensitive(PathSensitivity.RELATIVE)
abstract RegularFileProperty getSignedConfigFile()
/**
* RN/原生源码与打包配置共同决定 bundle、资源和 native baseline。
* 显式建模后 Gradle 才能安全复用上次输出，禁止用永久 out-of-date 代替依赖声明。
*/
@InputFiles
@PathSensitive(PathSensitivity.RELATIVE)
abstract ConfigurableFileCollection getSourceFiles()
@Input @Input
abstract Property<String> getNodeExecutable() abstract Property<String> getNodeExecutable()
@Input @Input
abstract Property<String> getAppVersion() abstract Property<String> getAppVersion()
@Input
abstract Property<String> getBuildId()
@Input
abstract Property<String> getBugCollectMode()
@OutputDirectory @OutputDirectory
abstract DirectoryProperty getAssetsOutputDirectory() abstract DirectoryProperty getOutputDirectory()
@OutputDirectory
abstract DirectoryProperty getResourcesOutputDirectory()
@Inject @Inject
abstract ExecOperations getExecOperations() abstract ExecOperations getExecOperations()
@TaskAction @TaskAction
void generate() { void generate() {
def embeddedBundles = assetsOutputDirectory.get().dir("rn-bundles").asFile def embeddedBundles = outputDirectory.get().dir("rn-bundles").asFile
def resources = resourcesOutputDirectory.get().asFile
execOperations.exec { execOperations.exec {
workingDir(projectRootDirectory.get().asFile) workingDir(projectRootDirectory.get().asFile)
environment("XUQM_BUILD_ID", buildId.get())
environment("XUQM_BUGCOLLECT_MODE", bugCollectMode.get())
commandLine( commandLine(
nodeExecutable.get(), nodeExecutable.get(),
cliFile.get().asFile.absolutePath, cliFile.get().asFile.absolutePath,
@ -92,23 +65,6 @@ abstract class GenerateXuqmBundlesTask extends DefaultTask {
appVersion.get(), appVersion.get(),
) )
}.assertNormalExitValue() }.assertNormalExitValue()
project.copy {
from(signedConfigFile.get().asFile)
into(assetsOutputDirectory.get().dir("config"))
rename { "config.xuqmconfig" }
}
// Android 内嵌 Bundle 通过 AssetManager 读取，但 require() 图片必须同时进入
// aapt2 的 drawable 资源表。只把 drawable-* 放进 assets 会导致图片静默为空。
project.delete(resources)
embeddedBundles.listFiles()?.findAll {
it.isDirectory() && it.name.startsWith("drawable-")
}?.each { drawableDirectory ->
project.copy {
from(drawableDirectory)
into(new File(resources, drawableDirectory.name))
}
}
} }
} }
@ -117,43 +73,10 @@ if (!plugins.hasPlugin("com.android.application")) {
} }
def xuqmProjectRoot = rootProject.projectDir.parentFile def xuqmProjectRoot = rootProject.projectDir.parentFile
def xuqmHostPackage = new JsonSlurper().parse(new File(xuqmProjectRoot, "package.json"))
def xuqmLocalDependencyDirectories = (xuqmHostPackage.dependencies ?: [:])
.findAll { _, requested -> requested instanceof String && requested.startsWith("file:") }
.collect { _, requested -> new File(xuqmProjectRoot, requested.substring("file:".length())).canonicalFile }
def xuqmUseMetro = providers.gradleProperty("USE_METRO") def xuqmUseMetro = providers.gradleProperty("USE_METRO")
.orElse(providers.environmentVariable("USE_METRO")) .orElse(providers.environmentVariable("USE_METRO"))
.map { it.toBoolean() } .map { it.toBoolean() }
.orElse(false) .orElse(false)
def xuqmReleaseVersionCode = providers.gradleProperty("XUQM_VERSION_CODE")
.orElse(providers.environmentVariable("XUQM_VERSION_CODE"))
if (xuqmReleaseVersionCode.isPresent()) {
def parsedVersionCode = Integer.parseInt(xuqmReleaseVersionCode.get())
if (parsedVersionCode <= 0) {
throw new GradleException("XUQM_VERSION_CODE must be a positive integer")
}
android.defaultConfig.versionCode = parsedVersionCode
}
def xuqmBuildId = providers.gradleProperty("XUQM_BUILD_ID")
.orElse(providers.environmentVariable("XUQM_BUILD_ID"))
.orElse("development")
def xuqmBugCollectMode = providers.gradleProperty("XUQM_BUGCOLLECT_MODE")
.orElse(providers.environmentVariable("XUQM_BUGCOLLECT_MODE"))
.orElse("platform")
if (!["platform", "disabled"].contains(xuqmBugCollectMode.get())) {
throw new GradleException("XUQM_BUGCOLLECT_MODE must be platform or disabled")
}
def xuqmSignedConfigDirectory = new File(xuqmProjectRoot, "src/assets/config")
def xuqmSignedConfigCandidates = xuqmSignedConfigDirectory.isDirectory()
? (xuqmSignedConfigDirectory.listFiles()?.findAll {
it.isFile() && it.name.toLowerCase(Locale.ROOT).endsWith(".xuqmconfig")
} ?: []).sort { left, right -> left.name <=> right.name }
: []
if (xuqmSignedConfigCandidates.size() > 1) {
throw new GradleException(
"src/assets/config must contain exactly one .xuqmconfig file; found ${xuqmSignedConfigCandidates.size()}"
)
}
def prepareXuqmBundles = tasks.register( def prepareXuqmBundles = tasks.register(
"prepareXuqmEmbeddedBundles", "prepareXuqmEmbeddedBundles",
@ -163,52 +86,8 @@ def prepareXuqmBundles = tasks.register(
description = "Builds and embeds all configured Xuqm RN plugin bundles." description = "Builds and embeds all configured Xuqm RN plugin bundles."
projectRootDirectory.set(xuqmProjectRoot) projectRootDirectory.set(xuqmProjectRoot)
cliFile.set(new File(xuqmProjectRoot, "node_modules/@xuqm/rn-update/scripts/xuqm-rn.mjs")) cliFile.set(new File(xuqmProjectRoot, "node_modules/@xuqm/rn-update/scripts/xuqm-rn.mjs"))
configFile.set(new File(xuqmProjectRoot, "xuqm.modules.json")) configFile.set(new File(xuqmProjectRoot, "xuqm.config.json"))
packageFile.set(new File(xuqmProjectRoot, "package.json")) packageFile.set(new File(xuqmProjectRoot, "package.json"))
signedConfigFile.set(
xuqmSignedConfigCandidates
? xuqmSignedConfigCandidates.first()
: new File(xuqmSignedConfigDirectory, "config.xuqmconfig")
)
sourceFiles.from(project.fileTree(xuqmProjectRoot) {
include("src/**")
include("assets/**")
include("android/**")
include("index.*")
include("babel.config.*")
include("metro.config.*")
include("react-native.config.*")
include("tsconfig*.json")
include("pnpm-lock.yaml")
include("yarn.lock")
exclude("android/**/build/**")
exclude("android/**/.cxx/**")
exclude("android/**/.gradle/**")
exclude("android/app/src/**/generated/**")
})
sourceFiles.from(project.fileTree(new File(
xuqmProjectRoot,
"node_modules/@xuqm/rn-update/scripts",
)) {
include("*.mjs")
})
// registry 依赖由不可变版本号进入 baseline；file: 依赖在版本不变时也可能修改
// 源码，必须同时成为 Gradle 输入和 native baseline 内容。
// JS/TS 源码决定 bundle 内容，android/ios 决定 native baseline，缺一不可。
xuqmLocalDependencyDirectories.each { dependencyDirectory ->
sourceFiles.from(project.fileTree(dependencyDirectory) {
include("src/**")
include("metro/**")
include("android/**")
include("ios/**")
include("*.podspec")
include("package.json")
exclude("**/build/**")
exclude("**/.cxx/**")
exclude("**/.gradle/**")
exclude("**/generated/**")
})
}
nodeExecutable.set(System.getenv("NODE_BINARY") ?: "node") nodeExecutable.set(System.getenv("NODE_BINARY") ?: "node")
appVersion.set(providers.provider { appVersion.set(providers.provider {
def version = android.defaultConfig.versionName def version = android.defaultConfig.versionName
@ -217,21 +96,15 @@ def prepareXuqmBundles = tasks.register(
} }
version.toString() version.toString()
}) })
buildId.set(xuqmBuildId) outputDirectory.set(layout.buildDirectory.dir("generated/xuqm/assets"))
bugCollectMode.set(xuqmBugCollectMode) outputs.upToDateWhen { false }
assetsOutputDirectory.set(layout.buildDirectory.dir("generated/xuqm/assets"))
resourcesOutputDirectory.set(layout.buildDirectory.dir("generated/xuqm/res"))
} }
androidComponents.onVariants(androidComponents.selector().all()) { variant -> androidComponents.onVariants(androidComponents.selector().all()) { variant ->
if (variant.buildType == "release" || !xuqmUseMetro.get()) { if (variant.buildType == "release" || !xuqmUseMetro.get()) {
variant.sources.assets?.addGeneratedSourceDirectory( variant.sources.assets?.addGeneratedSourceDirectory(
prepareXuqmBundles, prepareXuqmBundles,
{ task -> task.assetsOutputDirectory }, { task -> task.outputDirectory },
)
variant.sources.res?.addGeneratedSourceDirectory(
prepareXuqmBundles,
{ task -> task.resourcesOutputDirectory },
) )
} }
} }

103
packages/update/metro/index.js
查看文件

@ -1,103 +0,0 @@
const fs = require('node:fs')
const path = require('node:path')
const { withXuqmConfig } = require('@xuqm/rn-common/metro')
const MODULE_RANGE_SIZE = 10_000_000
function readCache(file) {
if (!fs.existsSync(file)) return {}
try {
return JSON.parse(fs.readFileSync(file, 'utf8'))
} catch {
return {}
}
}
function writeCache(file, value) {
fs.mkdirSync(path.dirname(file), { recursive: true })
fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`)
}
function hasModule(cache, modulePath) {
return Object.prototype.hasOwnProperty.call(cache, modulePath)
}
function isRuntimePrelude(modulePath) {
return modulePath.includes('__prelude__') || modulePath.includes('polyfills')
}
function createModuleSerializer(environment = process.env) {
const moduleId = environment.XUQM_MODULE_ID
const moduleType = environment.XUQM_MODULE_TYPE
if (!moduleId || !moduleType) return null
const cacheFile = path.resolve(
environment.XUQM_MODULE_CACHE_FILE ?? '.xuqm-cache/common-module-ids.json',
)
if (environment.XUQM_RESET_MODULE_CACHE === 'true') writeCache(cacheFile, {})
const sharedCache = readCache(cacheFile)
// processModuleFilter 会在 createModuleIdFactory 分配编号之后执行。必须冻结进入
// 当前 bundle 之前已经存在的共享模块；否则 common 新分配的模块刚写入缓存，随即
// 又会被当作 startup 已提供模块过滤，生成只含 require(entryId) 的无效空包。
const inheritedSharedModules = new Set(Object.keys(sharedCache))
const writesSharedCache = moduleType === 'startup' || moduleType === 'common'
const moduleIndex = Number.parseInt(environment.XUQM_MODULE_INDEX ?? '0', 10)
let nextId = writesSharedCache
? Object.values(sharedCache).reduce((maximum, value) => Math.max(maximum, Number(value)), -1) +
1
: (Number.isFinite(moduleIndex) && moduleIndex >= 0 ? moduleIndex + 1 : 1) * MODULE_RANGE_SIZE
const localIds = new Map()
return {
createModuleIdFactory() {
return modulePath => {
if (hasModule(sharedCache, modulePath)) return sharedCache[modulePath]
const existing = localIds.get(modulePath)
if (existing !== undefined) return existing
const id = nextId++
localIds.set(modulePath, id)
if (writesSharedCache) {
sharedCache[modulePath] = id
writeCache(cacheFile, sharedCache)
}
return id
}
},
processModuleFilter(module) {
if (moduleType === 'startup') return true
if (isRuntimePrelude(module.path)) return false
return !inheritedSharedModules.has(module.path)
},
}
}
/**
* 同一份 Metro 配置同时服务日常开发和插件构建。CLI 构建插件时注入模块上下文；
* 普通 `pnpm android/start` 没有这些变量，因此保持标准 React Native 行为。
*/
function withXuqmModuleConfig(metroConfig) {
const configured = withXuqmConfig(metroConfig)
const moduleSerializer = createModuleSerializer()
if (!moduleSerializer) return configured
const configuredFilter = configured.serializer?.processModuleFilter
return {
...configured,
serializer: {
...configured.serializer,
...moduleSerializer,
processModuleFilter(module) {
return (
(configuredFilter ? configuredFilter(module) : true) &&
moduleSerializer.processModuleFilter(module)
)
},
},
}
}
module.exports = {
createModuleSerializer,
withXuqmModuleConfig,
}

14
packages/update/package.json
查看文件

@ -6,18 +6,9 @@
"main": "src/index.ts", "main": "src/index.ts",
"react-native": "src/index.ts", "react-native": "src/index.ts",
"types": "src/index.ts", "types": "src/index.ts",
"exports": {
".": "./src/index.ts",
"./native-bundle": "./src/NativeBundle.ts",
"./plugin-assets": "./src/PluginAssets.ts",
"./plugin-registry": "./src/PluginRegistry.ts",
"./metro": "./metro/index.js",
"./package.json": "./package.json"
},
"files": [ "files": [
"src", "src",
"android", "android",
"metro",
"scripts", "scripts",
"templates", "templates",
"react-native.config.js", "react-native.config.js",
@ -36,13 +27,12 @@
"pack:check": "node scripts/verify-package.mjs" "pack:check": "node scripts/verify-package.mjs"
}, },
"dependencies": { "dependencies": {
"fflate": "0.8.3",
"semver": "7.8.5" "semver": "7.8.5"
}, },
"peerDependencies": { "peerDependencies": {
"react-native": ">=0.76.0",
"@react-native-async-storage/async-storage": ">=1.21.0", "@react-native-async-storage/async-storage": ">=1.21.0",
"@xuqm/rn-common": "workspace:>=0.6.0-alpha.4", "@xuqm/rn-common": "workspace:>=0.6.0-alpha.4"
"react-native": ">=0.76.0"
}, },
"devDependencies": { "devDependencies": {
"@types/semver": "7.7.1", "@types/semver": "7.7.1",

38
packages/update/scripts/artifact-upload.mjs
查看文件

@ -1,38 +0,0 @@
export const BUGCOLLECT_ARTIFACT_UPLOAD_PATH = '/bugcollect/v1/artifacts/upload'
/** Source Map 与插件发布使用同一流水线 Bearer，不允许匿名上传构建制品。 */
export function createArtifactUploadRequest(apiToken, form) {
if (typeof apiToken !== 'string' || apiToken.trim() === '') {
throw new Error('artifact upload requires an API token')
}
return {
method: 'POST',
headers: { Authorization: `Bearer ${apiToken}` },
body: form,
}
}
/** RN Source Map 与 Android R8 Mapping 共用 artifacts 入口，但类型和身份字段明确分离。 */
export function createRnSourceMapForm({
appKey,
platform,
appVersion,
buildId,
moduleId,
moduleVersion,
bundleHash,
fileBytes,
fileName,
}) {
const form = new FormData()
form.append('artifactType', 'RN_SOURCEMAP')
form.append('appKey', appKey)
form.append('platform', platform)
form.append('appVersion', appVersion)
form.append('buildId', buildId)
form.append('moduleId', moduleId)
form.append('moduleVersion', moduleVersion)
form.append('bundleHash', bundleHash)
form.append('file', new Blob([fileBytes]), fileName)
return form
}

45
packages/update/scripts/artifact-upload.test.mjs
查看文件

@ -1,45 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import {
BUGCOLLECT_ARTIFACT_UPLOAD_PATH,
createArtifactUploadRequest,
createRnSourceMapForm,
} from './artifact-upload.mjs'
test('RN Source Map uses the frozen artifact upload contract', () => {
const form = createRnSourceMapForm({
appKey: 'app',
platform: 'android',
appVersion: '8.0.0',
buildId: 'build-1',
moduleId: 'orders',
moduleVersion: '1.0.2',
bundleHash: 'a'.repeat(64),
fileBytes: new Uint8Array([1, 2, 3]),
fileName: 'orders.android.map',
})
assert.equal(BUGCOLLECT_ARTIFACT_UPLOAD_PATH, '/bugcollect/v1/artifacts/upload')
assert.deepEqual(
Object.fromEntries(
[...form.entries()]
.filter(([, value]) => typeof value === 'string')
.map(([key, value]) => [key, value]),
),
{
artifactType: 'RN_SOURCEMAP',
appKey: 'app',
platform: 'android',
appVersion: '8.0.0',
buildId: 'build-1',
moduleId: 'orders',
moduleVersion: '1.0.2',
bundleHash: 'a'.repeat(64),
},
)
assert.equal(form.get('file') instanceof Blob, true)
const request = createArtifactUploadRequest('release-token', form)
assert.deepEqual(request.headers, { Authorization: 'Bearer release-token' })
assert.equal(request.body, form)
assert.throws(() => createArtifactUploadRequest('', form), /requires an API token/)
})

48
packages/update/scripts/metro.test.mjs
查看文件

@ -1,48 +0,0 @@
import assert from 'node:assert/strict'
import { mkdtempSync, rmSync } from 'node:fs'
import { createRequire } from 'node:module'
import { tmpdir } from 'node:os'
import path from 'node:path'
import test from 'node:test'
const require = createRequire(import.meta.url)
const { createModuleSerializer } = require('../metro')
function context(cacheFile, moduleId, moduleType, moduleIndex, reset = false) {
return {
XUQM_MODULE_CACHE_FILE: cacheFile,
XUQM_MODULE_ID: moduleId,
XUQM_MODULE_INDEX: String(moduleIndex),
XUQM_MODULE_TYPE: moduleType,
XUQM_RESET_MODULE_CACHE: reset ? 'true' : 'false',
}
}
test('Metro module ranges share startup/common and isolate every app or buz', () => {
const directory = mkdtempSync(path.join(tmpdir(), 'xuqm-metro-'))
const cacheFile = path.join(directory, 'ids.json')
try {
const startup = createModuleSerializer(context(cacheFile, 'startup', 'startup', 0, true))
const startupFactory = startup.createModuleIdFactory()
assert.equal(startupFactory('/runtime/prelude.js'), 0)
const common = createModuleSerializer(context(cacheFile, 'common', 'common', 1))
assert.equal(common.processModuleFilter({ path: '/runtime/prelude.js' }), false)
const commonFactory = common.createModuleIdFactory()
assert.equal(commonFactory('/runtime/prelude.js'), 0)
assert.equal(commonFactory('/shared/common.ts'), 1)
assert.equal(
common.processModuleFilter({ path: '/shared/common.ts' }),
true,
'common 本轮新分配的模块必须保留在当前 bundle 中',
)
const app = createModuleSerializer(context(cacheFile, 'app', 'app', 2))
const buz = createModuleSerializer(context(cacheFile, 'buz-a', 'buz', 3))
assert.equal(app.processModuleFilter({ path: '/shared/common.ts' }), false)
assert.equal(app.createModuleIdFactory()('/app/entry.ts'), 30_000_000)
assert.equal(buz.createModuleIdFactory()('/buz/entry.ts'), 40_000_000)
} finally {
rmSync(directory, { force: true, recursive: true })
}
})

27
packages/update/scripts/native-baseline.mjs
查看文件

@ -83,30 +83,6 @@ function runtimeDependencyVersions(root, hostPackage) {
return runtime return runtime
} }
/**
* 开发期 file: 依赖不会因为源码变化自动提升 package version，因此必须把它们的
* 原生源码纳入完整包基线；正式 registry 依赖仍由不可变版本号标识。
*/
function localDependencyNativeFiles(root, hostPackage, platform) {
const dependencies = hostPackage.dependencies ?? {}
const files = []
for (const [name, requested] of Object.entries(dependencies).sort(([left], [right]) =>
left.localeCompare(right),
)) {
if (typeof requested !== 'string' || !requested.startsWith('file:')) continue
const dependencyRoot = path.resolve(root, requested.slice('file:'.length))
for (const file of walkFiles(
path.join(dependencyRoot, platform),
dependencyRoot,
new Set([...NATIVE_EXTENSIONS, ...PACKAGED_ASSET_EXTENSIONS]),
new Set(platform === 'android' ? ['gradlew'] : ['Podfile']),
)) {
files.push({ ...file, relative: `local-dependency/${name}/${file.relative}` })
}
}
return files
}
/** Deterministic identity of code and dependencies that can only change through a full APK. */ /** Deterministic identity of code and dependencies that can only change through a full APK. */
export function computeNativeBaseline(root = process.cwd(), platform = 'android') { export function computeNativeBaseline(root = process.cwd(), platform = 'android') {
if (platform !== 'android' && platform !== 'ios') { if (platform !== 'android' && platform !== 'ios') {
@ -128,8 +104,7 @@ export function computeNativeBaseline(root = process.cwd(), platform = 'android'
const sourceAssets = [path.join(root, 'src'), path.join(root, 'assets')].flatMap(directory => const sourceAssets = [path.join(root, 'src'), path.join(root, 'assets')].flatMap(directory =>
walkFiles(directory, root, PACKAGED_ASSET_EXTENSIONS), walkFiles(directory, root, PACKAGED_ASSET_EXTENSIONS),
) )
const localDependencyFiles = localDependencyNativeFiles(root, hostPackage, platform) for (const file of [...nativeFiles, ...sourceAssets].sort((a, b) =>
for (const file of [...nativeFiles, ...sourceAssets, ...localDependencyFiles].sort((a, b) =>
a.relative.localeCompare(b.relative), a.relative.localeCompare(b.relative),
)) { )) {
hash.update(`file\0${file.relative}\0`) hash.update(`file\0${file.relative}\0`)

22
packages/update/scripts/native-baseline.test.mjs
查看文件

@ -72,25 +72,3 @@ test('native baselines are platform-specific', () => {
rmSync(root, { recursive: true, force: true }) rmSync(root, { recursive: true, force: true })
} }
}) })
test('native source from a local file dependency changes the full-app baseline', () => {
const root = fixture()
try {
const dependencyRoot = path.join(root, 'local-update-sdk')
const nativeFile = path.join(dependencyRoot, 'android', 'src', 'main', 'java', 'Bridge.java')
mkdirSync(path.dirname(nativeFile), { recursive: true })
writeFileSync(nativeFile, 'final class Bridge {}')
writeFileSync(
path.join(root, 'package.json'),
JSON.stringify({
dependencies: { 'runtime-library': '^1.0.0', '@xuqm/local': 'file:./local-update-sdk' },
}),
)
const initial = computeNativeBaseline(root, 'android')
writeFileSync(nativeFile, 'final class Bridge { int apiLevel = 2; }')
assert.notEqual(computeNativeBaseline(root, 'android'), initial)
} finally {
rmSync(root, { recursive: true, force: true })
}
})

48
packages/update/scripts/package-options.mjs
查看文件

@ -1,48 +0,0 @@
const BUGCOLLECT_MODES = new Set(['platform', 'disabled'])
/**
* Release 打包参数的唯一解析入口。CLI 同时接收标准的 `--bugcollect=disabled`
* 和命令行工具常见的空格写法，但后续流程只消费归一化结果。
*/
export function parsePackageOptions(optionArgs) {
const remaining = [...optionArgs]
const apkIndex = remaining.indexOf('--apk')
const apk = apkIndex >= 0
if (apk) remaining.splice(apkIndex, 1)
const parsedBugCollect = parseBugCollectOption(remaining)
if (parsedBugCollect.remaining.length) {
throw new Error(`unknown option(s): ${parsedBugCollect.remaining.join(' ')}`)
}
return { apk, bugCollectMode: parsedBugCollect.bugCollectMode }
}
export function parseBugCollectOption(optionArgs, defaultMode = 'platform') {
const remaining = [...optionArgs]
const equalsOptions = remaining.filter(option => option.startsWith('--bugcollect='))
const spaceIndexes = remaining
.map((option, index) => (option === '--bugcollect' ? index : -1))
.filter(index => index >= 0)
if (equalsOptions.length + spaceIndexes.length > 1) {
throw new Error('--bugcollect must be specified only once')
}
let bugCollectMode = defaultMode
if (equalsOptions.length === 1) {
const index = remaining.indexOf(equalsOptions[0])
bugCollectMode = equalsOptions[0].slice('--bugcollect='.length)
remaining.splice(index, 1)
} else if (spaceIndexes.length === 1) {
const index = spaceIndexes[0]
if (remaining[index + 1] === undefined) {
throw new Error('--bugcollect requires a value')
}
bugCollectMode = remaining[index + 1]
remaining.splice(index, 2)
}
if (!BUGCOLLECT_MODES.has(bugCollectMode)) {
throw new Error('--bugcollect must be platform or disabled')
}
return { bugCollectMode, remaining }
}

40
packages/update/scripts/package-options.test.mjs
查看文件

@ -1,40 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { parseBugCollectOption, parsePackageOptions } from './package-options.mjs'
test('package options normalize equals and space bugcollect syntax', () => {
assert.deepEqual(parsePackageOptions(['--bugcollect=disabled']), {
apk: false,
bugCollectMode: 'disabled',
})
assert.deepEqual(parsePackageOptions(['--apk', '--bugcollect', 'disabled']), {
apk: true,
bugCollectMode: 'disabled',
})
assert.deepEqual(parsePackageOptions([]), {
apk: false,
bugCollectMode: 'platform',
})
})
test('publish and package share one BugCollect option parser', () => {
assert.deepEqual(parseBugCollectOption(['--module', 'app', '--bugcollect=disabled']), {
bugCollectMode: 'disabled',
remaining: ['--module', 'app'],
})
assert.deepEqual(parseBugCollectOption(['--note', 'release'], 'disabled'), {
bugCollectMode: 'disabled',
remaining: ['--note', 'release'],
})
})
test('package options reject duplicate, missing and invalid values', () => {
assert.throws(
() => parsePackageOptions(['--bugcollect=disabled', '--bugcollect', 'platform']),
/only once/,
)
assert.throws(() => parsePackageOptions(['--bugcollect']), /requires a value/)
assert.throws(() => parsePackageOptions(['--bugcollect=unknown']), /platform or disabled/)
assert.throws(() => parsePackageOptions(['--unknown']), /unknown option/)
})

39
packages/update/scripts/release-config.mjs
查看文件

@ -1,39 +0,0 @@
import { readFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import path from 'node:path'
/**
* 整包与插件发布共用的配置验证门禁。只阻断新产物；已安装 App 不在线查询吊销状态。
*/
export async function validateReleaseConfig({ projectRoot, packageName }) {
const hostRequire = createRequire(path.join(projectRoot, 'package.json'))
const commonMetro = hostRequire('@xuqm/rn-common/metro')
const configFile = commonMetro.findConfigFile(projectRoot)
if (!configFile) {
throw new Error('exactly one .xuqmconfig file is required in src/assets/config for Release')
}
const content = readFileSync(configFile, 'utf8').trim()
const resolved = commonMetro.decryptConfigAtBuildTime(content)
if (typeof packageName !== 'string' || packageName.trim() === '') {
throw new Error('A package identity is required for Release validation')
}
const response = await fetch(
`${String(resolved.serverUrl).replace(/\/$/, '')}/api/sdk/build/config/validate`,
{
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ content, packageName }),
},
)
if (!response.ok) {
throw new Error(`Release config validation service failed: HTTP ${response.status}`)
}
const payload = await response.json()
const result = payload.data ?? payload
if (result.valid !== true) {
throw new Error(
`Release config rejected (${result.errorCode ?? 'CONFIG_INVALID'}): ${result.message ?? 'unknown error'}`,
)
}
}

66
packages/update/scripts/release-identity.mjs
查看文件

@ -1,66 +0,0 @@
import { createHash } from 'node:crypto'
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import path from 'node:path'
const MAX_ANDROID_VERSION_CODE = 2_100_000_000
function readPreviousVersionCode(cacheFile) {
try {
return Number(JSON.parse(readFileSync(cacheFile, 'utf8')).versionCode) || 0
} catch {
return 0
}
}
/**
* 为同一 versionName 的连续测试包生成可安装的新构建身份。
*
* 本地缓存只负责同一工作区内的单调递增；CI 若需要跨工作区全局唯一，必须通过
* XUQM_VERSION_CODE 注入流水线唯一编号。
*/
export function createAndroidReleaseIdentity({
projectRoot,
environment = process.env,
now = Date.now(),
entropy = `${process.pid}:${Math.random()}`,
}) {
const cacheFile = path.join(projectRoot, '.xuqm-cache', 'release-build.json')
const previousVersionCode = readPreviousVersionCode(cacheFile)
const requestedText = environment.XUQM_VERSION_CODE
const requested = requestedText === undefined ? undefined : Number(requestedText)
if (
requestedText !== undefined &&
(!Number.isInteger(requested) || requested <= 0 || requested > MAX_ANDROID_VERSION_CODE)
) {
throw new Error(
`XUQM_VERSION_CODE must be an integer between 1 and ${MAX_ANDROID_VERSION_CODE}`,
)
}
const epochSeconds = Math.floor(now / 1_000)
const versionCode = requested ?? Math.max(epochSeconds, previousVersionCode + 1)
if (versionCode > MAX_ANDROID_VERSION_CODE) {
throw new Error('Generated Android versionCode exceeds limit')
}
const buildId =
environment.XUQM_BUILD_ID ??
createHash('sha256').update(`${versionCode}:${now}:${entropy}`).digest('hex').slice(0, 32)
if (!/^[A-Za-z0-9._-]{1,128}$/.test(buildId)) {
throw new Error('XUQM_BUILD_ID must contain only letters, numbers, dot, underscore or hyphen')
}
mkdirSync(path.dirname(cacheFile), { recursive: true })
writeFileSync(
cacheFile,
`${JSON.stringify(
{
versionCode,
buildId,
generatedAt: new Date(now).toISOString(),
},
null,
2,
)}\n`,
)
return { versionCode, buildId }
}

68
packages/update/scripts/release-identity.test.mjs
查看文件

@ -1,68 +0,0 @@
import assert from 'node:assert/strict'
import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import path from 'node:path'
import test from 'node:test'
import { createAndroidReleaseIdentity } from './release-identity.mjs'
test('release identity increases for repeated builds with the same app version', () => {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-release-identity-'))
try {
const first = createAndroidReleaseIdentity({
projectRoot: root,
environment: {},
now: 1_800_000_000_000,
entropy: 'first',
})
const second = createAndroidReleaseIdentity({
projectRoot: root,
environment: {},
now: 1_800_000_000_000,
entropy: 'second',
})
assert.equal(second.versionCode, first.versionCode + 1)
assert.notEqual(second.buildId, first.buildId)
const cached = JSON.parse(
readFileSync(path.join(root, '.xuqm-cache', 'release-build.json'), 'utf8'),
)
assert.deepEqual({ versionCode: cached.versionCode, buildId: cached.buildId }, second)
} finally {
rmSync(root, { recursive: true, force: true })
}
})
test('release identity accepts explicit CI identity and validates its contract', () => {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-release-identity-ci-'))
try {
assert.deepEqual(
createAndroidReleaseIdentity({
projectRoot: root,
environment: {
XUQM_VERSION_CODE: '123456',
XUQM_BUILD_ID: 'jenkins-123456',
},
now: 1_800_000_000_000,
}),
{ versionCode: 123456, buildId: 'jenkins-123456' },
)
assert.throws(
() =>
createAndroidReleaseIdentity({
projectRoot: root,
environment: { XUQM_VERSION_CODE: 'invalid' },
}),
/XUQM_VERSION_CODE/,
)
assert.throws(
() =>
createAndroidReleaseIdentity({
projectRoot: root,
environment: { XUQM_BUILD_ID: 'contains whitespace' },
}),
/XUQM_BUILD_ID/,
)
} finally {
rmSync(root, { recursive: true, force: true })
}
})

105
packages/update/scripts/release-package.mjs
查看文件

@ -1,105 +0,0 @@
import { createHash } from 'node:crypto'
import { readFileSync } from 'node:fs'
import { strFromU8, unzipSync } from 'fflate'
function requiredString(manifest, key) {
const value = manifest?.[key]
if (typeof value !== 'string' || value.trim() === '') {
throw new Error(`plugin package manifest ${key} is missing`)
}
return value
}
/**
* 发布身份只能来自即将上传的 ZIP，不能根据环境变量或缓存再次推导。这样 Bundle、
* Source Map 和服务端登记始终使用同一个构建产生的精确身份。
*/
export function readReleasePackageIdentity(packageFile, expected) {
const archive = unzipSync(new Uint8Array(readFileSync(packageFile)))
const manifestBytes = archive['rn-manifest.json']
if (!manifestBytes) throw new Error('plugin package manifest is missing')
let manifest
try {
manifest = JSON.parse(strFromU8(manifestBytes))
} catch {
throw new Error('plugin package manifest is invalid JSON')
}
const packageName = requiredString(manifest, 'packageName')
const moduleId = requiredString(manifest, 'moduleId')
const platform = requiredString(manifest, 'platform')
const moduleVersion = requiredString(manifest, 'version')
const appVersion = requiredString(manifest, 'appVersion')
const buildId = requiredString(manifest, 'buildId')
const bundleFile = requiredString(manifest, 'bundleFile')
const bundleHash = requiredString(manifest, 'bundleSha256')
const bundleFormat = requiredString(manifest, 'bundleFormat')
const nativeBaselineId = requiredString(manifest, 'builtAgainstNativeBaselineId')
const appVersionRange = requiredString(manifest, 'appVersionRange')
const minNativeApiLevel = manifest.minNativeApiLevel
if (buildId === 'development') {
throw new Error('plugin package was built without a release buildId; rebuild before publishing')
}
if (expected.packageName !== packageName) {
throw new Error(
`plugin package packageName mismatch: expected ${expected.packageName}, got ${packageName}`,
)
}
if (expected.moduleId !== moduleId) {
throw new Error(
`plugin package moduleId mismatch: expected ${expected.moduleId}, got ${moduleId}`,
)
}
if (expected.platform !== platform) {
throw new Error(
`plugin package platform mismatch: expected ${expected.platform}, got ${platform}`,
)
}
if (expected.moduleVersion !== moduleVersion) {
throw new Error(
`plugin package version mismatch: expected ${expected.moduleVersion}, got ${moduleVersion}`,
)
}
if (expected.appVersion !== appVersion) {
throw new Error(
`plugin package appVersion mismatch: expected ${expected.appVersion}, got ${appVersion}`,
)
}
if (!/^[a-f0-9]{64}$/i.test(bundleHash)) {
throw new Error('plugin package bundleSha256 is invalid')
}
if (!Number.isInteger(minNativeApiLevel) || minNativeApiLevel < 1) {
throw new Error('plugin package minNativeApiLevel is invalid')
}
if (
manifest.commonVersionRange !== undefined &&
(typeof manifest.commonVersionRange !== 'string' || !manifest.commonVersionRange.trim())
) {
throw new Error('plugin package commonVersionRange is invalid')
}
const bundleBytes = archive[bundleFile]
if (!bundleBytes) throw new Error(`plugin package bundle is missing: ${bundleFile}`)
const actualBundleHash = createHash('sha256').update(bundleBytes).digest('hex')
if (actualBundleHash !== bundleHash.toLowerCase()) {
throw new Error('plugin package bundleSha256 does not match bundle content')
}
return {
manifest,
packageName,
moduleId,
platform,
moduleVersion,
appVersion,
buildId,
bundleHash: actualBundleHash,
bundleFormat,
nativeBaselineId,
appVersionRange,
commonVersionRange: manifest.commonVersionRange,
minNativeApiLevel,
}
}

99
packages/update/scripts/release-package.test.mjs
查看文件

@ -1,99 +0,0 @@
import assert from 'node:assert/strict'
import { createHash } from 'node:crypto'
import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import path from 'node:path'
import test from 'node:test'
import { strToU8, zipSync } from 'fflate'
import { readReleasePackageIdentity } from './release-package.mjs'
function createPackage(root, overrides = {}, bundle = 'bundle') {
const bundleBytes = strToU8(bundle)
const manifest = {
schemaVersion: 1,
packageName: 'com.example.host',
moduleId: 'app',
platform: 'android',
version: '1.0.1',
appVersion: '8.0.0',
buildId: 'build-20260726',
bundleFile: 'app.android.bundle',
bundleSha256: createHash('sha256').update(bundleBytes).digest('hex'),
bundleFormat: 'hermes-bytecode',
builtAgainstNativeBaselineId: 'native-1',
appVersionRange: '>=8.0.0 <9.0.0',
commonVersionRange: '>=1.0.0 <2.0.0',
minNativeApiLevel: 2,
...overrides,
}
const file = path.join(root, 'app.android.xuqm.zip')
writeFileSync(
file,
zipSync({
'rn-manifest.json': strToU8(JSON.stringify(manifest)),
'app.android.bundle': bundleBytes,
}),
)
return file
}
const expected = {
packageName: 'com.example.host',
moduleId: 'app',
platform: 'android',
moduleVersion: '1.0.1',
appVersion: '8.0.0',
}
test('release identity is read from and verified against the packaged Bundle', () => {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-release-package-'))
try {
const identity = readReleasePackageIdentity(createPackage(root), expected)
assert.equal(identity.packageName, 'com.example.host')
assert.equal(identity.buildId, 'build-20260726')
assert.equal(identity.bundleFormat, 'hermes-bytecode')
assert.equal(identity.nativeBaselineId, 'native-1')
assert.equal(identity.appVersionRange, '>=8.0.0 <9.0.0')
assert.equal(identity.commonVersionRange, '>=1.0.0 <2.0.0')
assert.equal(identity.minNativeApiLevel, 2)
} finally {
rmSync(root, { recursive: true, force: true })
}
})
test('publishing requires and exactly matches the packaged packageName', () => {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-release-package-name-'))
try {
assert.throws(
() => readReleasePackageIdentity(createPackage(root, { packageName: undefined }), expected),
/manifest packageName is missing/,
)
assert.throws(
() =>
readReleasePackageIdentity(
createPackage(root, { packageName: 'com.example.other' }),
expected,
),
/packageName mismatch: expected com\.example\.host, got com\.example\.other/,
)
} finally {
rmSync(root, { recursive: true, force: true })
}
})
test('publishing rejects development identity and mismatched packaged Bundle hash', () => {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-release-package-invalid-'))
try {
assert.throws(
() => readReleasePackageIdentity(createPackage(root, { buildId: 'development' }), expected),
/without a release buildId/,
)
assert.throws(
() =>
readReleasePackageIdentity(createPackage(root, { bundleSha256: 'a'.repeat(64) }), expected),
/does not match bundle content/,
)
} finally {
rmSync(root, { recursive: true, force: true })
}
})

45
packages/update/scripts/source-map.mjs
查看文件

@ -1,45 +0,0 @@
import { readFileSync, writeFileSync } from 'node:fs'
import path from 'node:path'
function normalize(value) {
return value.replaceAll('\\', '/')
}
function externalSourceName(normalized) {
const nodeModulesMarker = '/node_modules/'
const markerIndex = normalized.lastIndexOf(nodeModulesMarker)
if (markerIndex >= 0) {
return `external/node_modules/${normalized.slice(markerIndex + nodeModulesMarker.length)}`
}
return `external/${normalized.split('/').filter(Boolean).at(-1) ?? 'unknown-source'}`
}
/**
* root 内绝对路径变成项目相对路径；root 外绝对路径只保留稳定的外部标识，
* 绝不把 `../` 剥掉后伪装成项目源码，也不泄露开发机用户名或目录。
*/
export function sanitizeSourcePath(source, projectRoot) {
if (typeof source !== 'string') return source
const normalizedSource = normalize(source)
const normalizedRoot = normalize(projectRoot).replace(/\/+$/, '')
const windowsAbsolute = path.win32.isAbsolute(source)
const posixAbsolute = path.posix.isAbsolute(normalizedSource)
if (!windowsAbsolute && !posixAbsolute) return normalizedSource
const pathApi = windowsAbsolute ? path.win32 : path.posix
const comparableSource = windowsAbsolute ? source : normalizedSource
const comparableRoot = windowsAbsolute ? projectRoot : normalizedRoot
const relative = pathApi.relative(comparableRoot, comparableSource)
const outside =
relative === '..' || relative.startsWith(`..${pathApi.sep}`) || pathApi.isAbsolute(relative)
return outside ? externalSourceName(normalizedSource) : normalize(relative || '.')
}
export function sanitizeSourceMapFile(sourceMapFile, projectRoot) {
const sourceMap = JSON.parse(readFileSync(sourceMapFile, 'utf8'))
delete sourceMap.sourcesContent
if (Array.isArray(sourceMap.sources)) {
sourceMap.sources = sourceMap.sources.map(source => sanitizeSourcePath(source, projectRoot))
}
writeFileSync(sourceMapFile, JSON.stringify(sourceMap))
}

31
packages/update/scripts/source-map.test.mjs
查看文件

@ -1,31 +0,0 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { sanitizeSourcePath } from './source-map.mjs'
test('Unix sources distinguish project files from external absolute paths', () => {
assert.equal(sanitizeSourcePath('/workspace/app/src/Home.tsx', '/workspace/app'), 'src/Home.tsx')
assert.equal(
sanitizeSourcePath('/Users/alice/shared/secret.ts', '/workspace/app'),
'external/secret.ts',
)
assert.equal(
sanitizeSourcePath('/Users/alice/app/node_modules/react/index.js', '/workspace/app'),
'external/node_modules/react/index.js',
)
})
test('Windows sources distinguish project files without leaking host directories', () => {
assert.equal(
sanitizeSourcePath('C:\\workspace\\app\\src\\Home.tsx', 'C:\\workspace\\app'),
'src/Home.tsx',
)
assert.equal(
sanitizeSourcePath('D:\\Users\\alice\\private\\secret.ts', 'C:\\workspace\\app'),
'external/secret.ts',
)
assert.equal(
sanitizeSourcePath('D:\\cache\\node_modules\\react\\index.js', 'C:\\workspace\\app'),
'external/node_modules/react/index.js',
)
})

61
packages/update/scripts/xuqm-config.mjs
查看文件

@ -2,8 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
import path from 'node:path' import path from 'node:path'
import semver from 'semver' import semver from 'semver'
/** 插件构建清单；与平台签发的 config.xuqmconfig 初始化文件没有关系。 */ export const CONFIG_FILE_NAME = 'xuqm.config.json'
export const CONFIG_FILE_NAME = 'xuqm.modules.json'
export const SUPPORTED_PLATFORMS = new Set(['android', 'ios']) export const SUPPORTED_PLATFORMS = new Set(['android', 'ios'])
export const SUPPORTED_MODULE_TYPES = new Set(['startup', 'common', 'app', 'buz']) export const SUPPORTED_MODULE_TYPES = new Set(['startup', 'common', 'app', 'buz'])
@ -27,18 +26,6 @@ export function readConfig(root = process.cwd()) {
export function validateConfig(config, root = process.cwd()) { export function validateConfig(config, root = process.cwd()) {
const errors = [] const errors = []
if (!config.appId) errors.push('appId is required') if (!config.appId) errors.push('appId is required')
if (
config.packageName !== undefined &&
(typeof config.packageName !== 'string' || config.packageName.trim() === '')
) {
errors.push('packageName must be a non-empty string')
}
if (
config.iosBundleId !== undefined &&
(typeof config.iosBundleId !== 'string' || config.iosBundleId.trim() === '')
) {
errors.push('iosBundleId must be a non-empty string')
}
if (!config.mainModuleName) errors.push('mainModuleName is required') if (!config.mainModuleName) errors.push('mainModuleName is required')
if (typeof config.pluginVersion !== 'string' || !semver.valid(config.pluginVersion)) { if (typeof config.pluginVersion !== 'string' || !semver.valid(config.pluginVersion)) {
errors.push('pluginVersion must be SemVer') errors.push('pluginVersion must be SemVer')
@ -46,19 +33,10 @@ export function validateConfig(config, root = process.cwd()) {
if (typeof config.appVersionRange !== 'string' || !semver.validRange(config.appVersionRange)) { if (typeof config.appVersionRange !== 'string' || !semver.validRange(config.appVersionRange)) {
errors.push('appVersionRange must be a valid SemVer range') errors.push('appVersionRange must be a valid SemVer range')
} }
if (config.release && Object.prototype.hasOwnProperty.call(config.release, 'apiToken')) {
errors.push('release.apiToken is forbidden; Jenkins must inject XUQM_API_TOKEN')
}
if (!Array.isArray(config.modules) || config.modules.length === 0) { if (!Array.isArray(config.modules) || config.modules.length === 0) {
errors.push('modules must contain at least one module') errors.push('modules must contain at least one module')
return errors return errors
} }
if (config.modules.length > 1 && !config.metroConfig) {
errors.push('metroConfig is required for multi-module builds')
}
if (config.metroConfig && !existsSync(path.resolve(root, config.metroConfig))) {
errors.push(`Metro config not found: ${config.metroConfig}`)
}
const ids = new Set() const ids = new Set()
for (const module of config.modules) { for (const module of config.modules) {
@ -95,45 +73,10 @@ export function validateConfig(config, root = process.cwd()) {
if (module.metroConfig && !existsSync(path.resolve(root, module.metroConfig))) { if (module.metroConfig && !existsSync(path.resolve(root, module.metroConfig))) {
errors.push(`Metro config not found for ${module.id}: ${module.metroConfig}`) errors.push(`Metro config not found for ${module.id}: ${module.metroConfig}`)
} }
if (module.ownershipRoots !== undefined) {
if (module.type !== 'common') {
errors.push(`ownershipRoots is only supported by the common module: ${module.id}`)
} else if (!Array.isArray(module.ownershipRoots) || module.ownershipRoots.length === 0) {
errors.push(`ownershipRoots must be a non-empty string array for ${module.id}`)
} else {
for (const ownershipRoot of module.ownershipRoots) {
if (
typeof ownershipRoot !== 'string' ||
ownershipRoot.trim() === '' ||
!existsSync(path.resolve(root, ownershipRoot))
) {
errors.push(
`ownership root not found for ${module.id}: ${ownershipRoot ?? '<missing>'}`,
)
}
}
}
}
} }
return errors return errors
} }
/**
* wire 协议统一使用 packageName，但值必须是目标平台自己的宿主身份。所有构建、校验
* 与发布入口只能通过这里解析，避免 Android applicationId 泄漏到 iOS 插件。
*/
export function resolveHostPackageId(config, platform) {
if (!SUPPORTED_PLATFORMS.has(platform)) {
throw new Error(`unsupported platform: ${platform}`)
}
const key = platform === 'ios' ? 'iosBundleId' : 'packageName'
const value = config?.[key]
if (typeof value !== 'string' || value.trim() === '') {
throw new Error(`${key} is required for ${platform} build and release`)
}
return value.trim()
}
export function readPackageVersion(root = process.cwd()) { export function readPackageVersion(root = process.cwd()) {
const packageFile = path.join(root, 'package.json') const packageFile = path.join(root, 'package.json')
if (!existsSync(packageFile)) throw new Error('package.json is missing') if (!existsSync(packageFile)) throw new Error('package.json is missing')
@ -168,7 +111,7 @@ export function resolveVersionedModules(config, root = process.cwd(), appVersion
...(module.commonVersionRange === undefined && ['app', 'buz'].includes(module.type) ...(module.commonVersionRange === undefined && ['app', 'buz'].includes(module.type)
? { commonVersionRange: defaultCommonRange } ? { commonVersionRange: defaultCommonRange }
: {}), : {}),
minNativeApiLevel: module.minNativeApiLevel ?? 2, minNativeApiLevel: module.minNativeApiLevel ?? 1,
})), })),
} }
} }

99
packages/update/scripts/xuqm-config.test.mjs
查看文件

@ -1,16 +1,15 @@
import assert from 'node:assert/strict' import assert from 'node:assert/strict'
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os' import { tmpdir } from 'node:os'
import path from 'node:path' import path from 'node:path'
import test from 'node:test' import test from 'node:test'
import { resolveHostPackageId, resolveVersionedModules, validateConfig } from './xuqm-config.mjs' import { resolveVersionedModules, validateConfig } from './xuqm-config.mjs'
function fixture() { function fixture() {
const root = mkdtempSync(path.join(tmpdir(), 'xuqm-config-')) const root = mkdtempSync(path.join(tmpdir(), 'xuqm-config-'))
writeFileSync(path.join(root, 'package.json'), JSON.stringify({ version: '7.2.14' })) writeFileSync(path.join(root, 'package.json'), JSON.stringify({ version: '7.2.14' }))
writeFileSync(path.join(root, 'common.ts'), '') writeFileSync(path.join(root, 'common.ts'), '')
writeFileSync(path.join(root, 'app.ts'), '') writeFileSync(path.join(root, 'app.ts'), '')
writeFileSync(path.join(root, 'metro.config.js'), 'module.exports = {}\n')
return root return root
} }
@ -19,11 +18,9 @@ test('plugins start at the configured plugin version independently from the app
try { try {
const config = { const config = {
appId: 'example', appId: 'example',
packageName: 'com.example.host',
mainModuleName: 'Example', mainModuleName: 'Example',
pluginVersion: '1.0.0', pluginVersion: '1.0.0',
appVersionRange: '>=7.2.14 <8.0.0', appVersionRange: '>=7.2.14 <8.0.0',
metroConfig: './metro.config.js',
modules: [ modules: [
{ id: 'common', type: 'common', entry: './common.ts' }, { id: 'common', type: 'common', entry: './common.ts' },
{ id: 'app', type: 'app', entry: './app.ts' }, { id: 'app', type: 'app', entry: './app.ts' },
@ -35,7 +32,7 @@ test('plugins start at the configured plugin version independently from the app
assert.equal(resolved.modules[0].moduleVersion, '1.0.0') assert.equal(resolved.modules[0].moduleVersion, '1.0.0')
assert.equal(resolved.modules[1].moduleVersion, '1.0.0') assert.equal(resolved.modules[1].moduleVersion, '1.0.0')
assert.equal(resolved.modules[1].commonVersionRange, '>=1.0.0 <2.0.0') assert.equal(resolved.modules[1].commonVersionRange, '>=1.0.0 <2.0.0')
assert.equal(resolved.modules[1].minNativeApiLevel, 2) assert.equal(resolved.modules[1].minNativeApiLevel, 1)
} finally { } finally {
rmSync(root, { recursive: true, force: true }) rmSync(root, { recursive: true, force: true })
} }
@ -64,93 +61,3 @@ test('an explicitly independently released module keeps its own version', () =>
rmSync(root, { recursive: true, force: true }) rmSync(root, { recursive: true, force: true })
} }
}) })
test('only common can own existing shared source roots', () => {
const root = fixture()
try {
mkdirSync(path.join(root, 'src', 'common'), { recursive: true })
const base = {
appId: 'example',
packageName: 'com.example.host',
mainModuleName: 'Example',
pluginVersion: '1.0.0',
appVersionRange: '>=1.0.0 <2.0.0',
metroConfig: './metro.config.js',
}
assert.deepEqual(
validateConfig(
{
...base,
modules: [
{
id: 'common',
type: 'common',
entry: './common.ts',
ownershipRoots: ['./src/common'],
},
],
},
root,
),
[],
)
assert.match(
validateConfig(
{
...base,
modules: [
{
id: 'app',
type: 'app',
entry: './app.ts',
ownershipRoots: ['./src/common'],
},
],
},
root,
).join('\n'),
/only supported by the common module/,
)
} finally {
rmSync(root, { recursive: true, force: true })
}
})
test('release token cannot be stored in xuqm.modules.json', () => {
const root = fixture()
try {
const errors = validateConfig(
{
appId: 'example',
packageName: 'com.example.host',
mainModuleName: 'Example',
pluginVersion: '1.0.0',
appVersionRange: '>=1.0.0 <2.0.0',
metroConfig: './metro.config.js',
release: { apiToken: 'must-not-enter-source' },
modules: [{ id: 'common', type: 'common', entry: './common.ts' }],
},
root,
)
assert.match(errors.join('\n'), /release\.apiToken is forbidden.*XUQM_API_TOKEN/)
} finally {
rmSync(root, { recursive: true, force: true })
}
})
test('host package identity resolves exactly once for each target platform', () => {
const config = {
packageName: 'com.example.android',
iosBundleId: 'com.example.ios',
}
assert.equal(resolveHostPackageId(config, 'android'), 'com.example.android')
assert.equal(resolveHostPackageId(config, 'ios'), 'com.example.ios')
assert.throws(
() => resolveHostPackageId({ packageName: 'com.example.android' }, 'ios'),
/iosBundleId is required for ios build and release/,
)
assert.throws(
() => resolveHostPackageId({ iosBundleId: 'com.example.ios' }, 'android'),
/packageName is required for android build and release/,
)
})

296
packages/update/scripts/xuqm-rn.mjs
查看文件

@ -1,7 +1,6 @@
#!/usr/bin/env node #!/usr/bin/env node
import { execFileSync } from 'node:child_process' import { execFileSync } from 'node:child_process'
import { createHash } from 'node:crypto'
import { import {
copyFileSync, copyFileSync,
existsSync, existsSync,
@ -15,7 +14,6 @@ import {
import { createRequire } from 'node:module' import { createRequire } from 'node:module'
import path from 'node:path' import path from 'node:path'
import process from 'node:process' import process from 'node:process'
import { strToU8, zipSync } from 'fflate'
import { import {
CONFIG_FILE_NAME, CONFIG_FILE_NAME,
SUPPORTED_PLATFORMS, SUPPORTED_PLATFORMS,
@ -24,16 +22,11 @@ import {
compatibleAppRange, compatibleAppRange,
parseModuleOptions, parseModuleOptions,
readConfig, readConfig,
resolveHostPackageId,
resolveVersionedModules, resolveVersionedModules,
selectModules, selectModules,
validateConfig, validateConfig,
} from './xuqm-config.mjs' } from './xuqm-config.mjs'
import { computeNativeBaseline } from './native-baseline.mjs' import { computeNativeBaseline } from './native-baseline.mjs'
import { parseBugCollectOption, parsePackageOptions } from './package-options.mjs'
import { validateReleaseConfig } from './release-config.mjs'
import { createAndroidReleaseIdentity } from './release-identity.mjs'
import { sanitizeSourceMapFile } from './source-map.mjs'
const root = process.cwd() const root = process.cwd()
const args = process.argv.slice(2) const args = process.argv.slice(2)
@ -48,15 +41,8 @@ function writeJson(file, value) {
writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`) writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`)
} }
async function validateReleaseConfigOnline(config, platform) { function childEnvironment() {
await validateReleaseConfig({ const environment = { ...process.env }
projectRoot: root,
packageName: resolveHostPackageId(config, platform),
})
}
function childEnvironment(overrides = {}) {
const environment = { ...process.env, ...overrides }
// Metro may set FORCE_COLOR in its transformer workers. Forward a single // Metro may set FORCE_COLOR in its transformer workers. Forward a single
// explicit color flag so those workers never inherit a contradictory pair. // explicit color flag so those workers never inherit a contradictory pair.
if (environment.NO_COLOR !== undefined) { if (environment.NO_COLOR !== undefined) {
@ -66,13 +52,13 @@ function childEnvironment(overrides = {}) {
return environment return environment
} }
function runReactNative(cliArgs, environment = {}) { function runReactNative(cliArgs) {
const reactNativeCli = path.join(root, 'node_modules', 'react-native', 'cli.js') const reactNativeCli = path.join(root, 'node_modules', 'react-native', 'cli.js')
if (!existsSync(reactNativeCli)) fail('react-native CLI is missing; install dependencies first') if (!existsSync(reactNativeCli)) fail('react-native CLI is missing; install dependencies first')
execFileSync(process.execPath, [reactNativeCli, ...cliArgs], { execFileSync(process.execPath, [reactNativeCli, ...cliArgs], {
stdio: 'inherit', stdio: 'inherit',
cwd: root, cwd: root,
env: childEnvironment(environment), env: childEnvironment(),
}) })
} }
@ -152,12 +138,10 @@ function init() {
writeJson(configFile, { writeJson(configFile, {
schemaVersion: 3, schemaVersion: 3,
appId: pkg.name ?? 'react-native-app', appId: pkg.name ?? 'react-native-app',
packageName: pkg.name ?? 'react-native-app',
mainModuleName: pkg.name ?? 'ReactNativeApp', mainModuleName: pkg.name ?? 'ReactNativeApp',
pluginVersion: '1.0.0', pluginVersion: '1.0.0',
appVersionRange: compatibleAppRange(pkg.version ?? '1.0.0'), appVersionRange: compatibleAppRange(pkg.version ?? '1.0.0'),
outputDir: './bundle', outputDir: './bundle',
metroConfig: './metro.config.js',
embeddedOutput: { embeddedOutput: {
android: './android/app/src/main/assets/rn-bundles', android: './android/app/src/main/assets/rn-bundles',
ios: './bundle/embedded/ios/rn-bundles', ios: './bundle/embedded/ios/rn-bundles',
@ -249,88 +233,12 @@ function parseSelectedModules(config, optionArgs) {
} }
} }
/**
* 独立构建 app/buz 时也必须先生成 startup/common 的共享模块表。
* 依赖 bundle 只参与本次构建，不会因为选择了单个 buz 就被一并发布。
*/
function resolveBuildModules(config, selectedModules) {
const selectedIds = new Set(selectedModules.map(module => module.id))
const needsCommon = selectedModules.some(module => ['app', 'buz'].includes(module.type))
const needsStartup = selectedModules.some(module => module.type !== 'startup')
const priorities = { startup: 0, common: 1, app: 2, buz: 3 }
return config.modules
.filter(
module =>
selectedIds.has(module.id) ||
(needsCommon && module.type === 'common') ||
(needsStartup && module.type === 'startup'),
)
.sort((left, right) => priorities[left.type] - priorities[right.type])
}
const OWNED_SOURCE_EXTENSION = /\.(?:js|jsx|ts|tsx)$/
const EXCLUDED_OWNERSHIP_SOURCE =
/(?:^|\/)(?:__tests__|tests?)(?:\/|$)|\.(?:spec|test)\.[^.]+$|\.d\.ts$/
function ownershipSourceFiles(directory, platform) {
const selected = new Map()
for (const relative of walkFiles(directory)) {
if (!OWNED_SOURCE_EXTENSION.test(relative) || EXCLUDED_OWNERSHIP_SOURCE.test(relative)) continue
const platformMatch = relative.match(/\.(android|ios|native|web)(?=\.[^.]+$)/)
const variant = platformMatch?.[1]
if (variant && variant !== platform && variant !== 'native') continue
const key = platformMatch ? relative.replace(`.${variant}`, '') : relative
const priority = variant === platform ? 3 : variant === 'native' ? 2 : 1
const existing = selected.get(key)
if (!existing || priority > existing.priority) {
selected.set(key, { absolute: path.join(directory, relative), priority })
}
}
return [...selected.values()].map(item => item.absolute).sort()
}
/**
* common 可声明若干唯一所有权目录。CLI 为当前平台生成一个临时入口，把这些目录
* 纳入 common 的依赖图但不执行模块；后续 app/buz 会按共享模块表过滤它们。
* 目录规则由 SDK 统一实现，宿主不再维护易遗漏的 require 清单。
*/
function buildEntryFile(module, platform) {
if (module.type !== 'common' || !module.ownershipRoots?.length) return module.entry
const generatedDirectory = path.join(root, '.xuqm-cache', 'ownership')
const generatedFile = path.join(generatedDirectory, `${module.id}.${platform}.js`)
const ownedFiles = module.ownershipRoots.flatMap(ownershipRoot =>
ownershipSourceFiles(path.resolve(root, ownershipRoot), platform),
)
const importPath = file => {
const relative = path.relative(generatedDirectory, file).split(path.sep).join('/')
return relative.startsWith('.') ? relative : `./${relative}`
}
const lines = [
`require(${JSON.stringify(importPath(path.resolve(root, module.entry)))})`,
'',
'function retainXuqmCommonOwnership() {',
...ownedFiles.map(file => ` require(${JSON.stringify(importPath(file))})`),
'}',
'',
'void retainXuqmCommonOwnership',
'',
]
mkdirSync(generatedDirectory, { recursive: true })
writeFileSync(generatedFile, lines.join('\n'))
return generatedFile
}
function build(platform, optionArgs = []) { function build(platform, optionArgs = []) {
assertPlatform(platform) assertPlatform(platform)
const config = doctor() const config = doctor()
resolveHostPackageId(config, platform) const modules = parseSelectedModules(config, optionArgs)
const versioned = resolveVersionedModules(config, root, process.env.XUQM_APP_VERSION)
const versionedConfig = { ...config, modules: versioned.modules }
const modules = parseSelectedModules(versionedConfig, optionArgs)
const buildModules = resolveBuildModules(versionedConfig, modules)
const useHermes = platform === 'android' && androidUsesHermes() const useHermes = platform === 'android' && androidUsesHermes()
const nativeBaselineId = computeNativeBaseline(root, platform) for (const module of modules) {
for (const [buildIndex, module] of buildModules.entries()) {
const outputDirectory = bundleOutputDirectory(root, config, platform, module.id) const outputDirectory = bundleOutputDirectory(root, config, platform, module.id)
rmSync(outputDirectory, { force: true, recursive: true }) rmSync(outputDirectory, { force: true, recursive: true })
mkdirSync(outputDirectory, { recursive: true }) mkdirSync(outputDirectory, { recursive: true })
@ -342,7 +250,7 @@ function build(platform, optionArgs = []) {
'--dev', '--dev',
'false', 'false',
'--entry-file', '--entry-file',
buildEntryFile(module, platform), module.entry,
'--bundle-output', '--bundle-output',
bundleFile(root, config, platform, module.id), bundleFile(root, config, platform, module.id),
'--assets-dest', '--assets-dest',
@ -351,30 +259,13 @@ function build(platform, optionArgs = []) {
] ]
const metroConfig = module.metroConfig ?? config.metroConfig const metroConfig = module.metroConfig ?? config.metroConfig
if (metroConfig) cliArgs.push('--config', metroConfig) if (metroConfig) cliArgs.push('--config', metroConfig)
// 每个 Release 模块始终生成独立 Source Map；是否上传由发布阶段决定。 if (module.sourceMap === true) {
cliArgs.push('--sourcemap-output', `${bundleFile(root, config, platform, module.id)}.map`) cliArgs.push('--sourcemap-output', `${bundleFile(root, config, platform, module.id)}.map`)
console.log(`xuqm-rn: building ${module.id}/${platform}`)
runReactNative(cliArgs.slice(1), {
XUQM_MODULE_CACHE_FILE: path.join(root, '.xuqm-cache', 'common-module-ids.json'),
XUQM_MODULE_ID: module.id,
XUQM_MODULE_INDEX: String(config.modules.findIndex(item => item.id === module.id)),
XUQM_MODULE_TYPE: module.type,
XUQM_RESET_MODULE_CACHE: buildIndex === 0 ? 'true' : 'false',
})
if (useHermes) compileHermesBundle(bundleFile(root, config, platform, module.id), true)
sanitizeSourceMapFile(`${bundleFile(root, config, platform, module.id)}.map`, root)
// startup 是随宿主 APK 固化的最小引导代码，不属于可在线发布插件。为它生成
// 发布包既没有安装入口，也容易让发布人员误认为它可以脱离整包升级。
if (module.type !== 'startup') {
createModulePackage(
config,
platform,
module,
versioned.appVersion,
nativeBaselineId,
useHermes ? 'hermes-bytecode' : 'javascript',
)
} }
console.log(`xuqm-rn: building ${module.id}/${platform}`)
runReactNative(cliArgs.slice(1))
if (useHermes)
compileHermesBundle(bundleFile(root, config, platform, module.id), module.sourceMap === true)
} }
return { config, modules } return { config, modules }
} }
@ -392,68 +283,10 @@ function walkFiles(directory, relativePrefix = '') {
function moduleAssetFiles(rootDirectory, bundleName) { function moduleAssetFiles(rootDirectory, bundleName) {
return walkFiles(rootDirectory).filter( return walkFiles(rootDirectory).filter(
file => file => file !== bundleName && file !== 'raw/keep.xml' && !file.endsWith('.map'),
file !== bundleName &&
file !== 'raw/keep.xml' &&
!file.endsWith('.map') &&
!file.endsWith('.xuqm.zip'),
) )
} }
function modulePackageFile(config, platform, moduleId) {
return path.join(
bundleOutputDirectory(root, config, platform, moduleId),
`${moduleId}.${platform}.xuqm.zip`,
)
}
/**
* 线上插件与 APK 内嵌插件共用同一份模块元数据。发布物始终是二进制 ZIP，避免
* Hermes 字节码经过 UTF-8 转换损坏，并让插件自己的图片、字体等资源原子到达。
*/
function createModulePackage(config, platform, module, appVersion, nativeBaselineId, bundleFormat) {
const directory = bundleOutputDirectory(root, config, platform, module.id)
const bundleName = `${module.id}.${platform}.bundle`
const bundleBytes = readFileSync(path.join(directory, bundleName))
const assetFiles = moduleAssetFiles(directory, bundleName)
const assets = assetFiles.map(relative => {
const bytes = readFileSync(path.join(directory, relative))
return {
path: relative,
byteLength: bytes.byteLength,
sha256: createHash('sha256').update(bytes).digest('hex'),
}
})
const manifest = {
schemaVersion: 1,
packageName: resolveHostPackageId(config, platform),
moduleId: module.id,
type: module.type,
platform,
version: module.moduleVersion,
appVersion,
appVersionRange: module.appVersionRange,
builtAgainstNativeBaselineId: nativeBaselineId,
bundleFormat,
buildId: process.env.XUQM_BUILD_ID ?? 'development',
bugCollectMode: process.env.XUQM_BUGCOLLECT_MODE ?? 'platform',
bundleFile: bundleName,
bundleByteLength: bundleBytes.byteLength,
bundleSha256: createHash('sha256').update(bundleBytes).digest('hex'),
...(module.commonVersionRange ? { commonVersionRange: module.commonVersionRange } : {}),
minNativeApiLevel: module.minNativeApiLevel,
assets,
}
const archive = {
'rn-manifest.json': strToU8(`${JSON.stringify(manifest, null, 2)}\n`),
[bundleName]: new Uint8Array(bundleBytes),
}
for (const asset of assets) {
archive[`assets/${asset.path}`] = new Uint8Array(readFileSync(path.join(directory, asset.path)))
}
writeFileSync(modulePackageFile(config, platform, module.id), zipSync(archive, { level: 9 }))
}
function copyWithoutConflict(source, target, owners, owner) { function copyWithoutConflict(source, target, owners, owner) {
const relative = path.relative(path.dirname(target), target) const relative = path.relative(path.dirname(target), target)
if (existsSync(target)) { if (existsSync(target)) {
@ -474,14 +307,11 @@ function createManifest(config, platform, modules, appVersion, nativeBaselineId)
for (const module of modules) { for (const module of modules) {
const directory = bundleOutputDirectory(root, config, platform, module.id) const directory = bundleOutputDirectory(root, config, platform, module.id)
const bundleName = `${module.id}.${platform}.bundle` const bundleName = `${module.id}.${platform}.bundle`
const bundleBytes = readFileSync(path.join(directory, bundleName))
entries[module.id] = { entries[module.id] = {
id: module.id, id: module.id,
type: module.type, type: module.type,
directory: module.directory ?? module.id, directory: module.directory ?? module.id,
bundleFile: bundleName, bundleFile: bundleName,
sha256: createHash('sha256').update(bundleBytes).digest('hex'),
byteLength: bundleBytes.byteLength,
moduleVersion: module.moduleVersion, moduleVersion: module.moduleVersion,
appVersionRange: module.appVersionRange, appVersionRange: module.appVersionRange,
builtAgainstNativeBaselineId: nativeBaselineId, builtAgainstNativeBaselineId: nativeBaselineId,
@ -503,8 +333,6 @@ function createManifest(config, platform, modules, appVersion, nativeBaselineId)
bundleFormat: platform === 'android' && androidUsesHermes() ? 'hermes-bytecode' : 'javascript', bundleFormat: platform === 'android' && androidUsesHermes() ? 'hermes-bytecode' : 'javascript',
version: config.manifestVersion ?? 1, version: config.manifestVersion ?? 1,
nativeBaselineId, nativeBaselineId,
buildId: process.env.XUQM_BUILD_ID ?? 'development',
bugCollectMode: process.env.XUQM_BUGCOLLECT_MODE ?? 'platform',
modules: entries, modules: entries,
} }
} }
@ -547,22 +375,11 @@ function embed(platform, optionArgs = []) {
rmSync(target, { force: true, recursive: true }) rmSync(target, { force: true, recursive: true })
mkdirSync(target, { recursive: true }) mkdirSync(target, { recursive: true })
const owners = new Map() const owners = new Map()
const assetOwners = new Map()
const nativeBaselineId = computeNativeBaseline(root, platform) const nativeBaselineId = computeNativeBaseline(root, platform)
for (const module of versioned.modules) { for (const module of versioned.modules) {
const sourceRoot = bundleOutputDirectory(root, config, platform, module.id) const sourceRoot = bundleOutputDirectory(root, config, platform, module.id)
const bundleName = `${module.id}.${platform}.bundle` const bundleName = `${module.id}.${platform}.bundle`
const assets = moduleAssetFiles(sourceRoot, bundleName) for (const relative of [bundleName, ...moduleAssetFiles(sourceRoot, bundleName)]) {
for (const relative of assets) {
const existingOwner = assetOwners.get(relative)
if (existingOwner) {
throw new Error(
`asset ownership collision: ${relative} belongs to both ${existingOwner} and ${module.id}; move shared assets into common ownershipRoots`,
)
}
assetOwners.set(relative, module.id)
}
for (const relative of [bundleName, ...assets]) {
copyWithoutConflict( copyWithoutConflict(
path.join(sourceRoot, relative), path.join(sourceRoot, relative),
path.join(target, relative), path.join(target, relative),
@ -581,82 +398,33 @@ function embed(platform, optionArgs = []) {
} }
function publish(platform, optionArgs) { function publish(platform, optionArgs) {
const { bugCollectMode, remaining } = parseBugCollectOption( const { moduleIds } = parseModuleOptions(optionArgs)
optionArgs,
process.env.XUQM_BUGCOLLECT_MODE ?? 'platform',
)
const { moduleIds } = parseModuleOptions(remaining)
const buildOptions = moduleIds.flatMap(moduleId => ['--module', moduleId]) const buildOptions = moduleIds.flatMap(moduleId => ['--module', moduleId])
const previousBuildId = process.env.XUQM_BUILD_ID build(platform, buildOptions)
const previousVersionCode = process.env.XUQM_VERSION_CODE const releaseScript = new URL('./xuqm_release.mjs', import.meta.url)
const previousBugCollectMode = process.env.XUQM_BUGCOLLECT_MODE execFileSync(process.execPath, [releaseScript.pathname, '--platform', platform, ...optionArgs], {
if (platform === 'android' && !previousBuildId) { cwd: root,
const identity = createAndroidReleaseIdentity({ projectRoot: root }) stdio: 'inherit',
process.env.XUQM_BUILD_ID = identity.buildId })
process.env.XUQM_VERSION_CODE = String(identity.versionCode)
}
process.env.XUQM_BUGCOLLECT_MODE = bugCollectMode
try {
build(platform, buildOptions)
const releaseScript = new URL('./xuqm_release.mjs', import.meta.url)
execFileSync(
process.execPath,
[releaseScript.pathname, '--platform', platform, ...optionArgs],
{
cwd: root,
stdio: 'inherit',
},
)
} finally {
if (previousBuildId === undefined) delete process.env.XUQM_BUILD_ID
else process.env.XUQM_BUILD_ID = previousBuildId
if (previousVersionCode === undefined) delete process.env.XUQM_VERSION_CODE
else process.env.XUQM_VERSION_CODE = previousVersionCode
if (previousBugCollectMode === undefined) delete process.env.XUQM_BUGCOLLECT_MODE
else process.env.XUQM_BUGCOLLECT_MODE = previousBugCollectMode
}
} }
async function packageApp(platform, optionArgs) { function packageApp(platform, optionArgs) {
assertPlatform(platform) assertPlatform(platform)
if (platform !== 'android') fail('native package command currently supports android only') if (platform !== 'android') fail('native package command currently supports android only')
let packageOptions const apkIndex = optionArgs.indexOf('--apk')
try { const apk = apkIndex >= 0
packageOptions = parsePackageOptions(optionArgs) if (apk) optionArgs.splice(apkIndex, 1)
} catch (error) { if (optionArgs.length) fail(`unknown option(s): ${optionArgs.join(' ')}`)
fail(error instanceof Error ? error.message : String(error))
}
const { apk, bugCollectMode } = packageOptions
const config = doctor()
await validateReleaseConfigOnline(config, platform)
const buildIdentity = createAndroidReleaseIdentity({ projectRoot: root })
const androidDirectory = path.join(root, 'android') const androidDirectory = path.join(root, 'android')
const wrapper = path.join( const wrapper = path.join(
androidDirectory, androidDirectory,
process.platform === 'win32' ? 'gradlew.bat' : 'gradlew', process.platform === 'win32' ? 'gradlew.bat' : 'gradlew',
) )
if (!existsSync(wrapper)) fail('Android Gradle wrapper is missing') if (!existsSync(wrapper)) fail('Android Gradle wrapper is missing')
execFileSync( execFileSync(wrapper, [apk ? 'assembleRelease' : 'bundleRelease'], {
wrapper, cwd: androidDirectory,
[ stdio: 'inherit',
apk ? 'assembleRelease' : 'bundleRelease', })
`-PXUQM_VERSION_CODE=${buildIdentity.versionCode}`,
`-PXUQM_BUILD_ID=${buildIdentity.buildId}`,
`-PXUQM_BUGCOLLECT_MODE=${bugCollectMode}`,
],
{
cwd: androidDirectory,
stdio: 'inherit',
env: childEnvironment({
XUQM_BUGCOLLECT_MODE: bugCollectMode,
XUQM_BUILD_ID: buildIdentity.buildId,
XUQM_VERSION_CODE: String(buildIdentity.versionCode),
}),
},
)
console.log(
`xuqm-rn: release identity versionCode=${buildIdentity.versionCode} buildId=${buildIdentity.buildId}`,
)
} }
function startMetro(optionArgs) { function startMetro(optionArgs) {
@ -717,7 +485,7 @@ try {
publish(args.shift() ?? 'android', args) publish(args.shift() ?? 'android', args)
break break
case 'package': case 'package':
await packageApp(args.shift() ?? 'android', args) packageApp(args.shift() ?? 'android', args)
break break
default: default:
printHelp() printHelp()

某些文件未显示，因为此 diff 中更改的文件太多 显示更多