197 lines
20 KiB
TypeScript
197 lines
20 KiB
TypeScript
/**
|
||
* 作用域化只读加载调度器:同 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>>;
|