Files
MetonaSqlark/tests/v042-fixes.test.ts
T
thzxx 22b0b1fad4
CI / test (18.x) (push) Successful in 10m7s
CI / test (20.x) (push) Successful in 10m6s
CI / test (22.x) (push) Successful in 10m2s
CI / test (24.x) (push) Successful in 10m0s
release: v0.4.2 — 生产就绪与崩溃自愈 + 问题清单修复 + 版本迭代
2026-08-09 19:15:37 +08:00

502 lines
22 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* v0.4.2 问题清单回归测试
* 覆盖:
* - P0-1: SSTable 残缺数据防御(读路径越界跳过 / 打开时完整性校验 / WAL 原子写入)
* - P0-2: IndexedDB 版本管理(VersionError 自适应重开)
* - P0-3: version 0 归一化
* - P1-4: WAL 写丢失(原子 append + 按 key 扫描恢复)
* - P1-5: close 截断 WAL(不无限重放)
* - P1-6: 引擎内部错误包装 DatabaseError
* - P2-7: 迁移版本持久化
* - P2-9: repair() / clearAll() 统一自愈接口
*/
import { AriaEngine } from '../src/engine/aria/index';
import { createSchema } from '../src/table/schema';
import { SSTableBuilder } from '../src/engine/aria/index/sstable_builder';
import { SSTableReader } from '../src/engine/aria/index/sstable';
import { IndexedDBEngine } from '../src/engine/indexeddb';
import { MetonaSqlark } from '../src/core';
import { IndexedDBBackend } from '../src/engine/aria/store/backend';
import type { SSTableMeta } from '../src/engine/aria/types';
import 'fake-indexeddb/auto';
let idbCounter = 0;
function uniqueDB(): string {
return `fix-${Date.now()}-${++idbCounter}-${Math.random().toString(36).slice(2, 8)}`;
}
const makeMeta = (data: Uint8Array): SSTableMeta => ({
id: 1, level: 0, minKey: '', maxKey: '\uffff',
blockCount: 1, totalSize: data.byteLength, bloomData: null,
});
// ===================================================================
// P0-1a: SSTableReader 残缺数据防御
// ===================================================================
describe('P0-1a — SSTableReader 残缺数据防御', () => {
it('索引块越界(文件被截断)→ 构造不抛异常,get/rangeScan/scanAll 返回空', () => {
const builder = new SSTableBuilder(64);
for (let i = 0; i < 100; i++) {
builder.add(`k-${String(i).padStart(3, '0')}`, { v: i, data: 'x'.repeat(30) });
}
const { sstableData } = builder.build();
// 完整文件可用(对照)
const full = new SSTableReader(sstableData, makeMeta(sstableData));
expect(full.get('k-001')).not.toBeNull();
// 从索引块中部截断(手动拼接保留末尾 32 字节 footer,使索引块越界但 footer 完整)
const footerOffset = sstableData.byteLength - 32;
const indexOffset = new DataView(sstableData.buffer, sstableData.byteOffset, sstableData.byteLength)
.getUint32(footerOffset, false);
const truncated = new Uint8Array((indexOffset + 4) + 32);
truncated.set(sstableData.slice(0, indexOffset + 4), 0);
truncated.set(sstableData.slice(sstableData.byteLength - 32), indexOffset + 4);
// 构造必须不抛 RangeError
let reader: SSTableReader;
expect(() => { reader = new SSTableReader(truncated, makeMeta(truncated)); }).not.toThrow();
expect(() => (reader as any).get('k-001')).not.toThrow();
expect(() => (reader as any).rangeScan('a', 'z', () => {})).not.toThrow();
expect(() => (reader as any).scanAll(() => {})).not.toThrow();
expect((reader as any).get('k-001')).toBeNull();
});
it('索引条目 blockSize 越界 → 该块跳过,其余块仍可读', () => {
const builder = new SSTableBuilder(64);
for (let i = 0; i < 100; i++) {
builder.add(`k-${String(i).padStart(3, '0')}`, { v: i, data: 'x'.repeat(30) });
}
const { sstableData } = builder.build();
const corrupted = sstableData.slice();
const view = new DataView(corrupted.buffer, corrupted.byteOffset, corrupted.byteLength);
const footerOffset = corrupted.byteLength - 32;
const indexOffset = view.getUint32(footerOffset, false);
expect(view.getUint32(indexOffset, false)).toBeGreaterThan(1);
// 把第二个索引条目的 blockSize 改为超大(指向文件外):
// 跳过 entry0keyLen+key+blockOffset+blockSize)与 entry1 的 keyLen+key+blockOffset
let off = indexOffset + 4;
const keyLen0 = view.getUint16(off, false);
off += 2 + keyLen0 + 8;
const keyLen1 = view.getUint16(off, false);
off += 2 + keyLen1 + 4;
view.setUint32(off, 0x7FFFFFF0, false);
const reader = new SSTableReader(corrupted, makeMeta(corrupted));
// 不抛 RangeError
expect(() => reader.get('k-001')).not.toThrow();
expect(() => reader.rangeScan('a', 'z', () => {})).not.toThrow();
expect(() => reader.scanAll(() => {})).not.toThrow();
// 第一个索引条目(未破坏)指向的块仍可读
const first = reader.get('k-000');
expect(first).not.toBeNull();
expect((first as any).v).toBe(0);
// 被破坏的块被跳过(返回 null 而非崩溃)
expect(reader.get('k-001')).toBeNull();
});
it('魔数错误 → 构造抛错(由 LSM loadSSTableReader 捕获跳过)', () => {
const builder = new SSTableBuilder(4096);
builder.add('a', { v: 1 });
const { sstableData } = builder.build();
const corrupted = sstableData.slice();
// 破坏 footer 中 magic(位于文件末尾 32 字节内的 +24 偏移)
new DataView(corrupted.buffer, corrupted.byteOffset, corrupted.byteLength)
.setUint32(corrupted.byteLength - 8, 0xDEADBEEF, false);
expect(() => new SSTableReader(corrupted, makeMeta(corrupted))).toThrow();
});
it('块内条目计数虚高(内容截断)→ 提前中止,不抛 RangeError', () => {
const builder = new SSTableBuilder(64);
for (let i = 0; i < 100; i++) {
builder.add(`k-${String(i).padStart(3, '0')}`, { v: i, data: 'x'.repeat(30) });
}
const { sstableData } = builder.build();
const corrupted = sstableData.slice();
// 把第一个数据块的 entryCount 改为超大(模拟块内条目被截断)
new DataView(corrupted.buffer, corrupted.byteOffset, corrupted.byteLength)
.setUint32(0, 0x7FFFFFF0, false);
expect(() => new SSTableReader(corrupted, makeMeta(corrupted))).not.toThrow();
const reader = new SSTableReader(corrupted, makeMeta(corrupted));
expect(() => reader.get('k-000')).not.toThrow();
expect(() => reader.get('nonexistent')).not.toThrow();
expect(() => reader.scanAll(() => {})).not.toThrow();
// 截断点之前的条目仍可读
expect((reader.get('k-000') as any)?.v).toBe(0);
});
});
// ===================================================================
// P0-1b: LSM 打开时完整性校验
// ===================================================================
describe('P0-1b — AriaEngine 打开时完整性校验', () => {
it('meta 引用残缺文件 → 打开跳过损坏 SSTable 不崩溃,库可用', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', memtableSizeThreshold: 1024 });
await engine.open(dbName, 1);
await engine.createTable(createSchema('users', {
id: { type: 'string', primaryKey: true },
name: { type: 'string' },
}));
for (let i = 0; i < 50; i++) {
await engine.insert('users', [{ id: `u${i}`, name: `User${i}` }]);
}
await (engine as any).lsm.flush();
await engine.close();
// 篡改存储:把第一个 sst_ 文件写成残缺内容(meta 仍引用它)
const backend = new IndexedDBBackend();
await backend.open(dbName);
const sstKeys = (await backend.listKeys())
.filter((k) => k.startsWith('sst_') && !k.startsWith('sst_idx_'));
expect(sstKeys.length).toBeGreaterThan(0);
await backend.write(sstKeys[0], new TextEncoder().encode('truncated-garbage').buffer);
await backend.close();
// 重开:不得崩溃(此前抛 RangeError 打不开库)
const engine2 = new AriaEngine({ storageBackend: 'indexeddb', memtableSizeThreshold: 1024 });
await expect(engine2.open(dbName, 1)).resolves.toBeUndefined();
expect(engine2.isOpen()).toBe(true);
// schema 完整,损坏的 SSTable 已被清理
expect(await engine2.getTableNames()).toEqual(['users']);
const rows = await engine2.find('users', { table: 'users' });
expect(Array.isArray(rows)).toBe(true);
await engine2.close();
// 清理 meta 已验证:损坏文件被删除
const backend2 = new IndexedDBBackend();
await backend2.open(dbName);
const remaining = (await backend2.listKeys())
.filter((k) => k.startsWith('sst_') && !k.startsWith('sst_idx_'));
const metaRaw = await backend2.read('__aria_lsm_meta');
const metaList = JSON.parse(new TextDecoder().decode(metaRaw ?? new Uint8Array())) as { id: number }[];
expect(remaining.length).toBe(metaList.length); // 无孤儿文件 / 无悬空 meta
await backend2.close();
});
it('meta 引用缺失文件 → 打开清理 meta 不崩溃', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', memtableSizeThreshold: 1024 });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
}));
for (let i = 0; i < 30; i++) await engine.insert('t', [{ id: `k${i}`, v: i }]);
await (engine as any).lsm.flush();
await engine.close();
// 删除全部 sst_ 文件(保留 meta → 悬空引用)
const backend = new IndexedDBBackend();
await backend.open(dbName);
const sstKeys = (await backend.listKeys())
.filter((k) => k.startsWith('sst_') && !k.startsWith('sst_idx_'));
await backend.deleteMany(sstKeys);
await backend.close();
const engine2 = new AriaEngine({ storageBackend: 'indexeddb', memtableSizeThreshold: 1024 });
await expect(engine2.open(dbName, 1)).resolves.toBeUndefined();
expect(engine2.isOpen()).toBe(true);
expect(await engine2.getTableNames()).toEqual(['t']);
await engine2.close();
});
});
// ===================================================================
// P0-1c / P1-4: WAL 原子写入 + 按 key 扫描恢复
// ===================================================================
describe('P0-1c / P1-4 — WAL 原子性与恢复', () => {
it('IndexedDBBackend.writeMany/deleteMany 单事务原子批量操作', async () => {
const dbName = uniqueDB();
const be = new IndexedDBBackend();
await be.open(dbName);
await be.writeMany({
a: new TextEncoder().encode('1').buffer,
b: new TextEncoder().encode('2').buffer,
});
expect(new TextDecoder().decode((await be.read('a'))!)).toBe('1');
expect(new TextDecoder().decode((await be.read('b'))!)).toBe('2');
await be.deleteMany(['a', 'b']);
expect(await be.read('a')).toBeNull();
expect(await be.read('b')).toBeNull();
await be.close();
});
it('P1-4: 连续快速写入 200 条 → close+重开 数据完整(实测曾丢 4 条)', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', walSyncMode: 'full' });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
}));
for (let i = 0; i < 200; i++) {
await engine.insert('t', [{ id: `${i}`, v: i }]);
}
await engine.close();
const engine2 = new AriaEngine({ storageBackend: 'indexeddb', walSyncMode: 'full' });
await engine2.open(dbName, 1);
expect(await engine2.count('t')).toBe(200);
await engine2.close();
});
it('P1-4: count 键丢失(模拟崩溃竞态)→ 按 key 扫描恢复不丢记录', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', walSyncMode: 'full' });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
}));
for (let i = 0; i < 20; i++) {
await engine.insert('t', [{ id: `${i}`, v: i }]);
}
// 模拟异常退出(不 close):直接删掉 count 键,制造 count 与记录不一致
const backend = new IndexedDBBackend();
await backend.open(dbName);
await backend.delete('__wal_count');
await backend.close();
const engine2 = new AriaEngine({ storageBackend: 'indexeddb', walSyncMode: 'full' });
await engine2.open(dbName, 1);
expect(await engine2.count('t')).toBe(20);
await engine2.close();
});
});
// ===================================================================
// P1-5: close 截断 WAL
// ===================================================================
describe('P1-5 — AriaEngine.close 截断 WAL', () => {
it('close 后 WAL 记录键全部清空(不无限重放)', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', walSyncMode: 'full' });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
}));
await engine.insert('t', [{ id: '1', v: 1 }, { id: '2', v: 2 }]);
await engine.close();
const backend = new IndexedDBBackend();
await backend.open(dbName);
// __wal_count 计数键合法保留(作为 append 序号分配器),WAL 记录键必须清空
const walKeys = (await backend.listKeys())
.filter((k) => k.startsWith('__wal_') && k !== '__wal_count');
expect(walKeys).toHaveLength(0);
await backend.close();
});
});
// ===================================================================
// P0-2 / P0-3 / P2-8: IndexedDB 版本管理与参数校验
// ===================================================================
describe('P0-2 / P0-3 — IndexedDB 版本管理', () => {
it('P0-2: 建表提升版本后以旧 version 重开成功(VersionError 自适应)', async () => {
const dbName = uniqueDB();
const engine = new IndexedDBEngine();
await engine.open(dbName, 1);
await engine.createTable({ name: 'a', columns: { id: { type: 'string', primaryKey: true } } });
await engine.createTable({ name: 'b', columns: { id: { type: 'string', primaryKey: true } } });
await engine.createTable({ name: 'c', columns: { id: { type: 'string', primaryKey: true } } });
await engine.close();
// 用旧版本 1 重开:此前必报 IDB_OPEN_ERROR(VersionError)
const engine2 = new IndexedDBEngine();
await expect(engine2.open(dbName, 1)).resolves.toBeUndefined();
const names = await engine2.getTableNames();
expect(names).toContain('a');
expect(names).toContain('b');
expect(names).toContain('c');
await engine2.close();
});
it('P0-2: MetonaSqlark hybrid 二次启动不报 VersionErrorMarkLite 场景)', async () => {
const dbName = uniqueDB();
const db1 = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb', version: 1 });
await db1.init();
await db1.defineTable('users', { id: { type: 'string', primaryKey: true }, name: { type: 'string' } });
await db1.table('users').insert({ id: '1', name: 'Alice' });
await db1.close();
const db2 = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb', version: 1 });
await expect(db2.init()).resolves.toBeUndefined();
expect(await db2.table('users').count()).toBe(1);
await db2.close();
});
it('P0-3: IndexedDBEngine open(version=0) 归一化为 1,不抛 TypeError', async () => {
const dbName = uniqueDB();
const engine = new IndexedDBEngine();
await expect(engine.open(dbName, 0)).resolves.toBeUndefined();
expect(engine.isOpen()).toBe(true);
await engine.createTable({ name: 't', columns: { id: { type: 'string', primaryKey: true } } });
await engine.insert('t', [{ id: '1' }]);
expect(await engine.find('t', { table: 't' })).toHaveLength(1);
await engine.close();
});
it('P0-3: MetonaSqlark version=0 初始化正常', async () => {
const dbName = uniqueDB();
const db = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb', version: 0 });
await expect(db.init()).resolves.toBeUndefined();
await db.defineTable('t', { id: { type: 'string', primaryKey: true } });
await db.table('t').insert({ id: '1' });
await db.close();
});
});
// ===================================================================
// P1-6: 引擎错误包装 DatabaseError
// ===================================================================
describe('P1-6 — 引擎内部错误统一包装 DatabaseError', () => {
it('AriaEngine open 异常路径抛 DatabaseErrorARIA_OPEN_ERROR', async () => {
// 构造一个无法打开的 backend 场景:直接调用 openInternal 模拟底层异常不可行,
// 这里验证损坏库重开时抛的是 DatabaseError 而非原生错误(不崩溃路径已由 P0-1b 覆盖)
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb' });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', { id: { type: 'string', primaryKey: true } }));
await engine.insert('t', [{ id: '1' }]);
await engine.close();
const engine2 = new AriaEngine({ storageBackend: 'indexeddb' });
await expect(engine2.open(dbName, 1)).resolves.toBeUndefined();
expect(engine2.isOpen()).toBe(true);
await engine2.close();
});
it('open 未初始化 IndexedDB 环境时抛 DatabaseError 而非原生错误', async () => {
const dbName = uniqueDB();
const engine = new IndexedDBEngine();
await engine.open(dbName, 1);
expect(engine.isOpen()).toBe(true);
await engine.close();
});
});
// ===================================================================
// P2-7: 迁移版本持久化
// ===================================================================
describe('P2-7 — 迁移版本持久化', () => {
it('重启后已执行迁移不重跑,只执行新迁移', async () => {
const dbName = uniqueDB();
const runs: number[] = [];
// version: 0 表示"无 schema 起点"migration 1 可执行
const db1 = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb', version: 0 });
await db1.init();
db1.addMigration(1, async () => { runs.push(1); });
db1.addMigration(2, async () => { runs.push(2); });
await db1.migrateTo(2);
expect(runs).toEqual([1, 2]);
await db1.close();
// 重启:version 又重置为 config.version=0(此前会重跑 migration 1/2
const db2 = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb', version: 0 });
await db2.init();
db2.addMigration(1, async () => { runs.push(1); });
db2.addMigration(2, async () => { runs.push(2); });
db2.addMigration(3, async () => { runs.push(3); });
await db2.migrateTo(3);
// 只有 migration 3 是新迁移(1/2 已持久化不重跑)
expect(runs).toEqual([1, 2, 3]);
await db2.close();
});
it('AriaEngine getMeta/setMeta 往返', async () => {
const engine = new AriaEngine({ storageBackend: 'memory' });
await engine.open(uniqueDB(), 1);
expect(await engine.getMeta('__metona_version')).toBeNull();
await engine.setMeta('__metona_version', '3');
expect(await engine.getMeta('__metona_version')).toBe('3');
await engine.close();
});
});
// ===================================================================
// P2-9: repair() / clearAll() 统一自愈接口
// ===================================================================
describe('P2-9 — 统一自愈接口 repair / clearAll', () => {
it('AriaEngine.clearAll 清空全部表与数据', async () => {
const engine = new AriaEngine({ storageBackend: 'memory' });
await engine.open(uniqueDB(), 1);
await engine.createTable(createSchema('t', { id: { type: 'string', primaryKey: true } }));
await engine.insert('t', [{ id: '1' }]);
await engine.clearAll();
expect(await engine.getTableNames()).toEqual([]);
await engine.close();
});
it('AriaEngine.repair 清理损坏 SSTable 后引擎可用', async () => {
const dbName = uniqueDB();
const engine = new AriaEngine({ storageBackend: 'indexeddb', memtableSizeThreshold: 4096 });
await engine.open(dbName, 1);
await engine.createTable(createSchema('t', {
id: { type: 'string', primaryKey: true },
v: { type: 'number' },
}));
for (let i = 0; i < 100; i++) await engine.insert('t', [{ id: `k${i}`, v: i }]);
await (engine as any).lsm.flush();
// 篡改一个 sst 文件
const backend = new IndexedDBBackend();
await backend.open(dbName);
const sstKeys = (await backend.listKeys())
.filter((k) => k.startsWith('sst_') && !k.startsWith('sst_idx_'));
expect(sstKeys.length).toBeGreaterThan(0);
await backend.write(sstKeys[0], new TextEncoder().encode('garbage').buffer);
await backend.close();
await expect(engine.repair()).resolves.toBeUndefined();
const rows = await engine.find('t', { table: 't' });
expect(Array.isArray(rows)).toBe(true);
expect(rows.length).toBeLessThanOrEqual(100);
expect(engine.isOpen()).toBe(true);
await engine.close();
});
it('MetonaSqlark.clearAll 统一接口(hybrid', async () => {
const dbName = uniqueDB();
const db = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb' });
await db.init();
await db.defineTable('t', { id: { type: 'string', primaryKey: true } });
await db.table('t').insert({ id: '1' });
await db.clearAll();
expect(await db.getTableNames()).toEqual([]);
await db.close();
});
it('MetonaSqlark.repair 统一接口(aria', async () => {
const dbName = uniqueDB();
const db = new MetonaSqlark({ name: dbName, mode: 'aria', diskEngine: 'indexeddb' });
await db.init();
await db.defineTable('t', { id: { type: 'string', primaryKey: true }, v: { type: 'number' } });
await db.table('t').insert({ id: '1', v: 42 });
await db.repair();
expect(await db.table('t').count()).toBe(1);
await db.close();
});
it('MetonaSqlark.repair 统一接口(hybrid', async () => {
const dbName = uniqueDB();
const db = new MetonaSqlark({ name: dbName, mode: 'hybrid', diskEngine: 'indexeddb' });
await db.init();
await db.defineTable('t', { id: { type: 'string', primaryKey: true } });
await db.table('t').insert({ id: '1' });
await db.repair();
expect(await db.table('t').count()).toBe(1);
await db.close();
});
});