docs(canvas): explain Foundry transport model streams and service receipts
This commit is contained in:
@@ -1,3 +1,7 @@
|
||||
/**
|
||||
* Foundry 模型读取适配器,把一次服务端读取转换成 runtime LoadPort 的带作用域分块结果。
|
||||
* 优先协商 NDJSON 流,旧服务器明确返回 JSON 时复用完整模型解释器;不会为了回退再发一次相同请求。
|
||||
*/
|
||||
import { decodeModelStream } from './model-stream.ts';
|
||||
import type { Id, Registry } from '../canvas-core/types.ts';
|
||||
import { fault } from '../canvas-core/values.ts';
|
||||
@@ -6,23 +10,30 @@ import { loadQueryKey, type LoadPort } from '../canvas-runtime/loader.ts';
|
||||
import { loadFoundryModel, type ServiceTransport } from './foundry.ts';
|
||||
|
||||
/** Negotiate real streaming; older servers may explicitly return complete JSON. */
|
||||
/** 绑定工作区和 registry,返回异步分块源;只接受 Foundry canonical-project 查询范围。 */
|
||||
export function createFoundryModelLoader(options: { workspaceId: Id; registry: Registry; transport: ServiceTransport }): LoadPort<CanonicalReadUpdate> {
|
||||
return async function* (scope, signal) {
|
||||
// query scope 是缓存/权限隔离依据,不能用某工作区的 transport 为另一种查询来源提供结果。
|
||||
if (scope.workspaceId !== options.workspaceId || scope.format !== 'canonical-model-v1' || scope.source !== 'foundry' || scope.viewKey !== 'canonical-project') throw fault('invalid_model_load_scope');
|
||||
const response=await options.transport({method:'GET',path:`workspaces/${encodeURIComponent(options.workspaceId)}/materials/${encodeURIComponent(scope.canvasId)}/canvas/model`,signal,responseFormat:'model-stream-v1'});
|
||||
// 流解析器控制序列、来源 token 和 EOF;适配器再补权限代次与 queryKey,供共享 loader 拒绝过期结果。
|
||||
if(response.stream){
|
||||
if(response.status!==200)throw fault('invalid_model_stream');
|
||||
for await(const chunk of decodeModelStream(response.stream,scope.canvasId,options.registry,signal))yield Object.freeze({...chunk,serverVersions:Object.freeze(Object.fromEntries(chunk.versions)),permissionEpoch:scope.authEpoch,queryKey:loadQueryKey(scope)});
|
||||
return;
|
||||
}
|
||||
// JSON 回退仅把已有 response 注入解释器,ready 与 migration-required 是不同结果,不能把迁移要求当空文档。
|
||||
const value = await loadFoundryModel(async()=>response, options.workspaceId, scope.canvasId, options.registry, signal);
|
||||
signal.throwIfAborted();
|
||||
const projectId = value.status === 'ready' ? value.document.projectId : value.rootId;
|
||||
// 对版本排序以稳定完整 JSON 回退的快照标记;这是结果身份,不是原响应字节的密码学摘要。
|
||||
const versions = Object.fromEntries([...(value.status === 'ready' ? value.versions : value.sourceVersions)].sort(([a], [b]) => a.localeCompare(b)));
|
||||
const token = JSON.stringify([projectId, versions]);
|
||||
const payload = value.status === 'ready' ? { projectId, canvases: [...value.document.canvases.values()], elements: [...value.document.elements.values()], tombstones: [...value.document.tombstones], versions } : { projectId, versions, migrationRequired: true };
|
||||
// A serialized payload cost, not a claim about pre-parse network/heap limits.
|
||||
// byteLength 是已解析后重新序列化的 payload 成本,不能据此宣称 JSON.parse 前已有网络/堆内存硬上限。
|
||||
const byteLength = new TextEncoder().encode(JSON.stringify(payload)).byteLength;
|
||||
// 完整 JSON 一次给出 complete;迁移结果使用 migration 覆盖标记,不伪造已加载 canvas 内容。
|
||||
yield Object.freeze({ queryKey: loadQueryKey(scope), projectId, snapshotToken: token, serverVersions: Object.freeze(versions), permissionEpoch: scope.authEpoch,
|
||||
sequence: 0, coverage: Object.freeze(value.status === 'ready' ? [...value.document.canvases.keys()].map(id => `canvas:${id}`) : [`migration:${scope.canvasId}`]), complete: true, byteLength, value });
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user