docs(canvas): explain import parsers, identities and integrity gates

This commit is contained in:
2026-11-12 00:31:08 +08:00
parent 68e655b52c
commit 72e84a6cc1
10 changed files with 150 additions and 0 deletions
@@ -1,29 +1,47 @@
/**
* 导出文档parser5:标准头先建立源树,随后每请求一项才延伸elements范围,实现先转换/加入/显示。
* 头乱序时明确回退索引解释器,再保留同一ordinal接口;不能因此声称所有文档都零预扫描。
* 范围扫描串行推进,已定位记录可独立重读;失败尾部成为明确错误记录,成功前缀不被回滚。
*/
import {readImportRange,isImportByteFailure,type ImportByteReader} from './import-byte-reader.ts';
import type {ImportLine,ImportSource} from './imports.ts';
import {createImportBudget,type ImportScheduling} from './import-budget.ts';
import {openDocumentImportSource} from './import-document.ts';
import {fault,validJson} from '../canvas-core/values.ts';
/** 已定位元素的原字节范围;只随请求积累,不在标准头准备时扫完整elements尾部。 */
type Range={start:number;end:number};
/** 单源共享byte缓存,仅减少重复读取;各scanner仍有自己的逻辑cursor。 */
type ScanCache={start:number;bytes:Uint8Array};
/** envelope内的轻量拥有树记录,不包含入口payload或renderer状态。 */
type Canvas={id:string;parent:null|{canvasId:string;entryElementId:string}};
/** 原源/指纹、可选已验证byte端口、取消与预算;指纹由上层完整性流程管理。 */
type Options=ImportScheduling&{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;signal:AbortSignal;maxRecordBytes?:number};
/** 明确支持的format1顶层字段,重复/未知字段拒绝,不隐式猜未来格式。 */
const allowed=new Set(['documentFormatVersion','projectId','canvases','elements','tombstones']);
/** JSON语法空白字节,不用于处理字符串内容。 */
const whitespace=(byte:number)=>byte===9||byte===10||byte===13||byte===32;
/** Each scan owns its cursor. An aborted scan cannot advance the resumable source. */
/** 每次扫描从指定位置建立私有cursor,完成边界后外层才更新可恢复源进度。 */
function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={start:-1,bytes:new Uint8Array()}){
const {bytes}=options,budget=createImportBudget(signal,options);
let cursor=start;
/** 在读取/采纳边界检查本次scanner的signal,缓存命中也不能跳过取消。 */
const check=()=>{if(signal.aborted)throw fault('import_aborted');};
/** 共享缓存不足时精确读16KiB,不推进私有cursor,EOF返回-1。 */
async function peek(){
check();if(cursor>=bytes.size)return -1;
if(cursor<cache.start||cursor>=cache.start+cache.bytes.length){const loaded=await readImportRange(bytes,options.readBytes,cursor,cursor+16384,signal);cache.start=cursor;cache.bytes=loaded;check();}
return cache.bytes[cursor-cache.start];
}
/** 推进一个字节并返回预算可能产生的让出Promise。 */
function step(){cursor++;return budget.step();}
/** 连续消费非字符串区的合法JSON空白。 */
async function spaces(){while(whitespace(await peek()))await step();}
/** 严格匹配一个结构字节,不修补缺逗号/冒号等源损坏。 */
async function take(byte:number){await spaces();if(await peek()!==byte)throw fault('invalid_document_import');await step();}
/** 引号/转义/栈配对扫描一个完整值range,限制嵌套深度,避免把字符串里的分隔符当边界。 */
async function value():Promise<Range>{
await spaces();const start=cursor,stack:number[]=[];let quoted=false,escaped=false;
while(true){
@@ -39,6 +57,7 @@ function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={sta
}
if(cursor===start)throw fault('invalid_document_import');return{start,end:cursor};
}
/** 对单range校验大小、fatal UTF8、JSON语法和值域,返回原值,不修改业务ID。 */
async function decode(range:Range,limit=options.maxRecordBytes??256*1024):Promise<any>{
check();if(range.end-range.start>limit)throw fault('record_too_large');
const data=await readImportRange(bytes,options.readBytes,range.start,range.end,signal);let text:string;
@@ -48,6 +67,7 @@ function scanner(options:Options,signal:AbortSignal,start=0,cache:ScanCache={sta
return{peek,step,spaces,take,value,decode,position:()=>cursor};
}
/** 仅验证envelope墓碑元数据为正安全整数表,目标导入仍使用新ID/新生命周期。 */
function tombstones(value:unknown){
if(!value||typeof value!=='object'||Array.isArray(value)||Object.values(value).some(n=>!Number.isSafeInteger(n)||(n as number)<1))throw fault('invalid_document_import');
}
@@ -55,6 +75,7 @@ function tombstones(value:unknown){
/** Parser 5: canonical headers open before scanning the elements tail.
* Out-of-order headers require the indexed interpreter to establish ownership first.
* Ordinals remain stable; ranges are retained only as records are requested. */
/** 打开standard header后即可返回源;真正elements/tail结构检查跟随read进行,未扫描尾部不冒称合法。 */
export async function openStreamingDocumentImportSource(input:Options):Promise<ImportSource>{
const options:Options=Object.freeze({...input});
const {bytes,signal}=options,max=options.maxRecordBytes??256*1024;
@@ -68,6 +89,7 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
const key=await header.decode(await header.value(),1024);
if(typeof key!=='string'||!allowed.has(key)||fields.has(key))throw fault('invalid_document_import');
await header.take(58);
// 必需format/project/canvases还没出现则不能安全解释owner,回退全envelope索引而非猜测。
if(key==='elements'){
if(!fields.has('documentFormatVersion')||!fields.has('projectId')||!fields.has('canvases')){
const indexed=await openDocumentImportSource(options);
@@ -86,6 +108,7 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
if(!canvas||typeof canvas.id!=='string'||!canvas.id||byId.has(canvas.id)||canvas.parent!==null&&(!canvas.parent||typeof canvas.parent.canvasId!=='string'||typeof canvas.parent.entryElementId!=='string'))throw fault('invalid_document_import');
byId.set(canvas.id,canvas);await budget.step();
}
// 验证单根和父链,rooted缓存已经验证的路径,减少深树中重复回溯工作。
const roots=canvases.filter(canvas=>canvas.parent===null);if(roots.length!==1)throw fault('invalid_document_import');
const rootId=roots[0].id,rooted=new Set([rootId]);
for(const canvas of canvases){
@@ -97,7 +120,9 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
for(const id of path){rooted.add(id);await budget.step();}
}
const children=canvases.filter(canvas=>canvas.id!==rootId),ranges:Range[]=[];
// 源级进度只记录完整range边界/phase,serial只串行化延伸;failure最多输出一条终结错误。
let cursor=header.position(),phase:'elements'|'tail'|'done'='elements',first=true,failure:string|undefined,serial=Promise.resolve();
/** 延伸一个element range,或验证剩余envelope与EOF;只在结构边界确认后更新cursor/phase。 */
async function scanNext(readSignal:AbortSignal){
const scan=scanAt(readSignal,cursor);
if(phase==='elements'){
@@ -109,6 +134,7 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
await scan.step();cursor=scan.position();phase=delimiter===93?'tail':'elements';first=false;ranges.push(range);return;
}
}
// elements结束后仍检查顶层重复/未知字段、可选tombstones与实际EOF,不能略过坏尾部。
const seen=new Set(fields.keys());await scan.spaces();
while(await scan.peek()!==125){
await scan.take(44);const key=await scan.decode(await scan.value(),1024);
@@ -120,14 +146,17 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
await scan.take(125);await scan.spaces();if(scan.position()!==bytes.size)throw fault('invalid_document_import');
cursor=scan.position();phase='done';
}
/** ordinal read:子canvas直接返回,元素按需scan定位;已定位范围逐记录解码,后续恢复可重读。 */
async function read(position:number,readSignal:AbortSignal):Promise<ImportLine|null>{
if(readSignal.aborted)throw fault('import_aborted');
if(!Number.isSafeInteger(position)||position<0)throw fault('invalid_import_cursor');
const elementIndex=position-children.length;
// 未定位位置才推进源扫描;取消/byte证据错误抛出,其它结构失败转成尾部error记录。
while(elementIndex>=ranges.length&&phase!=='done'){
try{await scanNext(readSignal);}catch(error){if(readSignal.aborted)throw fault('import_aborted');if(isImportByteFailure(error))throw error;failure=(error as {code?:string}).code??'invalid_document_import';phase='done';}
}
const count=children.length+ranges.length;
// 失败点恰好返回一条可报告记录,下一ordinal为EOF,不能吞掉错误而宣称正常结束。
if(position>=count){
if(failure&&position===count)return{cursor:position,nextCursor:position+1,key:`record:${position}`,error:failure};
if(position===count+(failure?1:0))return null;
@@ -140,6 +169,7 @@ export async function openStreamingDocumentImportSource(input:Options):Promise<I
return{...base,value:{kind,key:record.id,record,sourceRootId:rootId}};
}catch(error){if(readSignal.aborted)throw fault('import_aborted');if(isImportByteFailure(error))throw error;return{...base,error:(error as {code?:string}).code??'invalid_document_import'};}
}
/** 已定位record的重读不等未来scan的锁;仅扩张ranges通过serial排队,失败不会毒化后续Promise链。 */
return Object.freeze({fingerprint:options.fingerprint,parserVersion:5,read(position:number,readSignal:AbortSignal){
// A slow future scan must not block re-reading a pending unit for commit/recovery.
if(position<children.length+ranges.length)return read(position,readSignal);