228 lines
19 KiB
TypeScript
228 lines
19 KiB
TypeScript
/**
|
|
* 恢复图像的 JSON 值捕获、冻结与分片编码。保持既有 JSON 表示语义，并为已证明不可变的数据缓存结果/字节数。
|
|
* 它不是业务 schema 校验器：非有限数按 JSON 归一为 null，对象 undefined 字段省略、数组槽位转 null。
|
|
* 外部可变数据必须在首次 await 前捕获；仅来源/结构可证明安全的部分延后遍历，调度预算是软目标。
|
|
*/
|
|
import {hasDetachedJsonData} from '../canvas-core/json-data.ts';
|
|
import type { Json } from '../canvas-core/types.ts';
|
|
import { fault, freeze, validJson } from '../canvas-core/values.ts';
|
|
import {isDataContainer} from '../canvas-core/data-containers.ts';
|
|
import {createImportBudget, type ImportScheduling} from './import-budget.ts';
|
|
import type { RecoveryImage } from './storage-port.ts';
|
|
|
|
/** 归一后的值、子树高度、可复用证明和精确 JSON UTF-8 字节数；undefined 表示 JSON 省略值。 */
|
|
type Encoded = {value:Json|undefined;height:number;reusable:boolean;bytes:number};
|
|
// immutable: 源对象→归一值/高度/字节；encodedSizes: 输出子树→字节；sealed/imageSizes: 本 codec 图像身份/总字节。
|
|
// 都是进程内弱来源事实，不持久化、不检查权限/schema；JSON 克隆/重开对象不会继承 sealed 品牌。
|
|
const immutable=new WeakMap<object,Encoded>(),sealed=new WeakSet<object>(),encodedSizes=new WeakMap<object,number>(),imageSizes=new WeakMap<object,number>();
|
|
/** 计算 UTF-8 字节数（代理对计4字节）；调用时多为 JSON.stringify 后的已转义字符串。 */
|
|
function utf8Length(text:string){let bytes=0;for(let i=0;i<text.length;i++){const c=text.charCodeAt(i);if(c<128)bytes++;else if(c<2048)bytes+=2;else if(c>=0xd800&&c<=0xdbff&&i+1<text.length&&text.charCodeAt(i+1)>=0xdc00&&text.charCodeAt(i+1)<=0xdfff){bytes+=4;i++;}else bytes+=3;}return bytes;}
|
|
/** 计算原子值/属性名的 JSON 表示成本，包含引号及转义，不使用 JS UTF-16 length 代替。 */
|
|
const scalarBytes=(value:unknown)=>utf8Length(JSON.stringify(value));
|
|
|
|
/** JSON value semantics, with reuse only for transitively frozen plain data properties. */
|
|
/** 一次同步访问器拥有 visiting 路径 Set，共用模块 immutable 弱缓存；共享节点不等同循环，退出路径即移除。
|
|
* 普通数据逐属性捕获，toJSON/装箱/自定义原型退回原生 JSON 语义；此 codec 不是一般保身份深克隆工具。
|
|
* 会求值外部 getter/toJSON，也可能传播原生 JSON 异常；不修改业务 Root，但不能回滚用户回调副作用。 */
|
|
function createEncoder() {
|
|
const visiting=new Set<object>();
|
|
/** 按原 JSON 语义捕获值并检查最大深度64，返回携带不可变性/大小证明的 Encoded。 */
|
|
function visit(value:unknown,depth:number,key:string):Encoded {
|
|
if(value===null||typeof value==='string'||typeof value==='boolean'){if(depth>64)throw fault('invalid_recovery_payload');return{value,height:0,reusable:true,bytes:scalarBytes(value)};}
|
|
if(typeof value==='number'){if(depth>64)throw fault('invalid_recovery_payload');const normalized=Number.isFinite(value)?(Object.is(value,-0)?0:value):null;return{value:normalized,height:0,reusable:true,bytes:scalarBytes(normalized)};}
|
|
if(value===undefined||typeof value==='symbol')return{value:undefined,height:0,reusable:true,bytes:0};
|
|
/** 用 {[key]:value} 包裹保留原生 toJSON 的属性 key 上下文，stringify/parse 后再检查 JSON 深度并冻结结果。
|
|
* undefined 省略、BigInt/循环/用户回调错误保持该原生路径行为；返回 reusable=false，避免缓存隐藏可变状态。 */
|
|
const fallback=()=>{
|
|
// Preserve the previous JSON codec for toJSON, boxed values and custom prototypes.
|
|
// These can depend on hidden mutable state and are deliberately never cached.
|
|
const text=JSON.stringify({[key]:value}),encoded=JSON.parse(text)[key] as Json|undefined;
|
|
if(encoded!==undefined&&!validJson(encoded,depth))throw fault('invalid_recovery_payload');
|
|
return{value:freeze(encoded),height:0,reusable:false,bytes:encoded===undefined?0:scalarBytes(encoded)};
|
|
};
|
|
// BigInt 默认由原生 JSON 抛错，有自定义 toJSON 时保持其既有语义；函数通常被省略。
|
|
if(typeof value==='bigint'||typeof value==='function')return fallback();
|
|
if(typeof value!=='object')throw fault('invalid_recovery_payload');
|
|
const object=value as object,cached=immutable.get(object);
|
|
// 命中先前完整证明可跳过重读，但仍以当前位置+子树高度检查深度；它不是重新验证任意原型行为的入口。
|
|
if(cached){if(depth+cached.height>64)throw fault('invalid_recovery_payload');return cached;}
|
|
const prototype=Object.getPrototypeOf(object);
|
|
// A callable toJSON getter must also be evaluated afresh on every encode.
|
|
if(typeof (object as {toJSON?:unknown}).toJSON==='function'||(Array.isArray(object)?prototype!==Array.prototype&&prototype!==null:prototype!==Object.prototype&&prototype!==null))return fallback();
|
|
if(depth>64)throw fault('invalid_recovery_payload');
|
|
if(visiting.has(object))throw fault('invalid_recovery_payload');visiting.add(object);
|
|
const toJSON=Object.getOwnPropertyDescriptor(object,'toJSON');
|
|
// 浅 frozen 不够：本对象必须无访问器，且所有实际子值也都具有可复用证明。
|
|
let reusable=Object.isFrozen(object)&&(!toJSON||Object.hasOwn(toJSON,'value')),height=0,bytes=2;
|
|
try {
|
|
// 数组按 length 捕获，空洞/undefined 转 null；无自有数据属性的槽位会使结果不可缓存。
|
|
if(Array.isArray(object)){
|
|
const result:Json[]=[];
|
|
for(let index=0;index<object.length;index++){
|
|
const descriptor=Object.getOwnPropertyDescriptor(object,String(index));if(!descriptor||!Object.hasOwn(descriptor,'value'))reusable=false;
|
|
const child=visit(object[index],depth+1,String(index));if(child.value===undefined&&depth+1>64)throw fault('invalid_recovery_payload');result.push(child.value??null);bytes+=(index?1:0)+(child.value===undefined?4:child.bytes);height=Math.max(height,1+child.height);reusable&&=child.reusable;
|
|
}
|
|
const encoded={value:Object.freeze(result) as unknown as Json,height,reusable,bytes};encodedSizes.set(result,bytes);if(reusable)immutable.set(object,encoded);return encoded;
|
|
}
|
|
// 对象只遍历可枚举自有字符串键；省略值不计输出属性/高度，数组同类槽则归一成 null 并受深度上限约束。
|
|
// defineProperty 将 __proto__ 等保留为普通自有数据键，字节累计包含名字/冒号/逗号，不改变属性次序。
|
|
const result:Record<string,Json>={};let properties=0;
|
|
for(const name of Object.keys(object)){
|
|
const descriptor=Object.getOwnPropertyDescriptor(object,name);if(!descriptor||!Object.hasOwn(descriptor,'value'))reusable=false;
|
|
const child=visit((object as Record<string,unknown>)[name],depth+1,name);reusable&&=child.reusable;
|
|
if(child.value!==undefined){bytes+=(properties++?1:0)+scalarBytes(name)+1+child.bytes;Object.defineProperty(result,name,{value:child.value,enumerable:true});height=Math.max(height,1+child.height);}
|
|
}
|
|
const encoded={value:Object.freeze(result) as Json,height,reusable,bytes};encodedSizes.set(result,bytes);if(reusable)immutable.set(object,encoded);return encoded;
|
|
}finally{visiting.delete(object);}
|
|
}
|
|
return visit;
|
|
}
|
|
/** 同步捕获任意兼容输入为冻结 JSON；顶层被省略时拒绝，不能产生无 payload 的图像。 */
|
|
export function encodeRecoveryValue(input:unknown):Json {
|
|
const result=createEncoder()(input,0,'');if(result.value===undefined)throw fault('invalid_recovery_payload');return result.value;
|
|
}
|
|
|
|
/** 恢复图像版本，与 IDB schema/journal 版本分开，由具体恢复特性选择。 */
|
|
type ImageVersion = RecoveryImage['formatVersion'];
|
|
/** 校验受支持的图像版本和 revision 关系，localRevision 不得超过 rootRevision。 */
|
|
function validateHeader(formatVersion:ImageVersion,rootRevision:number,localRevision:number){
|
|
if(![1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17].includes(formatVersion)||!Number.isSafeInteger(rootRevision)||rootRevision<0||!Number.isSafeInteger(localRevision)||localRevision<0||localRevision>rootRevision)throw fault('corrupt_recovery_image');
|
|
}
|
|
/** 对已归一 payload 组装冻结图像并登记私有 sealed/大小；公开入口在此前验证 header。
|
|
* header 仅数字/ASCII 字段，以 payload:null 信封长度减 4 再加 payload UTF-8 成本；无子树事实时用原生计算。
|
|
* sealed 只表示 codec 捕获完成，不证明业务 schema、存储完成或服务端已确认。 */
|
|
function finishImage(formatVersion:ImageVersion,rootRevision:number,localRevision:number,encoded:Json):RecoveryImage {
|
|
const image=Object.freeze({formatVersion,rootRevision,localRevision,payload:encoded});sealed.add(image);imageSizes.set(image,JSON.stringify({...image,payload:null}).length-4+(encoded&&typeof encoded==='object'?encodedSizes.get(encoded)??scalarBytes(encoded):scalarBytes(encoded)));return image;
|
|
}
|
|
/** Only codec-owned, validated immutable images qualify for the storage copy fast path. */
|
|
/** 同步编码入口，完成 header 与值域捕获后才授予 sealed 来源标记。 */
|
|
export function sealRecoveryImage(formatVersion:ImageVersion,rootRevision:number,localRevision:number,payload:unknown):RecoveryImage {
|
|
validateHeader(formatVersion,rootRevision,localRevision);
|
|
return finishImage(formatVersion,rootRevision,localRevision,encodeRecoveryValue(payload));
|
|
}
|
|
|
|
/** 暂存可跨 suspension 保持值语义的原子输入，稍后按预算完成归一化/字符串字节计算。 */
|
|
type Scalar = null|string|number|boolean|undefined|symbol;
|
|
/** 编码准备计划：原子值、已捕获 Encoded，或可安全延后读取的结构/预捕获 children。 */
|
|
type Prepared = Scalar | Encoded | {source:object;depth:number;children?:Prepared[];keys?:string[]};
|
|
// Read unknown objects synchronously, before the first suspension. Shape-owned
|
|
// containers can include external values; each such occurrence is captured now.
|
|
// Detached JSON can also defer after checking its prototype environment.
|
|
/** 同步准备 Prepared 树：原子值可延后，已证明 Encoded 可复用，陌生子树按出现次数立即规范化。
|
|
* shape-owned 容器只证明外壳，仍逐个捕获外部子值；detached JSON 在原型环境允许时可整棵延后。
|
|
* 此准备阶段本身可遍历大量结构/运行回调，未必常数时间；不是 async 后才首次读取所有输入。 */
|
|
function prepareEncoding(input:unknown) {
|
|
const normalize=createEncoder(),visiting=new Set<object>();
|
|
let plainEnvironment:boolean|undefined;
|
|
/** 同步规范化陌生值；回调可能改全局原型，finally 只清 plainEnvironment 检查缓存，失败也清。
|
|
* 不清模块已有 immutable 编码事实，也不撤销用户环境修改；后续 detached 准入需重新读描述符。 */
|
|
const capture=(value:unknown,depth:number,key:string)=>{
|
|
try{return normalize(value,depth,key);}finally{plainEnvironment=undefined;}
|
|
};
|
|
/** 仅自有 detached JSON 且基础原型无 toJSON 钩子时，才允许整个子树延后读取。 */
|
|
const detached=(value:object)=>hasDetachedJsonData(value)&&(plainEnvironment??=(
|
|
Object.getPrototypeOf(Object.prototype)===null&&Object.getPrototypeOf(Array.prototype)===Object.prototype&&
|
|
!Object.getOwnPropertyDescriptor(Object.prototype,'toJSON')&&!Object.getOwnPropertyDescriptor(Array.prototype,'toJSON')
|
|
));
|
|
/** 递归构造安全计划；原子值延后，已缓存值复用，其余未知子树立刻捕获。 */
|
|
function prepare(value:unknown,depth:number,key:string):Prepared {
|
|
const kind=typeof value;
|
|
if(value===null||kind==='string'||kind==='number'||kind==='boolean'||kind==='undefined'||kind==='symbol'){
|
|
if(depth>64&&value!==undefined&&typeof value!=='symbol')throw fault('invalid_recovery_payload');
|
|
// Primitives cannot change while suspended. Defer normalization/UTF-8 work
|
|
// as well as allocation of their Encoded facts to the budgeted traversal.
|
|
return value as Scalar;
|
|
}
|
|
if(typeof value!=='object')return capture(value,depth,key);
|
|
const cached=immutable.get(value);
|
|
if(cached){if(depth+cached.height>64)throw fault('invalid_recovery_payload');return cached;}
|
|
// Detached JSON has no accessors, custom prototypes or mutable
|
|
// descendants. Its full walk can wait; foreign freezes cannot grant this.
|
|
if(detached(value))return {source:value,depth};
|
|
// 陌生 frozen 对象仍走同步捕获，不凭外壳不可变就假设子值/访问器也稳定。
|
|
if(!isDataContainer(value))return capture(value,depth,key);
|
|
// Prototype toJSON changes must retain ordinary JSON semantics, including
|
|
// accessors. Inspect descriptors without evaluating them an extra time.
|
|
// 检查描述符而非重复读取 getter，保留继承 toJSON 的原生 JSON 语义。
|
|
let prototype:object|null=value,hasToJSON=false;
|
|
while(prototype){if(Object.getOwnPropertyDescriptor(prototype,'toJSON')){hasToJSON=true;break;}prototype=Object.getPrototypeOf(prototype);}
|
|
if(hasToJSON)return capture(value,depth,key);
|
|
if(depth>64||visiting.has(value))throw fault('invalid_recovery_payload');
|
|
visiting.add(value);
|
|
try {
|
|
const keys=Array.isArray(value)?undefined:Object.keys(value),children:Prepared[]=[];
|
|
if(keys)for(const name of keys)children.push(prepare((value as Record<string,unknown>)[name],depth+1,name));
|
|
else for(let index=0;index<(value as unknown[]).length;index++)children.push(prepare((value as unknown[])[index],depth+1,String(index)));
|
|
return {source:value,depth,children,keys};
|
|
}finally{visiting.delete(value);}
|
|
}
|
|
return {plan:prepare(input,0,''),normalize};
|
|
}
|
|
|
|
/** Capture external data immediately; cooperatively encode stable owned tables.
|
|
* Time slicing is soft: synchronous capture of an unknown subtree remains indivisible.
|
|
* The returned image has exactly the synchronous codec's wire representation. */
|
|
/** 验 header 并同步 prepare 后，驱动编码生成器按 ImportBudget 合作让出，最终才 finishImage。
|
|
* 默认优先 scheduler.yield，否则 timer；无 signal/check 参数，宿主需通过 yieldTask 或外层采纳围栏处理生命周期。
|
|
* 逐子项计工作，原子归一化/字符串转义/UTF-8 计量及未知子树捕获仍为同步步骤，不保证每项都不超时间片。
|
|
* 失败不返回部分图像/授予可用 sealed 结果，但已建的不可变子树缓存与回调副作用不会整体回滚。
|
|
* 结果沿用同步 codec 的规范 JSON 表示，不包含文件 Blob 或恢复业务状态的执行动作。 */
|
|
export async function sealRecoveryImageAsync(formatVersion:ImageVersion,rootRevision:number,localRevision:number,payload:unknown,options:ImportScheduling={}):Promise<RecoveryImage> {
|
|
validateHeader(formatVersion,rootRevision,localRevision);
|
|
const {plan,normalize}=prepareEncoding(payload);
|
|
const scheduler=(globalThis as typeof globalThis & {scheduler?:{yield?:()=>Promise<void>}}).scheduler;
|
|
// 默认使用可用 scheduler.yield；没有时由预算适配器回退，所有语义仍由同一个 normalize 决定。
|
|
const budget=createImportBudget(new AbortController().signal,{...options,yieldTask:options.yieldTask??(typeof scheduler?.yield==='function'?()=>scheduler.yield!():undefined)});
|
|
/** Prepared 的判别：原子值走 normalize，带 height 是已捕获 Encoded，其余为结构计划。
|
|
* 有 children 就用准备阶段捕获值；无 children 只允许已准入 detached 源的不可变数据属性延后读取。
|
|
* 每个输出子项完成后才 budget.step/yield；组装容器时累计高度/精确字节并登记弱缓存，不外发半成品。 */
|
|
function* encode(plan:Prepared,depth=0,key=''):Generator<Promise<void>,Encoded,void>{
|
|
if(plan===null||typeof plan!=='object')return normalize(plan,depth,key);
|
|
if('height' in plan)return plan;
|
|
// Preparation must capture every unsafe occurrence before yielding. Once an
|
|
// earlier occurrence has assembled a proven immutable source, later plans
|
|
// can reuse that fact without rebuilding the same JSON containers.
|
|
// 同一源先前出现已建立完整不可变证明时，可复用派生结果，但仍检查当前深度余量。
|
|
const cached=immutable.get(plan.source);
|
|
if(cached){if(depth+cached.height>64)throw fault('invalid_recovery_payload');return cached;}
|
|
if(depth>64)throw fault('invalid_recovery_payload');
|
|
let height=0,bytes=2,reusable=true,properties=0;
|
|
const array=Array.isArray(plan.source),keys=plan.children?plan.keys:array?undefined:Object.keys(plan.source);
|
|
const length=plan.children?.length??(array?(plan.source as unknown[]).length:keys!.length),result:Json[]|Record<string,Json>=array?[]:{};
|
|
for(let index=0;index<length;index++){
|
|
const name=keys?.[index]??String(index);
|
|
// No children array means detached JSON. Read only its immutable own data
|
|
// properties, with the prototype behavior captured during preparation.
|
|
const value=plan.children?undefined:(plan.source as Record<string,unknown>)[name];
|
|
const entry=plan.children?plan.children[index]:value&&typeof value==='object'?{source:value,depth:plan.depth+1}:value as Scalar;
|
|
const child=entry===null||typeof entry!=='object'?normalize(entry,plan.depth+1,name):'height' in entry?entry:yield* encode(entry,plan.depth+1,name);
|
|
reusable&&=child.reusable;
|
|
if(array){
|
|
if(child.value===undefined&&plan.depth+1>64)throw fault('invalid_recovery_payload');
|
|
(result as Json[]).push(child.value??null);bytes+=(index?1:0)+(child.value===undefined?4:child.bytes);height=Math.max(height,1+child.height);
|
|
}else if(child.value!==undefined){
|
|
const name=keys![index];bytes+=(properties++?1:0)+scalarBytes(name)+1+child.bytes;
|
|
Object.defineProperty(result,name,{value:child.value,enumerable:true});height=Math.max(height,1+child.height);
|
|
}
|
|
// 工作确实发生在 yield 之间，而不是先同步编码完后仅空等一个异步边界。
|
|
const pause=budget.step();if(pause)yield pause;
|
|
}
|
|
const encoded={value:Object.freeze(result) as Json,height,reusable,bytes};encodedSizes.set(result,bytes);if(reusable)immutable.set(plan.source,encoded);return encoded;
|
|
}
|
|
// 宿主循环消费生成器并等待让出；最终 Encoded 完成才调用 finishImage。
|
|
const iterator=encode(plan);let step=iterator.next();while(!step.done){await step.value;step=iterator.next();}
|
|
if(step.value.value===undefined)throw fault('invalid_recovery_payload');
|
|
return finishImage(formatVersion,rootRevision,localRevision,step.value.value);
|
|
}
|
|
/** 仅查询本进程私有 WeakSet 身份，不重新验 header/payload/持久性；外部同形对象或反序列化副本不命中。 */
|
|
export function isSealedRecoveryImage(image:RecoveryImage):boolean{return sealed.has(image);}
|
|
|
|
/** Exact UTF-8 JSON size, available only for codec-owned immutable images. */
|
|
/** 只对 codec-owned 图像返回精确总字节，普通外来图像返回 undefined 走防御路径。 */
|
|
export function sealedRecoveryByteLength(image:RecoveryImage){return imageSizes.get(image);}
|
|
|
|
/** Internal codec ownership/size fact, never inferred from external Object.freeze. */
|
|
/** 查询本 codec 输出子树的大小事实，未知身份返回 undefined，不能用外部 freeze/自报长度冒充。
|
|
* 只提供 serializer 的成本依据，不证明任何加载/上传任务已完成。 */
|
|
export function encodedRecoveryByteLength(value:object){return encodedSizes.get(value);}
|