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
+19
View File
@@ -1,26 +1,41 @@
/**
* 完整导出文档的索引解释器(parserVersion=4),用于旧任务和头字段乱序等回退路径。
* 准备阶段扫描O(bytes)并保留O(records)字节range,不解码全部元素payload,但并非常数内存/零预扫描。
* 生成ordinal记录流:先子canvas后元素;源根映到目标,不把旧ID/墓碑直接带入目标生命周期。
*/
import {readImportRange,isImportByteFailure,type ImportByteReader} from './import-byte-reader.ts';
import {createImportBudget,type ImportScheduling} from './import-budget.ts';
import type {ImportSource,ImportLine} from './imports.ts';
import {fault,validJson} from '../canvas-core/values.ts';
/** 一条JSON值的原始[start,end)字节范围,源Blob仍是权威数据,不保存另一份payload副本。 */
type Range={start:number;end:number};
/** Index the envelope without decoding element payloads. Original bytes remain the source.
* Preparation scans O(bytes) and retains O(records) ranges; this is not constant memory. */
/** 在64MiB源上索引envelope/记录范围,验证头与树后返回可按ordinal重读的ImportSource。 */
export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:string;readBytes?:ImportByteReader;signal:AbortSignal;maxRecordBytes?:number}&ImportScheduling):Promise<ImportSource>{
const {bytes,signal}=options,max=options.maxRecordBytes??256*1024;
if(!(bytes instanceof Blob)||bytes.size>64*1024*1024||!options.fingerprint||!Number.isSafeInteger(max)||max<1)throw fault('invalid_import_source');
let cursor=0,cache={start:-1,bytes:new Uint8Array()};const budget=createImportBudget(signal,options);
/** JSON合法语法空白判定;不在这里做文本编码猜测或容错清洗。 */
const space=(b:number)=>[9,10,13,32].includes(b);
/** 16KiB分块缓存读取,异步边界检查signal,EOF用-1表示。 */
async function peek(){if(signal.aborted)throw fault('import_aborted');if(cursor>=bytes.size)return -1;if(cursor<cache.start||cursor>=cache.start+cache.bytes.length){cache={start:cursor,bytes:await readImportRange(bytes,options.readBytes,cursor,cursor+16384,signal)};if(signal.aborted)throw fault('import_aborted');}return cache.bytes[cursor-cache.start];}
/** 推进扫描cursor并按预算计工作量;单原生JSON.parse仍由大小上限约束。 */
function step(){cursor++;return budget.step();}
/** 跳过值/分隔符之间空白,保持range不含前导空白。 */
async function spaces(){while(space(await peek()))await step();}
/** 在跳空白后严格消费预期结构字节,错位立即拒绝,不猜字段/格式。 */
async function take(byte:number){await spaces();if(await peek()!==byte)throw fault('invalid_document_import');await step();}
/** 只定位一个值的范围,跟踪引号/转义/容器配对,扫描嵌套上限256;真正JSON解析稍后做。 */
async function value():Promise<Range>{await spaces();const start=cursor,stack:number[]=[];let quoted=false,escaped=false;
while(true){const b=await peek();if(b<0){if(quoted||stack.length)throw fault('invalid_document_import');break;}if(!quoted&&!stack.length&&(b===44||b===93||b===125||space(b)))break;
if(quoted){if(escaped)escaped=false;else if(b===92)escaped=true;else if(b===34)quoted=false;}else if(b===34)quoted=true;else if(b===91||b===123){stack.push(b);if(stack.length>256)throw fault('json_nesting_limit');}else if(b===93||b===125){if(stack.pop()!==(b===93?91:123))throw fault('invalid_document_import');}
const ended=!quoted&&stack.length===0&&(b===34||b===93||b===125);await step();if(ended)break;
}if(cursor===start)throw fault('invalid_document_import');return{start,end:cursor};
}
/** 对限定range执行fatal UTF8和JSON值域校验;key/元数据/记录可使用不同字节上限。 */
async function decode(range:Range,limit=max,readSignal=signal){if(range.end-range.start>limit)throw fault('record_too_large');const data=await readImportRange(bytes,options.readBytes,range.start,range.end,readSignal);let text:string;try{text=new TextDecoder('utf-8',{fatal:true}).decode(data);}catch{throw fault('invalid_utf8');}try{const result=JSON.parse(text);if(!validJson(result))throw Error();return result;}catch{throw fault('invalid_json');}}
// envelope字段名去重;elements仅保留ranges,其它字段按有限metadata大小解码。
const fields=new Map<string,unknown>(),elements:Range[]=[];
await take(123);await spaces();if(await peek()===125)throw fault('invalid_document_import');
while(true){const key=await decode(await value(),1024);if(typeof key!=='string'||fields.has(key))throw fault('invalid_document_import');await take(58);
@@ -28,17 +43,21 @@ export async function openDocumentImportSource(options:{bytes:Blob;fingerprint:s
else fields.set(key,await decode(await value(),4*1024*1024));
await spaces();if(await peek()===125){await step();break;}await take(44);
}
// 只支持显式format1与已知顶层字段,未知envelope不能偷偷当一组普通记录导入。
await spaces();if(cursor!==bytes.size||fields.get('documentFormatVersion')!==1||typeof fields.get('projectId')!=='string'||!fields.get('projectId')||!Array.isArray(fields.get('canvases'))||!fields.has('elements')||[...fields.keys()].some(key=>!['documentFormatVersion','projectId','canvases','elements','tombstones'].includes(key)))throw fault('invalid_document_import');
const canvases=fields.get('canvases') as {id:string;parent:null|{canvasId:string;entryElementId:string}}[],ids=new Set<string>();
for(const canvas of canvases){if(!canvas||typeof canvas.id!=='string'||!canvas.id||ids.has(canvas.id)||canvas.parent!==null&&(!canvas.parent||typeof canvas.parent.canvasId!=='string'||typeof canvas.parent.entryElementId!=='string'))throw fault('invalid_document_import');ids.add(canvas.id);}
const roots=canvases.filter(canvas=>canvas.parent===null);if(roots.length!==1)throw fault('invalid_document_import');const rootId=roots[0].id;
// parent链必须存在且无环;入口实际节点/引用闭合仍由后续原生转换与文档校验完成。
const byId=new Map(canvases.map(canvas=>[canvas.id,canvas]));
for(const canvas of canvases){const seen=new Set<string>();let current=canvas;while(current.parent){if(seen.has(current.id))throw fault('invalid_document_import');seen.add(current.id);await budget.step();const parent=byId.get(current.parent.canvasId);if(!parent)throw fault('invalid_document_import');current=parent;}}
const tombstones=fields.get('tombstones');if(tombstones!==undefined&&(!tombstones||typeof tombstones!=='object'||Array.isArray(tombstones)||Object.values(tombstones).some(n=>!Number.isSafeInteger(n)||(n as number)<1)))throw fault('invalid_document_import');
// 排除源根canvas,按固定ordinal拼接子canvas与元素;恢复cursor不是原Blob字节偏移。
const children=canvases.filter(canvas=>canvas.id!==rootId),count=children.length+elements.length;
return Object.freeze({fingerprint:options.fingerprint,parserVersion:4,async read(position:number,readSignal:AbortSignal):Promise<ImportLine|null>{
if(readSignal.aborted)throw fault('import_aborted');if(!Number.isSafeInteger(position)||position<0||position>count)throw fault('invalid_import_cursor');if(position===count)return null;
const base={cursor:position,nextCursor:position+1,key:`record:${position}`};let record:any,kind:string;
// 单记录payload失败返回error/next ordinal,保留后续合法记录;源级字节失败和取消仍抛出。
try{if(position<children.length){kind='canvas';record=children[position];}else{kind='element';record=await decode(elements[position-children.length],max,readSignal);}if(readSignal.aborted)throw fault('import_aborted');if(!record||typeof record!=='object'||Array.isArray(record)||typeof record.id!=='string'||!record.id)throw fault('invalid_native_import_record');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'};}
}});
}