docs(canvas): explain recovery encoding and history replay evidence
This commit is contained in:
@@ -1,8 +1,14 @@
|
||||
/**
|
||||
* 把已捕获的恢复图像编码成精确 JSON UTF-8 Blob,按 token/片段分批让出。
|
||||
* 序列化不发布部分 Root;只能对 codec-owned 规范化 JSON 使用分片快速路径,外部图像保留原生防御路径。
|
||||
* 最终 Blob 大小必须匹配编码器的精确证明,避免悄悄变更检查点字节表示。
|
||||
*/
|
||||
import type {RecoveryImage} from './storage-port.ts';
|
||||
import {isSealedRecoveryImage,sealedRecoveryByteLength,encodedRecoveryByteLength} from './recovery-encoding.ts';
|
||||
import {createImportBudget,type ImportScheduling} from './import-budget.ts';
|
||||
import {fault} from '../canvas-core/values.ts';
|
||||
|
||||
/** 长字符串每段至多4096 UTF-16单元;避免截断代理对,再分别转义并拼接为一个合法 JSON 字符串。 */
|
||||
function* stringTokens(value:string):Generator<string>{
|
||||
if(value.length<=4096){yield JSON.stringify(value);return;}
|
||||
yield '"';
|
||||
@@ -10,6 +16,7 @@ function* stringTokens(value:string):Generator<string>{
|
||||
yield '"';
|
||||
}
|
||||
/** Only traverse codec-owned normalized JSON. Small owned subtrees use native stringify. */
|
||||
/** 保留数组/对象原顺序,显式输出分隔符;≤16KiB 已知子树直接 stringify,降低 token 分配开销。 */
|
||||
function* tokens(value:unknown):Generator<string>{
|
||||
if(value&&typeof value==='object'){
|
||||
const size=encodedRecoveryByteLength(value);if(size!==undefined&&size<=16384){yield JSON.stringify(value);return;}
|
||||
@@ -19,12 +26,16 @@ function* tokens(value:unknown):Generator<string>{
|
||||
if(typeof value==='string')yield* stringTokens(value);else yield JSON.stringify(value);
|
||||
}
|
||||
/** Preserve exact JSON.stringify bytes; scheduling never exposes a partial recovery image. */
|
||||
/** 输出完成的 Blob;check 在工作/await 边界复查 leader/生命周期,失败不返回半成品。 */
|
||||
export async function serializeRecoveryImage(image:RecoveryImage,options:ImportScheduling&{check?:()=>void}={}):Promise<Blob>{
|
||||
options.check?.();
|
||||
// 外部输入不信任所有权/尺寸缓存,继续走原生同步 stringify,不能冒称这一路也全部可分片。
|
||||
if(!isSealedRecoveryImage(image)){const bytes=new Blob([JSON.stringify(image)],{type:'application/json'});options.check?.();return bytes;}
|
||||
// 小 token 先聚合成约8K字符的片段,控制 BlobPart 数量;不是每个标点都创建独立 Blob。
|
||||
const budget=createImportBudget(new AbortController().signal,options),parts:BlobPart[]=[];let pending:string[]=[],length=0;
|
||||
for(const token of tokens(image)){
|
||||
pending.push(token);length+=token.length;
|
||||
// 检查身份后让出,恢复执行再检查;避免异步期间已退役的 writer 继续采用结果。
|
||||
if(length>=8192){parts.push(pending.join(''));pending=[];length=0;options.check?.();await budget.step(128);options.check?.();}
|
||||
}
|
||||
if(pending.length)parts.push(pending.join(''));options.check?.();
|
||||
|
||||
Reference in New Issue
Block a user