MetonaTeam/MetonaSqlark
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(v0.8.0): 全量回归审查 —— 1 处 P0 数据丢失 + 4 处 P1 + 9 处 P2 根因修复

Browse Source 
方法：四个对抗性子代理分头审查（数据正确性 / 文档宣称 vs 实现 / 公共 API 契约 /
测试质量），每条结论要求可复现证据；逐条复核 + 探针确认 + 变异验证（40 项全部
被对应用例拦住）。

P0：事务活跃期间 repair()/close()/周期 checkpoint 推进 WAL 水位 → 已 COMMIT 的
事务整批消失且恢复报告"干净"。根因 hasPendingFlushData()/computeDurableLsn()
不看 txnSnapshot；守卫此前只在 CheckpointManager 两个回调里。修复：守卫下沉到
computeDurableLsn() 与 advanceWalCheckpoint() 入口（唯一实现）。

P1：
- WAL 前缀缺失丢弃整段活分片（回退上一代 manifest 时 kept 为空）→ 前缀缺失单独
  记录，后缀照常重放；仅 fromLsn === 0 时才算真异常
- 孤儿回收门槛只看引擎层 dataLossSuspected，漏掉 LSM 层被丢的 SSTable →
  统一 describeRecoveryDamage() 聚合判定（损坏时绝不删"引用不到"的文件）
- vacuum() 逐层压缩绕过维护链 → vacuumLevels() 每层作为维护链任务执行
- reclaimRetiredNow() 无视在途读者（读者把"已退休"读成"文件损坏"）→ 有读者时
  退化为延迟回收

P2：WAL 记录级 CRC 损坏不计数不上报；旧格式表结构记录形状损坏静默当空库；
bloomFilterBitsPerKey 配置被接受却完全不生效（构建器写死默认值，实现缺陷）；
幽灵 meta；介质读故障等于文件损坏的语义无用例；manifest 回读校验两条守卫无用例；
文件名≠载荷世代判定无用例；pageIdWatermark 单调性无用例；分片号两条真实不变量
无用例。

覆盖率口径（第二处漏洞）：interface.ts 混着三个运行时函数（cloneRow 等）却被
描述为"纯类型、不纳入统计" → 实现搬到 src/engine/row_clone.ts；搬完门禁真的
失败（functions 93.84% < 94%），补测退化路径后通过。

测试质量：3 条空壳用例改值级断言；1 条"全损坏"用例实际只走缓存 → 拆成两条真
用例；5 秒墙钟 race 改门控 + 失败上限；setTimeout 改 whenIdle()；<= 收紧为 <。

变异脚本加固：正控（干净基线必须全绿）、编译失败/0 用例单独归类、300s 超时、
逐字节 sha256 恢复校验、O_EXCL 进程锁、锚点唯一性；变异 22 → 40 项。

文档两轮订正（16 + 11 条不成立宣称）：MVCC 快照隔离、backup 一致性快照、
"空洞检测截断"、体积（251,109 B / gzip 63,145 B）、测试与覆盖率数字、
"5 种存储引擎"、Tree-shakable、错误码表补 16 个码、恢复报告字段、已知限制
（回退单向 / 多实例依赖 Web Locks / manifest 体积 / 尾部 WAL 分片不可识别）。

验证：常规套件 92 套件 / 1980 用例全绿；覆盖率 90.59 / 82.59 / 94.14 / 93.50
（阈值 90/82/94/93）；e2e 14/14（真实 Chromium + OPFS + CDP 崩溃）；
重型套件 4 套件 / 27 用例；变异 40/40；lint + 两份 tsc 干净；dist 已重建。
This commit is contained in:
thzxx
2026-09-15 16:33:40 +08:00
parent c3757f486c
commit 0b44620721
34 changed files with 4026 additions and 641 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+43 -17
View File
@@ -3,8 +3,8 @@
<p align="center">
<img src="https://img.shields.io/badge/version-0.8.0-blue?style=flat-square" alt="version">
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license">
<img src="https://img.shields.io/badge/coverage-90.34%25%20stmts-brightgreen?style=flat-square" alt="coverage">
<img src="https://img.shields.io/badge/tests-1935%20passed-success?style=flat-square" alt="tests">
<img src="https://img.shields.io/badge/coverage-90.59%25%20stmts-brightgreen?style=flat-square" alt="coverage">
<img src="https://img.shields.io/badge/tests-1980%20passed-success?style=flat-square" alt="tests">
</p>
> 基于 TypeScript 的**前端关系型数据库**：完整 SQL + Query Builder 双 API，
@@ -55,7 +55,7 @@
**生产级可靠性**
- **崩溃恢复** — WAL 原子写入 + CRC-32 完整性校验（SSTable 整文件 + WAL 记录）、空洞检测截断、打开时损坏自愈、`repair()` 清理重建
- **崩溃恢复** — WAL 原子写入 + CRC-32 完整性校验（SSTable 整文件 + WAL 记录）、分片空洞与记录损坏**如实上报**（`ARIA_WAL_GAP` / `droppedWALRecords`，拒绝静默截断）、打开时损坏自愈、`repair()` 清理重建
- **全库加密** — AES-256-GCM 透明加密（PBKDF2 密钥派生 + 密码验证 + 篡改检测），`encryption.password` 一键启用
- **多标签页独占锁** — Web Locks API，第二个标签页打开同一库抛 `ARIA_LOCKED`
- **数据安全** — 输入校验（`required` / `maxLength` / `min` / `max`）、SQL 注入防护、Bloom Filter 快速否定
@@ -91,7 +91,7 @@ npm install @metona-team/metona-sqlark
<script src="https://git.metona.cn/MetonaTeam/MetonaSqlark/raw/branch/master/dist/metona-sqlark.min.js"></script>
```
或从 [`dist/`](./dist/) 下载：`metona-sqlark.js`（UMD 开发版）/ `metona-sqlark.min.js`（压缩版，gzip ~27KB）/ `metona-sqlark.esm.js` / `metona-sqlark.cjs` / `metona-sqlark.d.ts`
或从 [`dist/`](./dist/) 下载：`metona-sqlark.js`（UMD 开发版）/ `metona-sqlark.min.js`（压缩版：实测 251,109 字节 / gzip 63,145 字节）/ `metona-sqlark.esm.js` / `metona-sqlark.cjs` / `metona-sqlark.d.ts`
---
@@ -371,9 +371,9 @@ const rows = await db.query('SELECT * FROM users');
|------|------|
| **LSM-Tree** | MemTable（红黑树）→ 多级 SSTable，异步 Compaction（从存储兜底加载），写背压 |
| **页面化存储** | SSTable 存为 4KB 页面（FileManager 分配 pageId + BufferPool LRU 缓存 256 页 ≈ 1MB），`pageStorage` 在 opfs/kv 后端默认启用 |
| **WAL** | 分片文件 `__wal_%06d.bin` + 真追加；标准 CRC32 记录校验；full/batch/none 三模式；**LSN 全库单调**（manifest 记高水位）；分片号只增不减；空洞（含前缀缺失）显式上报 `ARIA_WAL_GAP`；16MB 阈值自动 checkpoint（活跃事务期间不截断） |
| **WAL** | 分片文件 `__wal_%06d.bin` + 真追加；标准 CRC32 记录校验（记录级 CRC 失败会计数并上报 `droppedWALRecords`）；full/batch/none 三模式；**LSN 全库单调**（manifest 记高水位）；分片号**绝不回退、也绝不低于 manifest 水位**（整体清空后允许复用最后用过的号）；内部空洞与记录损坏显式上报（`gaps` / `corruptRecords`），水位从未推进时的前缀缺失同样按空洞上报，水位已推进时前缀缺失视为"已清理的前缀"；16MB 阈值自动 checkpoint（活跃事务期间不截断） |
| **单一提交点** | `__aria_manifest_<gen>`：页面水位 + 各命名空间 SSTable 元数据 + 表结构 + WAL 起始位置 + 待落盘冻结表意图，一次原子提交（头部/载荷双 CRC，先写后验，保留两代）。顺序固定为**数据落盘 → manifest 提交 → 才允许截断 WAL / 删除旧文件**；恢复只认最后一份 CRC 通过的世代，元数据损坏抛 `ARIA_MANIFEST_CORRUPT`（不再静默当空库） |
| **崩溃恢复** | 打开时完整性校验（整文件 CRC-32；**介质读故障不再被当成"文件不存在"**，抛 `ARIA_SSTABLE_READ_FAILED` 且不误删元数据）、按 LSN 水位重放 WAL、恢复后自动重建二级索引；`getRecoveryReport()` 返回 `{droppedSSTables, dataLossSuspected, walGaps, legacyImported, manifestFallback}`；`repair()` 只在 manifest 健康时回收孤儿页面 |
| **崩溃恢复** | 打开时完整性校验（整文件 CRC-32；**介质读故障不再被当成"文件不存在"**，抛 `ARIA_SSTABLE_READ_FAILED` 且不误删元数据）、按 LSN 水位重放 WAL、恢复后自动重建二级索引；`getRecoveryReport()` 返回 `{droppedSSTables, dataLossSuspected, walGaps, droppedWALRecords, legacyImported, manifestFallback}`；`repair()` 只在 manifest 健康时回收孤儿页面 |
| **Compaction** | 整层合并不再"先摘层再合并"（合并期间该层对读者始终可见）；底部层原地合并**回收墓碑**（删除密集场景空间不再无界增长）；按层 `compacting` 集合（跨层触发不丢失）；被取代的 SSTable 进入**退休表**，等更早的读者退出后才物理删除 |
| **全库加密** | `encryption.password` → EncryptedBackend 透明加解密（WAL/SSTable/Schema/元数据全密文）；PBKDF2 派生 + salt 持久化；密码错误/篡改 → `ARIA_DECRYPT_ERROR` |
| **MVCC** | 版本链仅作事务内 undo（提交即清理，**无快照隔离**；事务串行）；自动 GC |
@@ -391,6 +391,7 @@ const rows = await db.query('SELECT * FROM users');
| `memtableSizeThreshold` | `number` | `4MB` | MemTable 刷盘阈值 |
| `levelSizeMultiplier` | `number` | `10` | LSM 层级容量倍数 |
| `bloomFilterBitsPerKey` | `number` | `10` | Bloom Filter 每 key 位数 |
| `maxMemoryMB` | `number` | `64` | 内存预算（MB）：主 LSM 估算内存超限时触发 flush + MVCC GC |
| `walEnabled` | `boolean` | `true` | 是否启用 WAL |
| `walSyncMode` | `'full' \| 'batch' \| 'none'` | `'full'` | WAL 同步模式 |
| `checkpointInterval` | `number` | `1000` | Checkpoint 间隔（操作数） |
@@ -422,7 +423,7 @@ const { data, loading, error, refresh } = useSqlarkQuery(db, 'SELECT * FROM user
npm install # 安装依赖
npm run dev # 开发模式（localhost:3001）
npm run build # 生产构建（生成 dist/）
npm test # 运行测试（1935 用例 · 91 套件；+4 个重型套件）
npm test # 运行测试（1980 用例 · 92 套件；+4 个重型套件）
python3 scripts/mutation-b6.py # 变异验证：把 B-6 的修复逐项回退，对应用例必须失败
npm run test:e2e # Playwright e2e（真实 Chromium + OPFS + 崩溃注入，需先 build）
npm run lint # 代码检查
@@ -435,11 +436,11 @@ npm run typecheck # 类型检查
| 指标 | 数值 |
|------|------|
| 测试用例 | 1935（91 套件）+ 14 Playwright e2e，另 4 个重型套件在独立 CI job 串行运行 |
| 语句覆盖率 | 90.34%（8391/9288） |
| 分支覆盖率 | 82.16%（4367/5315） |
| 函数覆盖率 | 94.06%（1204/1280） |
| 行覆盖率 | 93.23%（7606/8158） |
| 测试用例 | 1980（92 套件）+ 14 Playwright e2e，另 4 个重型套件在独立 CI job 串行运行 |
| 语句覆盖率 | 90.59%（8532/9418） |
| 分支覆盖率 | 82.59%（4452/5390） |
| 函数覆盖率 | 94.14%（1223/1299） |
| 行覆盖率 | 93.50%（7727/8264） |
| SQL 关键字 | 72 |
| 存储模式 | 4（`memory` / `disk` / `hybrid` / `aria`） |
| 存储后端 | 3（OPFS / KVStore / Memory），Aria 引擎另有 LSM-Tree + WAL + 页面化 |
@@ -447,7 +448,10 @@ npm run typecheck # 类型检查
> **覆盖率口径**：`collectCoverageFrom = src/**/*.ts`，仅排除两个**纯类型声明**文件
> （`engine/interface.ts`、`query/ast.ts` —— 它们只有 interface/type，可执行语句为 0，
> 纳入统计只会稀释分母）。CI 常规 job 带 `--coverage` 运行，
> 纳入统计只会稀释分母）。v0.8.0 审查曾发现 `interface.ts` 里混着三个运行时函数
> （`cloneRow`/`cloneRowFallback`/`cloneRows`）—— 已搬到 `src/engine/row_clone.ts`
> 并纳入统计（搬完门禁立刻因 functions 93.84% < 94% 失败，补测退化路径后通过）。
> CI 常规 job 带 `--coverage` 运行，
> `jest.config.cjs` 的 `coverageThreshold` 为 statements 90 / branches 82 /
> functions 94 / lines 93，任一项不达标即失败 —— **门槛不达标不允许发版**。
>
@@ -462,9 +466,13 @@ npm run typecheck # 类型检查
- **存储布局在 v0.8.0 变更** — 元数据从"每个命名空间一份裸 JSON"（`__aria_lsm_meta*` /
`__aria_schemas`）收敛为 `__aria_manifest_<generation>`（带世代号与双 CRC）。
旧库**首次用 v0.8.0 打开时自动迁移**（旧键保留不删，可回退旧版本），迁移遇到损坏
的旧元数据会明确报 `ARIA_LEGACY_META_CORRUPT` 而不是当成空库。直接读取这些内部
key 的外部脚本需要跟着改（引擎侧无公开 API 依赖它们）。
旧库**首次用 v0.8.0 打开时自动迁移**（旧键保留不删），迁移遇到损坏的旧元数据会
明确报 `ARIA_LEGACY_META_CORRUPT` 而不是当成空库。直接读取这些内部 key 的外部
脚本需要跟着改（引擎侧无公开 API 依赖它们）。
* **回退是单向的**：迁移后所有新写入只进 manifest，旧的 `__aria_lsm_meta*` /
`__aria_schemas` 停留在迁移那一刻。用旧版本打开同一个库会看到**迁移时刻的旧
视图**（不是"数据都在"），继续写入还会让两套布局分叉 —— 需要回退旧版本时，
先用 v0.8.0 导出数据，不要指望旧键是新数据的镜像。
- **单列主键** — 复合主键暂不支持（建表时显式 `SCHEMA_ERROR`），列入 v0.8 路线图
- **写语句关联引用** — UPDATE/DELETE 的 WHERE 支持非关联子查询（`IN (SELECT)` / 标量子查询），关联引用（`$col` / 关联 EXISTS）显式抛 `NOT_SUPPORTED`（不静默）
- **`backup()` 不是跨表一致性快照** — 实现为**逐表读取**（Aria 走引擎级 `backup()`，
@@ -476,6 +484,23 @@ npm run typecheck # 类型检查
- **建表 UNIQUE 约束** — 不可经 `DROP INDEX` 解除（对齐 SQLite，需重建表）；仅 `CREATE UNIQUE INDEX` 添加的约束可随索引删除
- **唯一值交换更新** — 同一语句内两行互换唯一列值（A:x→y, B:y→x）保守拒绝（最终状态合法但报 `UNIQUE_VIOLATION`）
- **主键非空** — 主键列强制非空（SQL 语义 PK 隐含 NOT NULL），`INSERT`/`UPDATE` 置 null/undefined 抛 `VALIDATION_ERROR`
- **多实例写入保护依赖 Web Locks** — AriaEngine 用 Web Locks 做库级独占：第二个实例
打开同一个库时抛 `ARIA_LOCKED`，这是**唯一受支持**的多标签页写入方式。运行环境
没有 Web Locks 时该保护会自动降级为"提交点冲突检测"（manifest 世代号单调 + 提交前
检查是否存在别的实例提交的更新世代 → 抛 `STALE_INSTANCE`），但降级只保证
**不静默覆盖别人的提交**，不保证多实例写入的数据完整性：被拒绝的那一方此前
已写入自己 WAL 分片的记录，可能被胜出实例的 checkpoint 当作可回收前缀清掉。
结论：**不要在没有 Web Locks 的环境里让两个实例同时写同一个库**；需要并发访问时
由应用层串行化（如 SharedWorker / 主标签页代理）。
- **manifest 体积随 SSTable 数量增长** — 单一提交点把全部命名空间的 SSTable 元数据
（键范围、页面 id 列表、大小）+ 表结构 + WAL 水位写进**同一个文件**，每次提交
整体重写（保留两代）。因此元数据量与已落盘 SSTable 数成正比：长期高频写入、
层级很多且迟迟不合并的库，其 manifest 会明显大于数据本身之外的一般预期。当前
没有"元数据分层/增量"机制，`vacuum()` 合并层级是唯一的收敛手段（列入后续版本）。
- **尾部 WAL 分片丢失无法从介质自身识别** — 分片内部空洞（中间缺号）与记录级 CRC
损坏都会被上报；但如果**最后一个**分片整个消失，介质上没有任何"它本该存在"的证据
（manifest 只记 `startSegment`/`nextLsn`，不记最后分片号），此时只能靠
`ARIA_WRITE_LOST`（有未落盘冻结表却重放不到任何记录）兜住"确定丢数据"的情况。
### 浏览器兼容性
@@ -487,7 +512,8 @@ npm run typecheck # 类型检查
| Node.js | 16+ | ✅ | ✅（内存介质） | ✅（内存介质） |
> **OPFS**：基础 API（`createWritable` 原子写）在 Chromium 102+ / Firefox 111+ / Safari 15.2+ 均支持。
> 无跨文件事务，AriaEngine 以 WAL 分片单文件原子写 + 空洞检测截断保证崩溃一致性。
> 无跨文件事务，AriaEngine 以 WAL 分片单文件原子写 + manifest 单一提交点保证崩溃一致性；
> 分片空洞与记录级损坏都会被**显式上报**（恢复报告 + 告警），不做静默截断。
>
> **多标签页保护**：AriaEngine 通过 Web Locks 获取库级独占锁，第二个标签页打开同一库抛 `ARIA_LOCKED`。