Files
Endoleap/src/lib/canvas-runtime/loader.ts
T

197 lines
20 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 作用域化只读加载调度器:同 query identity 合并进行中的请求,每个导航订阅仍有独立取消/快照。
* queue 控制等待、active 限并发、cache 可选且必须额外验证;不拥有 working/history/ACK,也不直接发布业务文档。
* 端口必须验证并提供不可变 payload 和测量 byteLength,这里校验捕获元数据、连续块与预算,不猜任意 T 的结构。
*/
import type { Id } from '../canvas-core/types.ts';
import { equal, fault, freeze } from '../canvas-core/values.ts';
/** 账号/工作区/项目/画布/查询/格式/来源/authEpoch 决定共享身份,navigationGeneration 属于订阅者。 */
export type LoadScope = {
readonly accountId: Id; readonly workspaceId: Id; readonly projectId: Id | null; readonly canvasId: Id;
readonly viewKey: string; readonly format: string; readonly queryFingerprint: string; readonly source: string;
readonly authEpoch: number; readonly navigationGeneration: number;
};
/** 一次捕获的连续块:queryKey/token/版本/权限代次固定,coverage 由协议适配器解释。 */
export type LoadChunk<T> = {
readonly queryKey: string; readonly projectId: Id; readonly snapshotToken: string;
readonly serverVersions: Readonly<Record<Id, number>>; readonly permissionEpoch: number;
readonly sequence: number; readonly coverage: readonly string[]; readonly complete: boolean;
readonly byteLength: number; readonly value: T;
};
/** 加载状态及已收到块;initial-ready 表示收到首个合法块,可能只是空模型头,并不证明画面已有元素。
* partial 继续累积前缀;ready Promise 要等 terminal+EOF,失败前缀仍保留在 failed-with-partial 快照中。 */
export type LoadSnapshot<T> = {
readonly scope: LoadScope; readonly generation: number;
readonly cacheStatus: 'bypassed' | 'miss' | 'invalid' | 'hit';
readonly status: 'queued' | 'loading' | 'initial-ready' | 'partial' | 'complete' | 'failed' | 'failed-with-partial' | 'cancelled';
readonly chunks: readonly LoadChunk<T>[]; readonly coverage: readonly string[]; readonly byteLength: number;
readonly error?: { readonly code: string; readonly message: string };
};
/** 可取消的异步只读块源,负责实际 HTTP/解码与 payload 校验,不能在这里偷偷写项目状态。 */
export type LoadPort<T> = (scope: LoadScope, signal: AbortSignal) => AsyncIterable<LoadChunk<T>>;
/** 单订阅句柄:ready 等完整读取,getSnapshot 可看合法前缀,release 仅解除自己的借用。 */
export type LoadHandle<T> = { readonly ready: Promise<LoadSnapshot<T>>; getSnapshot(): LoadSnapshot<T>; release(): void };
/** Navigation belongs to a subscriber, not the shared query identity. */
/** 验证 scope 并稳定编码共享 key;刻意排除导航代次,让两个 view 可复用同一读取。 */
export function loadQueryKey(scope: LoadScope): string {
if (!scope || ![scope.accountId, scope.workspaceId, scope.canvasId, scope.viewKey, scope.format, scope.queryFingerprint, scope.source].every(value => typeof value === 'string' && value.length > 0)
|| scope.projectId !== null && (typeof scope.projectId !== 'string' || !scope.projectId)
|| ![scope.authEpoch, scope.navigationGeneration].every(value => Number.isSafeInteger(value) && value >= 0)) throw fault('invalid_load_scope');
return JSON.stringify([scope.accountId, scope.workspaceId, scope.projectId, scope.canvasId, scope.viewKey, scope.format, scope.queryFingerprint, scope.source, scope.authEpoch]);
}
/** Read copies only. This coordinator never publishes a document or a server ACK.
* Adapters validate payloads and declare their measured byte cost before yielding.
*/
/** 建立共享 query 调度器:inflight 去重、queue 按 generation FIFO、active 计真实未退出源,cache 按 Map LRU。
* 默认并发 4/等待 128、单响应声明 64MiB/4096 块;上限依赖 adapter 准确测量 byteLength,不测 T 或内存峰值。
* 默认缓存年龄 0 不插入终态缓存;启用后仍须订阅 allow-validated 且 acceptCached 同意,不把缓存当授权事实。
* 不重试、无读取超时,不深克隆/解释 T;current 应表达共享查询的授权生命周期,导航取消由各订阅管理。 */
export function createScopedLoader<T>(options: {
load: LoadPort<T>; current(scope: LoadScope): boolean; concurrency?: number; maxQueued?: number;
maxResponseBytes?: number; maxChunks?: number; maxCacheEntries?: number; maxCacheBytes?: number;
cacheMaxAgeMs?: number; now?: () => number;
acceptCached?(scope: LoadScope, snapshot: LoadSnapshot<T>): boolean;
onObserverError?(error: unknown): void;
}) {
/** 订阅自己的 scope/取消/通知状态,不把旧导航的取消写成整个 job 失败。 */
type Subscriber = { readonly scope: LoadScope; active: boolean; cancelled?: LoadSnapshot<T>; lastState?: LoadSnapshot<T>; snapshot?: LoadSnapshot<T>;resolve(value: LoadSnapshot<T>): void; reject(error: unknown): void; cleanup(): void; notify?(snapshot: LoadSnapshot<T>): void };
/** 共享执行句柄,scope 来自首个订阅;view 会将导航信息换成各订阅自己的 scope。
* generation 区分重开,controller 在 retire(最后释放或 close)时 abort,不以订阅数为持久任务事实。 */
type Job = { readonly key: string; readonly scope: LoadScope; readonly generation: number; readonly controller: AbortController; readonly subscribers: Set<Subscriber>; state: LoadSnapshot<T>; retired: boolean };
const concurrency = options.concurrency ?? 4, maxQueued = options.maxQueued ?? 128, maxBytes = options.maxResponseBytes ?? 64 * 1024 * 1024, maxChunks = options.maxChunks ?? 4096;
const maxCacheEntries = options.maxCacheEntries ?? 16, maxCacheBytes = options.maxCacheBytes ?? 16 * 1024 * 1024, cacheMaxAge = options.cacheMaxAgeMs ?? 0;
for (const [name, value] of Object.entries({ concurrency, maxQueued, maxBytes, maxChunks, maxCacheEntries, maxCacheBytes, cacheMaxAge })) if (!Number.isSafeInteger(value) || value < (['maxCacheEntries', 'maxCacheBytes', 'cacheMaxAge'].includes(name) ? 0 : 1)) throw fault('invalid_loader_budget');
// inflight 按 query 去重,queue 按 generation FIFO;cache 的 Map 插入顺序用于 LRU 淘汰。
const inflight = new Map<string, Job>(), queue = new Map<number, Job>(), cache = new Map<string, { state: LoadSnapshot<T>; at: number }>();
let active = 0, generation = 0, closed = false, cacheBytes = 0;
/** 缓存计时输入必须非负安全整数;具体缓存命中还要检查时间倒退/年龄。 */
const now = () => { const value = (options.now ?? Date.now)(); if (!Number.isSafeInteger(value) || value < 0) throw fault('invalid_loader_clock'); return value; };
/** 每个异步采纳边界检查 loader 生命周期与精确身份,不用 HTTP 成功替代授权仍有效。 */
const current = (scope: LoadScope) => { if (closed) throw fault('loader_closed'); if (!options.current(scope)) throw fault('identity_changed'); };
/** 共享 job 状态不变时复用该订阅快照;scope 替换为订阅者自己的导航信息。 */
const view = (job: Job, subscriber: Subscriber): LoadSnapshot<T> => {if(subscriber.lastState!==job.state){subscriber.lastState=job.state;subscriber.snapshot=Object.freeze({...job.state,scope:subscriber.scope});}return subscriber.snapshot!;};
/** 单独隔离 observer 异常,报告失败也不改变共享执行和其它订阅者的通知。 */
const notifyOne = (job: Job, subscriber: Subscriber) => { if (subscriber.active) { try { subscriber.notify?.(view(job, subscriber)); } catch (error) { try { options.onObserverError?.(error); } catch { /* Observers cannot change scheduling. */ } } } };
/** 副本遍历当前订阅者,允许通知过程中某订阅自行释放而不破坏迭代。 */
const notify = (job: Job) => { for (const subscriber of [...job.subscribers]) notifyOne(job, subscriber); };
/** 淘汰同时扣除字节计数,避免缓存键删了但容量永远不归还。 */
const removeCache = (key: string) => { const entry = cache.get(key); if (entry) { cacheBytes -= entry.state.byteLength; cache.delete(key); } };
/** 幂等 retire:abort、移除排队/仍指向自己的 inflight,不删除缓存、不清前缀或提早扣 active。
* 成功/失败后仍保留的句柄可独立 release;本函数不把已兑现的 ready Promise 改成拒绝。 */
function retire(job: Job) {
if (job.retired) return; job.retired = true; job.controller.abort(); queue.delete(job.generation);
if (inflight.get(job.key) === job) inflight.delete(job.key);
}
/** FIFO 启动有订阅的工作并登记真实 active;即使源无视 abort,只有它 finally 结束才归还槽位。 */
function pump() {
while (!closed && active < concurrency && queue.size) {
const job = queue.values().next().value!; queue.delete(job.generation);
if (job.retired || !job.subscribers.size) continue;
active++; job.state = Object.freeze({ ...job.state, status: 'loading' }); notify(job);
void (async () => {
try {
current(job.scope); let terminal = false, projectId: Id | undefined, token: string | undefined, versions: Readonly<Record<Id, number>> | undefined;
// 端口可收到已取消信号(例如 loading 通知期间最后订阅释放);它仍须在实际 I/O 前检查 signal。
// 每块重新检查身份,核对连续序号、稳定 token/项目/版本、权限代次和声明预算;coverage 只是合法字符串集合。
// complete/coverage 的领域含义、实际请求范围和 T 的 schema 由 adapter 负责,本层不从它们推断文档闭合。
for await (const chunk of options.load(job.scope, job.controller.signal)) {
if (job.retired) return; current(job.scope);
if (!chunk || terminal || chunk.queryKey !== job.key || chunk.permissionEpoch !== job.scope.authEpoch || typeof chunk.projectId !== 'string' || !chunk.projectId
|| job.scope.projectId !== null && chunk.projectId !== job.scope.projectId || typeof chunk.snapshotToken !== 'string' || !chunk.snapshotToken
|| chunk.sequence !== job.state.chunks.length || typeof chunk.complete !== 'boolean' || !Number.isSafeInteger(chunk.byteLength) || chunk.byteLength < 0
|| !Array.isArray(chunk.coverage) || chunk.coverage.some(key => typeof key !== 'string' || !key) || new Set(chunk.coverage).size !== chunk.coverage.length
|| !chunk.serverVersions || typeof chunk.serverVersions !== 'object' || Array.isArray(chunk.serverVersions)
|| ![Object.prototype,null].includes(Object.getPrototypeOf(chunk.serverVersions))
|| Object.entries(chunk.serverVersions).some(([id, version]) => !id || !Number.isSafeInteger(version) || version < 1)) throw fault('invalid_load_chunk');
// 版本表顺序不影响相等性;同一捕获的内容版本发生变化则拒绝拼成完整结果。
const orderedVersions = Object.fromEntries(Object.entries(chunk.serverVersions).sort(([a], [b]) => a.localeCompare(b)));
if (projectId !== undefined && (chunk.projectId !== projectId || chunk.snapshotToken !== token || !equal(orderedVersions, versions))) throw fault('load_snapshot_changed');
if (job.state.chunks.length >= maxChunks || chunk.byteLength > maxBytes - job.state.byteLength) throw fault('load_response_budget');
projectId = chunk.projectId; token = chunk.snapshotToken; versions = orderedVersions; terminal = chunk.complete;
// 捕获标准元数据表/coverage,value 与其它嵌套扩展字段仍沿用端口引用,不在此深冻结任意 T。
// adapter 应在 yield 前完成 payload 校验并交出不可变值;外层 Object.freeze 不证明内部所有权。
const owned = Object.freeze({ ...chunk, serverVersions: freeze(orderedVersions), coverage: freeze([...chunk.coverage]) });
// 只追加合法块并通知可显示前缀;即使当前块 complete=true,也要等源 EOF 才能成功 ready。
job.state = Object.freeze({ ...job.state, status: job.state.chunks.length ? 'partial' : 'initial-ready', chunks: Object.freeze([...job.state.chunks, owned]),
coverage: freeze([...new Set([...job.state.coverage, ...chunk.coverage])]), byteLength: job.state.byteLength + chunk.byteLength }); notify(job);
}
if (job.retired) return; current(job.scope); if (!terminal) throw fault('incomplete_load');
job.state = Object.freeze({ ...job.state, status: 'complete' });
// 完整结果才进缓存,且三项缓存开关都开启;按条数和测量字节双重 LRU 上限淘汰。
if (maxCacheEntries && maxCacheBytes && cacheMaxAge && job.state.byteLength <= maxCacheBytes) {
removeCache(job.key); cache.set(job.key, { state: job.state, at: now() }); cacheBytes += job.state.byteLength;
while (cache.size > maxCacheEntries || cacheBytes > maxCacheBytes) removeCache(cache.keys().next().value!);
}
// 成功清理外部 abort 监听并兑现 ready,但不自动 release 句柄;后续 signal.abort 不再改变其快照。
// subscriber 仍持有共享状态,调用方应在不再使用时显式 release;已发出的快照继续描述原切点。
notify(job); for (const subscriber of job.subscribers) if (subscriber.active) { subscriber.cleanup(); subscriber.resolve(view(job, subscriber)); }
} catch (error) {
if (job.retired) return;
// 尾部失败仍保留已校验 chunks,状态 failed-with-partial;不伪造 complete,也不清掉已显示前缀。
const failure = error as { code?: string; message?: string };
job.state = Object.freeze({ ...job.state, status: job.state.chunks.length ? 'failed-with-partial' : 'failed', error: freeze({ code: typeof failure?.code === 'string' ? failure.code : 'load_failed', message: typeof failure?.message === 'string' ? failure.message : 'Load failed' }) });
notify(job); for (const subscriber of job.subscribers) if (subscriber.active) { subscriber.cleanup(); subscriber.reject(error); }
} finally {
// 迟到旧源结束时只清自己,不能误删相同 key 新订阅创建的 job;随后归还 active 并泵队列。
if (inflight.get(job.key) === job) inflight.delete(job.key);
active--; pump();
}
})();
}
}
return Object.freeze({
/** 捕获声明 scope 字段,校验身份/取消,再检查缓存并共享或新建 job;不打开 ProjectEngine。
* fresh 会淘汰该 key 的旧缓存,但仍共享已有 inflight,并不保证为每次调用发新请求。
* 缓存验证/时钟/容量等错误可同步抛出,成功才返回 ready/getSnapshot/release 句柄。
* cacheStatus 属于共享 job 建立时的读取事实,复用在途 job 不会按新订阅的缓存偏好重写它。 */
acquire(scopeInput: LoadScope, settings: { signal?: AbortSignal; onUpdate?: (snapshot: LoadSnapshot<T>) => void; cache?: 'fresh' | 'allow-validated' } = {}): LoadHandle<T> {
if(!scopeInput)throw fault('invalid_load_scope');
const scope:LoadScope=Object.freeze({accountId:scopeInput.accountId,workspaceId:scopeInput.workspaceId,projectId:scopeInput.projectId,canvasId:scopeInput.canvasId,viewKey:scopeInput.viewKey,format:scopeInput.format,queryFingerprint:scopeInput.queryFingerprint,source:scopeInput.source,authEpoch:scopeInput.authEpoch,navigationGeneration:scopeInput.navigationGeneration});
const key = loadQueryKey(scope); current(scope); if (settings.signal?.aborted) throw fault('load_aborted');
let cacheStatus: LoadSnapshot<T>['cacheStatus'] = settings.cache === 'allow-validated' ? 'miss' : 'bypassed';
let cached = cache.get(key);
// 缓存需 allow-validated、年龄有效且 acceptCached===true;时钟倒退或 fresh 都使旧缓存失效。
if (cached) {
const age = now() - cached.at;
if (age < 0 || age > cacheMaxAge || settings.cache !== 'allow-validated' || !options.acceptCached || options.acceptCached(scope, cached.state) !== true) { if(settings.cache==='allow-validated')cacheStatus='invalid';removeCache(key); cached = undefined; }
else { cacheStatus='hit';cache.delete(key); cache.set(key, cached); }
}
current(scope);
if(settings.signal?.aborted)throw fault('load_aborted');
// 已有 inflight 优先共享;新 job 的容量包含可立即开跑的空槽,generation 溢出明确拒绝。
let job = inflight.get(key);
if (!job) {
if (!cached && queue.size >= maxQueued + Math.max(0, concurrency - active)) throw fault('load_capacity');
if (generation >= Number.MAX_SAFE_INTEGER) throw fault('load_generation_exhausted');
job = { key, scope, generation: ++generation, controller: new AbortController(), subscribers: new Set(), retired: false,
state: cached ? Object.freeze({ ...cached.state, scope, generation,cacheStatus }) : Object.freeze({ scope, generation,cacheStatus,status: 'queued', chunks: Object.freeze([]), coverage: Object.freeze([]), byteLength: 0 }) };
if (!cached) { inflight.set(key, job); queue.set(job.generation, job); }
}
const shared = job; let subscriber: Subscriber;
const ready = new Promise<LoadSnapshot<T>>((resolve, reject) => { subscriber = { scope, active: true, resolve, reject, notify: settings.onUpdate, cleanup: () => settings.signal?.removeEventListener('abort', release) }; });
/** 为本订阅记录 cancelled 快照、移除监听/借用,尝试以 load_aborted 拒绝尚未兑现的 ready。
* ready 已成功/失败时 Promise 结果不变;getSnapshot 则改读此 cancelled 切点,保留已有 chunks。
* 最后借用者才 retire 共享源;取消一个订阅不会撤回其它订阅的前缀或删除成功缓存。 */
const release = () => { if (!subscriber.active) return; subscriber.cancelled=Object.freeze({...view(shared,subscriber),status:'cancelled'});subscriber.active = false; subscriber.cleanup(); shared.subscribers.delete(subscriber); subscriber.reject(fault('load_aborted')); if (!shared.subscribers.size) retire(shared); };
shared.subscribers.add(subscriber!); settings.signal?.addEventListener('abort', release, { once: true });
// 缓存命中的句柄不登记进 inflight,ready 立即兑现,外部 abort 监听仍保留到 release。
// 因此 close 负责清共享缓存,却不追溯取消这种已返回句柄;调用方仍拥有其只读快照。
if (cached) { subscriber!.resolve(view(shared, subscriber!)); notifyOne(shared, subscriber!); } else { notifyOne(shared, subscriber!); pump(); }
return Object.freeze({ ready, getSnapshot: () => subscriber.cancelled??view(shared,subscriber), release });
},
/** 永久关闭:只对当前 inflight 的订阅记录 cancelled 并以 loader_closed 拒绝,随后清 queue/cache。
* 不追溯修改已从 inflight 退出的终态句柄或缓存命中句柄;其旧快照仍可读,显式 release 仍可调用。
* 不等待底层迭代器退出,active 在各 finally 才归还;无视 abort 的源仍可能占着资源,但迟到块不被采纳。 */
close() {
if (closed) return; closed = true;
for (const job of [...inflight.values()]) { retire(job); for (const subscriber of job.subscribers) if (subscriber.active) { subscriber.cancelled=Object.freeze({...view(job,subscriber),status:'cancelled'});subscriber.active = false; subscriber.cleanup(); subscriber.reject(fault('loader_closed')); } job.subscribers.clear(); }
queue.clear(); cache.clear(); cacheBytes = 0;
},
});
}
/** 公共泛型读取器 API 由工厂推导,加载结果仍需协议层转换为具体 canonical 数据。 */
export type ScopedLoader<T> = ReturnType<typeof createScopedLoader<T>>;