docs(tests): explain streaming import cursors and read-proof lifecycle

This commit is contained in:
2026-11-12 17:25:23 +08:00
parent 225170b024
commit 7ed36b1ae0
7 changed files with 15 additions and 2 deletions
@@ -22,6 +22,8 @@ test('canonical document opens and emits its first record without reading the ga
const bytes=new Source([JSON.stringify({...header,elements:[{id:'first'},{id:'second',text:'x'.repeat(100000)}],tombstones:{}})]),reader=await open(bytes);
assert.equal(reader.parserVersion,5);assert.equal(reads.some(([start])=>start>=32768),false);
assert.equal((await reader.read(0,signal())).value.record.id,'first');assert.equal(reads.some(([start])=>start>=32768),false);
// read(1) 挂在未来切片;同时重读缓存序号 0,并用 500ms 上限捕获串行锁误阻塞。
// finally 无论重读是否成功都取消挂起调用并释放 gate,随后检查原调用拒绝且同序号可重新扫描。
const controller=new AbortController(),pending=reader.read(1,controller.signal);await entered.promise;let timer;try{const repeated=await Promise.race([reader.read(0,signal()),new Promise((_,reject)=>timer=setTimeout(()=>reject(Error('a blocked future scan prevented re-reading a ready record')),500))]);assert.equal(repeated.value.record.id,'first');}finally{clearTimeout(timer);controller.abort();block=false;gate.resolve();}await assert.rejects(pending,/import_aborted/);
assert.equal((await reader.read(1,signal())).value.record.id,'second');assert.equal(await reader.read(2,signal()),null);
});
@@ -33,6 +35,7 @@ test('reopening and concurrent reads keep stable canvas-first ordinals and origi
});
// 非法墓碑、垃圾、重复字段、未知尾字段及尾逗号不撤回合法元素,只追加一条可推进游标的错误后结束。
// 先读两个合法序号,再断言错误 nextCursor=3、下一次为 null,区分可恢复 I/O 拒绝和终态格式错误。
test('bad envelope tails preserve legal records and become one explicit terminal failure',async()=>{
for(const suffix of [',"tombstones":{"bad":0}}','} trailing',',"elements":[]}',',"unknown":true}',',}']){
const reader=await open(JSON.stringify({...header,elements:[{id:'first'},{id:'last'}]}).slice(0,-1)+suffix);