docs(canvas): explain host ownership, asset retention and durable storage

This commit is contained in:
2026-11-12 00:07:21 +08:00
parent 4c1b35e0cf
commit da00490ded
9 changed files with 227 additions and 0 deletions
+19
View File
@@ -1,3 +1,8 @@
/**
* 工作区级生命周期:共享 digest/display/asset depot,按 projectId 复用一个 ProjectEngine。
* view 只借用 engine,离开页面不关闭持久任务;workspace.close 统一收尾所有项目及资源池。
* 关闭前先停止新准入,任一项目关闭失败就保留共享池/存储供重试,不用强制清空掩盖未保存状态。
*/
import {createAssetDepot} from './asset-depot.ts';
import type {LoadingState} from './loading.ts';
import type { Document, Id, Registry } from '../canvas-core/types.ts';
@@ -7,7 +12,9 @@ import {createDigestPool,type DigestPort} from './digest-pool.ts';
import type { StoragePort } from './storage-port.ts';
import { createDisplayCache } from './display-cache.ts';
/** 异步打开的项目引擎类型,文档、历史和运行事实的真正拥有者。 */
export type ProjectEngine = Awaited<ReturnType<typeof openProjectEngine>>;
/** 装配身份、存储、共享计算端口与每项目 service adapters;不把凭证写入持久文档。 */
export type WorkspaceOptions = {
accountId: Id; workspaceId: Id; authEpoch: number; registry: Registry; storage: StoragePort; digests?:DigestPort; images?:import('./image-decoder.ts').ImageDecoderPort; queryBudget?:EngineOptions['queryBudget'];
isCurrentIdentity(): boolean;
@@ -16,13 +23,17 @@ export type WorkspaceOptions = {
};
/** Workspace owns persistent projects; a view only borrows one and never closes it. */
/** 创建工作区容器,不立刻打开所有项目,只有 open/openPartial 才取得项目 engine。 */
export function createWorkspaceRuntime(options: WorkspaceOptions) {
const digests=options.digests??createDigestPool();
const displays=createDisplayCache({onError:options.onError});
// 缓存打开中的 Promise 而非仅缓存完成实例,防止并发两个 view 为同项目申请两个 leader。
const projects = new Map<Id, Promise<ProjectEngine>>();
let accepting = true, closed = false, closing: Promise<void> | undefined;
/** 准入同时要求工作区仍接受任务和宿主身份仍有效,关闭一开始就让旧调用失效。 */
const current = () => accepting && !closed && options.isCurrentIdentity();
const assetDepot=options.storage.assetDepot?createAssetDepot({scope:options,port:options.storage.assetDepot,current,digest:(bytes,signal)=>digests.digest(bytes,signal)}):undefined;
/** 取得/创建共享项目;打开失败只移除同一个 Promise,迟到失败不能删掉后来重开的实例。 */
function acquire(document:Document,versions:ReadonlyMap<Id,number>,loading?:LoadingState){
if(!current())return Promise.reject(fault('identity_changed'));
const existing=projects.get(document.projectId);if(existing)return existing;
@@ -33,22 +44,28 @@ export function createWorkspaceRuntime(options: WorkspaceOptions) {
accountId: options.accountId, workspaceId: options.workspaceId, authEpoch: options.authEpoch, registry: options.registry,
isCurrentIdentity: current,
assetDepot,
/** 查看项目打开句柄的只读表,不授予外部关闭/替换内部 ownership 的能力。 */
getProjects: () => readMap(projects),
/** 完整源与已有 engine 协调:同捕获完成走 loading.complete,旧版本不覆盖较新的本地基线。 */
open(document: Document, versions: ReadonlyMap<Id, number>,settings:{sourceToken?:string}={}) {
return acquire(document,versions).then(async engine=>{if(!current())throw fault('identity_changed');const loading=engine.loading.getState();if(loading&&settings.sourceToken===loading.sourceToken){const result=await engine.loading.complete(document,versions,{sourceToken:settings.sourceToken});if(result.status==='rejected')throw fault(result.code,result.targets);}else{const previous=engine.getSnapshot().runtime.versions;if(![...versions].some(([id,value])=>(previous.get(id)??0)>value)){const result=engine.refresh(document,versions);if(result.status==='rejected'&&loading)throw fault(result.code,result.targets);}}return engine;});
},
/** 接入部分源并复用项目 engine,仅相同 sourceToken 的后续块继续 accept。 */
openPartial(document:Document,versions:ReadonlyMap<Id,number>,loading:LoadingState){
return acquire(document,versions,loading).then(engine=>{if(!current())throw fault('identity_changed');const previous=engine.loading.getState();if(previous?.sourceToken===loading.sourceToken){const result=engine.loading.accept(document,versions,loading);if(result.status==='rejected')throw fault(result.code,result.targets);}return engine;});
},
/** view 离开后工作区仍可补完项目加载;await 前后都检查身份,错误交宿主报告。 */
async resumeLoading(projectId:Id){
try{if(!current())throw fault('identity_changed');const opening=projects.get(projectId);if(!opening)throw fault('project_not_open');const engine=await opening;if(!current())throw fault('identity_changed');const result=await engine.loading.resume();if(result.status==='rejected')throw fault(result.code,result.targets);return result;}
catch(error){if(current()){try{options.onError?.(error);}catch{}}throw error;}
},
/** 幂等/可重试关闭:复用当前 closing Promise,全部 engine 成功后才释放池和 storage。 */
close() {
accepting = false; // Fence commands/transports before awaiting pending opens or storage.
if (closed) return Promise.resolve();
if (closing) return closing;
const task = (async () => {
// 未成功打开的项目无需关闭;已打开项目各自等待 durable 收尾,allSettled 不漏掉其它项目的错误。
const results = await Promise.allSettled([...projects.values()].map(async pending => {
let engine: ProjectEngine;
try { engine = await pending; } catch { return; }
@@ -56,6 +73,7 @@ export function createWorkspaceRuntime(options: WorkspaceOptions) {
}));
const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
if (errors.length) throw new AggregateError(errors, 'workspace_close_failed');
// 只有所有项目可靠关闭才到这里;失败走 finally 清 closing,下一次 close 可重试,资源不先释放。
assetDepot?.close();displays.close();digests.close();options.images?.close();options.storage.close(); projects.clear(); closed = true;
})();
closing = task.finally(() => { closing = undefined; });
@@ -63,4 +81,5 @@ export function createWorkspaceRuntime(options: WorkspaceOptions) {
},
});
}
/** 公共工作区 API 从实现推导,避免另一份可变 store 合同。 */
export type WorkspaceRuntime = ReturnType<typeof createWorkspaceRuntime>;