docs(canvas): explain import execution and lazy copy source recovery
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
/**
|
||||
* 格式1的完整复制源快照与复制声明签名。源字节在任务准入前从一个不可变文档捕获,
|
||||
* 后续规划/重开不读取当前用户正在改的live文档;源SHA与持久字节由外层完整性流程绑定。
|
||||
*/
|
||||
import type { CanvasRecord, Document, ElementRecord, Registry } from '../canvas-core/types.ts';
|
||||
import { createDocument, validateDocumentSteps } from '../canvas-core/document.ts';
|
||||
import { fault } from '../canvas-core/values.ts';
|
||||
@@ -6,13 +10,16 @@ import { createNdjsonImportSource } from './imports.ts';
|
||||
import {createCopyBudget} from './copy-budget.ts';
|
||||
import type {ImportScheduling} from './import-budget.ts';
|
||||
/** Capture immutable source bytes before a preparation job is admitted. No mutable live getters. */
|
||||
/** 逐项编码header/canvas/element/tombstone为NDJSON,检查记录/总源上限并合作让出,最终返回完整Blob。 */
|
||||
export async function encodeCopySnapshot(document:Document,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<Blob>{
|
||||
const budget=createCopyBudget(signal,scheduling),parts:BlobPart[]=[];let bytes=0;
|
||||
/** 生成一条记录并累计实际UTF8字节,单条≤256KiB、总源≤64MiB;不省略未知组件payload。 */
|
||||
const append=(value:unknown)=>{if(signal.aborted)throw fault('copy_aborted');const text=JSON.stringify(value)+'\n',size=new TextEncoder().encode(text).byteLength;if(size>256*1024)throw fault('record_too_large');bytes+=size;if(bytes>64*1024*1024)throw fault('invalid_import_source');parts.push(text);return size;};
|
||||
append({kind:'header',version:1,projectId:document.projectId});
|
||||
for(const[kind,records]of [['canvas',document.canvases.values()],['element',document.elements.values()],['tombstone',document.tombstones.entries()]] as const)for(const record of records){const size=append({kind,record});await budget.step(Math.max(1,Math.ceil(size/1024)));}
|
||||
if(signal.aborted)throw fault('copy_aborted');return new Blob(parts,{type:'application/x-ndjson'});
|
||||
}
|
||||
/** 旧源完整解码,验证同project/header、墓碑唯一,重建并分片校验完整Document后才返回。 */
|
||||
export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Registry,signal:AbortSignal,scheduling:ImportScheduling={}):Promise<Document>{
|
||||
const budget=createCopyBudget(signal,scheduling),source=createNdjsonImportSource({bytes,fingerprint:'captured-copy-snapshot'}),canvases:CanvasRecord[]=[],elements:ElementRecord[]=[],tombstones=new Map<string,number>();let cursor=0,header=false;
|
||||
while(true){
|
||||
@@ -23,6 +30,7 @@ export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Re
|
||||
await budget.step(Math.max(1,Math.ceil((cursor-start)/1024)));
|
||||
}
|
||||
if(!header||signal.aborted)throw fault(signal.aborted?'copy_aborted':'invalid_copy_snapshot');
|
||||
// 不把合法header/记录数量当成完整图合法;parent/owner/端点/schema仍由核心校验。
|
||||
const document=createDocument(projectId,canvases,elements,tombstones);
|
||||
for(const _ of validateDocumentSteps(document,registry))await budget.step();
|
||||
if(signal.aborted)throw fault('copy_aborted');
|
||||
@@ -30,6 +38,7 @@ export async function decodeCopySnapshot(bytes:Blob,projectId:string,registry:Re
|
||||
}
|
||||
|
||||
/** Copy declarations are a versioned input; never silently reinterpret a persisted preparation. */
|
||||
/** 仅对源涉及组件的数据版本/structure/copy声明生成稳定签名,防持久准备被新声明静默重解释。 */
|
||||
export function copyRegistrySignature(document:Document,registry:Registry):string{
|
||||
const ids=new Set([...document.elements.values()].map(element=>element.componentId));
|
||||
return JSON.stringify([...ids].sort().map(id=>{const definition=registry.components.get(id);return definition?{id,dataVersion:definition.dataVersion,structure:definition.structure,copy:definition.copy??null}: {id,missing:true};}));
|
||||
|
||||
Reference in New Issue
Block a user