release: v0.5.1 — 存储后端生产级硬化（CRC-32/全库加密/WAL分片/页面化存储/多标签页锁/e2e）+ 深度审查修复（假实现接线/死代码清理）
This commit is contained in:
thzxx
+109
@@ -2,6 +2,115 @@
|
||||
|
||||
All notable changes to MetonaSqlark will be documented in this file.
|
||||
|
||||
## [0.5.1] - 2026-08-10
|
||||
|
||||
### 深度审查：消除假实现/半成品/死代码
|
||||
|
||||
> 对全部源码做系统性审查，修复"宣称存在但从未接线"的假实现、补齐无入口的半成品、
|
||||
> 删除无引用的死代码。
|
||||
|
||||
### Added（假实现接线）
|
||||
|
||||
- **CRUD 生命周期钩子真实接线** — 此前 `beforeInsert`/`afterInsert`/`beforeUpdate`/`afterUpdate`/`beforeDelete`/`afterDelete`
|
||||
六个钩子仅存在于类型与文档宣称（"14 种钩子"），从未被任何路径触发。现已在两条路径真实触发：
|
||||
- Table API：`table().insert/insertMany/update().execute()/delete().execute()`
|
||||
- SQL：`db.query("INSERT/UPDATE/DELETE ...")`
|
||||
参数与文档一致（beforeInsert: rows[]、afterUpdate: query, updates, count 等）；事务路径不触发（Table 无 hooks 回调，与现状一致）
|
||||
- **EXPLAIN SQL 入口** — 此前 executor 有 EXPLAIN 分支但 parser 无法解析（无 token），只能手工构造 AST 测试。
|
||||
补齐 `EXPLAIN <statement>` 语法（tokens/lexer/parser），任意引擎可用
|
||||
- **ANALYZE / REINDEX / VACUUM SQL 入口** — 此前仅有 AriaEngine 方法（`(engine as any)` 才能调用），README 宣称能力但用户无法触发。
|
||||
补齐 `ANALYZE [TABLE] name` / `REINDEX [TABLE] name` / `VACUUM` 语法；不支持的引擎抛 `NOT_SUPPORTED`
|
||||
- **SAVEPOINT SQL 入口** — 补齐 `SAVEPOINT name` / `ROLLBACK TO [SAVEPOINT] name` / `RELEASE [SAVEPOINT] name`；
|
||||
`ROLLBACK [TRANSACTION]` 保持原语义
|
||||
- **db.backup() 公共方法** — 引擎级 backup（MVCC 一致性视图）此前无公共入口；Aria 走引擎级，其余引擎回退 exportAll
|
||||
|
||||
### Removed（死代码）
|
||||
|
||||
- **`src/utils.ts` 整文件** — generateId/escapeHTML/deepMerge/debounce/throttle/isBrowser 在 src 内零引用
|
||||
（v0.0.1 遗留，仅测试锁定）；连同 tests/utils.test.ts 删除
|
||||
- **`estimateQueryCost`（未接线的"查询优化器"）** — 实现与测试存在但从未接入查询路径（find 用 tryIndexLookup 硬编码），删除消除"优化器存在但没用"假象
|
||||
- **MVCC 读侧全套** — readVersion/getLatestCommittedVersions/clearTable/getActiveTxnCount/isActive/getActiveWriteKeys：
|
||||
引擎事务读取走 txnSnapshot（MVCC 仅作 undo log），读侧实现从未执行。删除并改写相关测试为验证版本链清理/GC 行为
|
||||
- **统计/辅助死方法** — EvictionManager.getAllPages/getSize/popLRU/getCapacity、BufferPool.getCachedPageCount/getDirtyPageCount/getCapacity/newPage、
|
||||
WAL.isEnabled/getLSN、CheckpointManager.forceCheckpoint/setInterval/getOpCount、LSM.isInitialized/getCacheSize/getCacheLimit、
|
||||
SSTableReader.getMeta/getIndexBlockCount/getStoredChecksum、BloomFilter.getBitSize/getInsertedCount、MemTable.contains、
|
||||
FileManager.allocateTableRootPage/createEmptyPage、OPFSEngine.loadTableIntoMemory、QueryExecutor.setMaxRowsPerQuery、
|
||||
ConnectionManager.getRefCount
|
||||
- **类型/常量死代码** — STORAGE_MODES/DISK_ENGINES、ColumnEncoding/DEFAULT_BLOCK_SIZE/DataBlock、CallbackEntrySource、StatementType、AggregateExpression、SubqueryExpression
|
||||
- **Crypto 全局兼容层** — initCrypto/encryptPage/decryptPage/closeCrypto/isCryptoEnabled（v0.5.0 后引擎走 EncryptedBackend 实例，全局单例无消费者）；删除过时的"全局加密落盘"测试（aria-encryption.test.ts 已覆盖等价路径）
|
||||
|
||||
### Changed
|
||||
|
||||
- 测试 1022 → **1010**（63 套件；删除 12 个死代码测试 + 新增 22 个 hooks/维护语句测试）；覆盖率 86.68% → 待发布后统计
|
||||
- README 补维护语句表（EXPLAIN/ANALYZE/REINDEX/VACUUM/SAVEPOINT SQL 入口）与 `db.backup()` API
|
||||
- 14 个生命周期钩子现在全部真实触发（site/docs.html 与 CONTRIBUTING 宣称变为事实）
|
||||
|
||||
---
|
||||
|
||||
## [0.5.0] - 2026-08-10
|
||||
|
||||
### 里程碑：存储后端生产级硬化（自研 OPFS 后端全面落地）
|
||||
|
||||
> 本次版本对 AriaEngine 存储层做全链路生产级改造：修复"宣称有校验和/加密/页面式存储但实际未实现"的失实实现，
|
||||
> WAL 重构为分片文件（消除多文件原子性与文件爆炸问题）、SSTable 页面化物理存储（BufferPool/FileManager 真正接入）、
|
||||
> 多标签页独占锁、repair 自愈增强，并引入真实 Chromium e2e 验证。
|
||||
|
||||
### Added
|
||||
|
||||
- **全库 AES-256-GCM 加密（真实接线）** — `AriaEngineConfig.encryption.password`：
|
||||
- `EncryptedBackend` 装饰器在 backend 层透明加解密（WAL/SSTable/Schema/元数据全覆盖，每个 value 独立随机 IV + GCM 认证）
|
||||
- PBKDF2-SHA256（100000 迭代）派生密钥，salt + verifier 持久化于 `__aria_keymeta`（密码错误 → `ARIA_DECRYPT_ERROR`）
|
||||
- 加密开关一致性检测：明文旧库 + 加密配置 → `ARIA_ENCRYPT_CONFIG_ERROR`；加密库 + 无密码 → `ARIA_ENCRYPT_REQUIRED`
|
||||
- clearAll 保留密钥元数据（库身份保留，密码不变）
|
||||
- **WAL 分片存储重构** — `SegmentedWALStore`（`__wal_%06d.bin`）：
|
||||
- 取代"每条记录一个 key"旧结构：分片阈值 4MB 自动切换，文件数量可控
|
||||
- WAL 序号（LSN）内嵌记录字节流，移除 `__wal_count` 键 → append 单文件原子写（createWritable COW）
|
||||
- 空洞检测：分片序号不连续 → 空洞之后保守丢弃（仅可能来自 truncate 部分完成，数据已落盘，无害）
|
||||
- 旧格式 `__wal_N` + `__wal_count` 兼容：读取迁移重放，checkpoint 统一清空
|
||||
- **OPFS 后端 v2** —
|
||||
- `append()` 真追加：`createWritable({ keepExistingData })` + seek，O(chunk) 无需读旧内容
|
||||
- 写队列健壮性：单次任务失败不中断队列链（错误返回给调用方），close 等待队列排空
|
||||
- open 自动清理崩溃残留临时文件（`.crswap`/`.tmp`）
|
||||
- 原子性文档化：单文件 createWritable 为 copy-on-write 原子替换
|
||||
- **SSTable 页面化物理存储（BufferPool/FileManager 真正接入）** —
|
||||
- `PageSSTableStore`：SSTable 切分为 4KB 页面，经 FileManager 分配 pageId、BufferPool LRU 缓存
|
||||
- `save` 语义 = 已持久化（逐页 flushPage 落盘后才返回，WAL checkpoint 截断安全）
|
||||
- 页面 ID 列表经 `SSTableMeta.pageIds` 持久化；旧 meta（无 pageIds）自动走整 value 读取（兼容）
|
||||
- OPFS 后端默认启用（`pageStorage` 配置可覆盖）；FileManager 批量分配 `allocatePageIds`（一次 meta 持久化）
|
||||
- 读取缺失页面返回 null（此前返回空页会静默掩盖页面丢失，自愈路径依赖 null 触发清理）
|
||||
- **多标签页独占锁** — Web Locks API（Chrome 69+ / Firefox 96+ / Safari 15.4+）：
|
||||
- `ifAvailable` 模式：第二个标签页打开同一库 → 抛 `ARIA_LOCKED`（不排队挂起）
|
||||
- 打开失败自动释放锁（不泄漏）；close 等待锁真正归还
|
||||
- 不支持 Web Locks 的环境降级为无锁 + 告警（如实文档化）
|
||||
- **repair() 自愈增强** — 孤儿页面清理（meta 未引用的 `pg_` 文件）、OPFS 残留临时文件清理、WAL 空洞截断落地
|
||||
- **LZ4 格式 v2** — 压缩流前置 4 字节原始大小头：解压不再依赖外部估算（高压缩率数据下 `buf.length*2` 估算不足会截断），损坏头显式抛错
|
||||
- **SSTable 真实 CRC-32 校验和** — footer checksum 字段从写死 0 升级为整文件标准 CRC32（checksum=0 识别旧版文件跳过校验，兼容旧库）；打开校验/compaction 加载/运行期预加载三处均校验，损坏文件自动清理自愈
|
||||
- **WAL 标准 CRC32** — 记录校验从弱滚动校验升级为标准 CRC32；双算法探测（新算法失败再试旧算法）兼容旧 WAL 记录
|
||||
- **配置透传** — `DatabaseConfig.aria`：`MetonaSqlark.create()` 可配置 `walSyncMode`/`checkpointInterval`/`encryption`/`pageStorage`/`compression` 等 AriaEngine 专属参数
|
||||
- **Playwright e2e（真实 Chromium + OPFS）** — 7 用例：持久化（刷新保留）、关闭重开、崩溃恢复（WAL 重放）、多标签页锁、加密密码往返、页面化端到端 + 索引查询、repair 自愈；`npm run test:e2e`
|
||||
|
||||
### Fixed
|
||||
|
||||
- **加密此前从未接线（严重失实）** — crypto 模块全局单例从未被引擎调用、salt 不持久化重启无法解密；README 宣称的 AES-GCM 实际不可用。改为 EncryptedBackend 装饰器 + keymeta 持久化 + 密码验证
|
||||
- **SSTable checksum 写死 0（严重失实）** — 数据腐坏（bit flip）完全无法检测。升级为真实 CRC-32，损坏文件打开自愈
|
||||
- **OPFS writeMany 无原子性（P0）** — WAL 记录 + count 多键写入非原子，记录空洞导致后续记录字节错位解析失败。分片重构后 WAL append 单文件原子写 + 空洞检测截断根治
|
||||
- **OPFS 高频写入文件爆炸（P1）** — 每条 WAL 记录一个文件，8 万条记录 = 8 万次 createWritable。分片存储 + 真追加根治
|
||||
- **LZ4 高压缩率解压截断（P1）** — `buf.length * 2` 估算原始大小，压缩率 >50% 时截断（SSTable 魔数在文件末尾被丢 → 整库数据丢失）。格式 v2 头部自描述根治
|
||||
- **OPFS 写队列失败永久中断（P1）** — 队列任务抛错后链 rejected，后续所有写挂起。单次失败不中断链
|
||||
- **OPFS close 不等挂起写（P1）** — close 立即置空目录句柄，挂起写静默丢失。close 等待队列排空
|
||||
- **Web Locks 方法解构 this 绑定丢失（e2e 发现）** — `navigator.locks.request` 解构后调用抛 Illegal invocation。改用 `.bind(lockManager)` 保持 this
|
||||
- **页面化 + 崩溃窗口数据丢失（压力测试发现）** — 修复前页面化路径在模拟崩溃测试中丢失已确认写入；根治后 500 随机操作 + 崩溃重放零丢失
|
||||
|
||||
### Changed
|
||||
|
||||
- `AriaEngineConfig` 新增 `encryption` / `pageStorage`；`DatabaseConfig` 新增 `aria` 透传
|
||||
- 页面层精简：删除从未接入主路径的 slot/tuple 模块（假"页面式存储"实现），仅保留生产代码实际使用的 `initPageHeader`/`createPage`；架构宣称如实更新（4KB 页面承载 SSTable 字节切片，非行级 Slotted Page）
|
||||
- LZ4 压缩格式不向后兼容（v0.2.6 已声明 compression 数据需重新导入，本次格式 v2 同理）
|
||||
- 测试 958 → **1022**（62 套件）；行覆盖率 84.2% → **86.68%**；新增 6 套件：crc32 / aria-checksum / aria-wal-crc / aria-wal-segment / aria-opfs-backend / aria-page-store / aria-encryption / aria-locks / aria-repair-hardening / aria-page-core
|
||||
- 新增 Playwright e2e 基建（`npm run test:e2e`，7 用例真实 Chromium）
|
||||
|
||||
---
|
||||
|
||||
## [0.4.4] - 2026-08-09
|
||||
|
||||
### Fixed
|
||||
|
||||
Reference in New Issue
Block a user