docs(service): explain asset receipts and model stream boundaries
This commit is contained in:
@@ -18,13 +18,16 @@ function object(value: unknown): Record<string, unknown> {
|
||||
return value as Record<string, unknown>;
|
||||
}
|
||||
/** 交叉检查冻结请求与元数据载荷:一个上传操作、无canvas写入版本、固定资源身份和原字节属性。
|
||||
* 最大原件20MiB;请求body只是可恢复元数据,原始Blob通过上传FormData单独携带。 */
|
||||
* 元数据 byte_length 必须为1字节至20MiB;body 只是固定请求声明,原 Blob 经 FormData 单独携带。
|
||||
* 不改写 request.body,不在这里检查实际 Blob;JSON.parse 等异常沿调用路径处理,不执行文件保存或任务编译。 */
|
||||
function payload(request: FrozenRequest) {
|
||||
const raw = object(JSON.parse(request.body));
|
||||
if (request.kind !== 'asset.upload' || request.protocolVersion !== 2 || raw.protocol_version !== 2 || raw.request_id !== request.id || !uuid.test(request.id) || typeof raw.resource_id !== 'string' || !uuid.test(raw.resource_id) || request.operationIds.length !== 1 || raw.operation_id !== request.operationIds[0] || request.canvasIds.length || Object.keys(request.expectedVersions).length || typeof raw.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(raw.sha256) || typeof raw.byte_length !== 'number' || !Number.isSafeInteger(raw.byte_length) || raw.byte_length < 1 || raw.byte_length > 20 * 1024 * 1024 || typeof raw.name !== 'string' || !raw.name || typeof raw.mime_type !== 'string') throw fault('invalid_asset_request');
|
||||
return raw;
|
||||
}
|
||||
/** 成功状态须匹配协议/请求身份;未知回执仍为 unresolved,普通拒绝也不能证明先前上传未提交。 */
|
||||
/** applied 只在2xx+协议/requestId 匹配时成立,捕获完整 JSON 回执,资源字段再由 accept 核对。
|
||||
* 查询404+matching unknown 是可再查的 unresolved;其它4xx 可 blocked,但不能因此制造 not-applied。
|
||||
* 状态解释不解决 ledger 或更新资源,它只返回 scheduler 所需的结果描述。 */
|
||||
function status(request: FrozenRequest, response: ServiceResponse, query: boolean): OperationStatus {
|
||||
const body = object(response.body), matching = body.protocol_version === 2 && body.request_id === request.id;
|
||||
if (matching && body.status === 'applied' && response.status >= 200 && response.status < 300) {
|
||||
@@ -39,7 +42,9 @@ function status(request: FrozenRequest, response: ServiceResponse, query: boolea
|
||||
|
||||
/** Immutable bytes and a preallocated resource ID survive response loss and view changes. */
|
||||
/** 校验规范HTTPS源站,构造工作区资源服务与授权域。
|
||||
* 上传与查询复用固定身份;本地资源是否保存、任务如何排队由engine负责。 */
|
||||
* 上传与查询复用固定身份;本地文件保存与任务调度由 engine 负责,工厂不自建队列或重试 timer。
|
||||
* origin 只用于规范 sourceURL/authority;实际 HTTP 目的地由 transport 配置,不能据此参数推断 fetch 去向。
|
||||
* options.project/transport 等沿用宿主对象读取合同,应保持配置稳定,不能运行中改 project 破坏授权域/URL 一致性。 */
|
||||
export function createFoundryAssets(options: { workspaceId: Id; transport: ServiceTransport; project?: string; origin?: string; displayURL?: (id: Id) => string }): AssetPort {
|
||||
if (!uuid.test(options.workspaceId)) throw fault('invalid_service_scope');
|
||||
const origin = new URL(options.origin ?? 'https://api.foundry.entroia.com');
|
||||
@@ -48,19 +53,23 @@ export function createFoundryAssets(options: { workspaceId: Id; transport: Servi
|
||||
/** 可持久化的规范原件地址;每段编码,默认项目endoleap,不与宿主代理预览URL混用。 */
|
||||
const sourceURL = (id: Id) => `${origin.origin}/projects/${encodeURIComponent(options.project ?? 'endoleap')}/${path}/${encodeURIComponent(id)}`;
|
||||
/** 验证已应用回执和本地资源事实一致,包括操作/摘要/长度/规范URL、尺寸和允许MIME。
|
||||
* 限制正整数尺寸及4000万像素,复制并冻结结果后才能登记StoredAsset。 */
|
||||
* 限制正整数尺寸及4000万像素,捕获/冻结 asset 后返回;不在此更新 runtime、清本地原图或写共享仓库。
|
||||
* 接受服务器检测的允许图片 MIME,不要求它与原上传 mimeType 完全相同;实际像素不在此再次解码验证。 */
|
||||
const accept = (request: FrozenRequest, result: OperationStatus, resource: ResourceRecord): StoredAsset => {
|
||||
const raw = payload(request), receipt = object(result.canonical), asset = object(receipt.asset);
|
||||
if (result.outcome !== 'applied' || receipt.protocol_version !== 2 || receipt.request_id !== request.id || receipt.status !== 'applied' || resource.id !== raw.resource_id || resource.operationId !== raw.operation_id || resource.digest !== raw.sha256 || resource.byteLength !== raw.byte_length || asset.id !== resource.id || asset.url !== sourceURL(resource.id) || asset.bytes !== resource.byteLength || typeof asset.width !== 'number' || typeof asset.height !== 'number' || !Number.isSafeInteger(asset.width) || !Number.isSafeInteger(asset.height) || asset.width <= 0 || asset.height <= 0 || asset.width * asset.height > 40_000_000 || !['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(asset.mime_type as string)) throw fault('asset_receipt_mismatch');
|
||||
return freeze(JSON.parse(JSON.stringify(asset)) as StoredAsset);
|
||||
};
|
||||
/** bytes存在走POST上传,否则GET原操作回执;执行错误保留unresolved,不擅自重置资源身份。 */
|
||||
/** 带 bytes 则 POST,否则 GET 原 requestId 回执;只做单次尝试,不换资源/操作/request 身份。
|
||||
* 参数/网络/回执异常按 Error 风格 code 转 unresolved;有明确 code(除 invalid_asset_response)才附 blocked。
|
||||
* signal 传给 transport,不能抢占这里原生 Blob.arrayBuffer/crypto.digest 的执行。 */
|
||||
async function execute(request: FrozenRequest, bytes: Blob | undefined, signal: AbortSignal) {
|
||||
try {
|
||||
const raw = payload(request);
|
||||
let body: FormData | undefined;
|
||||
if (bytes) {
|
||||
// 上传前再核对真实Blob长度和SHA;这里整体读取ArrayBuffer,受20MiB上传上限,不是流式摘要。
|
||||
// 元数据长度上限已校验,但实际 bytes.size 在整体 arrayBuffer+SHA 后才比对,不是本函数读取前的硬限。
|
||||
// 正常 engine 上传路径先检查实际长度;这里不做流式摘要或内存分块,调用者不能传任意超大 Blob 期待提前拒绝。
|
||||
const digest = [...new Uint8Array(await crypto.subtle.digest('SHA-256', await bytes.arrayBuffer()))].map(value => value.toString(16).padStart(2, '0')).join('');
|
||||
if (bytes.size !== raw.byte_length || digest !== raw.sha256) throw fault('resource_bytes_mismatch');
|
||||
// FormData只携带原图和文件名;幂等请求ID及资源ID通过transport专用头发送。
|
||||
@@ -75,7 +84,8 @@ export function createFoundryAssets(options: { workspaceId: Id; transport: Servi
|
||||
}
|
||||
/** 跨项目复用的服务授权端口。resolve读取版本化元数据并核对ID/规范URL,
|
||||
* read获取原件字节;字节SHA与授权元数据的一致性由调用它的AssetDepot继续验证。
|
||||
* scope绑定源站/项目/工作区,缓存命中不能替代一次新的领用授权。 */
|
||||
* scope绑定源站/项目/工作区,缓存命中不能替代一次新的领用授权。
|
||||
* resolve 返回冻结元数据,read 返回原字节响应;不在此重新哈希/解码,权限身份与字节预算还依赖 transport 合同。 */
|
||||
const authority=Object.freeze({scope:`${origin.origin}/projects/${encodeURIComponent(options.project??'endoleap')}/${path}`,async resolve(id:Id,signal:AbortSignal){if(!uuid.test(id))throw fault('invalid_resource_id');const response=await options.transport({method:'GET',path:`${path}/metadata/${encodeURIComponent(id)}`,signal}),raw=object(response.body);if(response.status!==200)throw fault(typeof raw.error==='string'?raw.error:'asset_authorization_failed');if(raw.metadata_version!==1)throw fault('asset_metadata_interpreter_unavailable');const value={version:1 as const,authority:authority.scope,digest:raw.sha256 as string,asset:raw.asset as StoredAsset};validateSharedAsset(value);if(value.asset.id!==id||value.asset.url!==sourceURL(id))throw fault('asset_authorization_mismatch');return freeze(value);},async read(id:Id,signal:AbortSignal){if(!uuid.test(id))throw fault('invalid_resource_id');const response=await options.transport({method:'GET',path:`${path}/${encodeURIComponent(id)}`,signal,responseFormat:'asset-bytes-v1'});if(response.status!==200||!response.bytes)throw fault('asset_bytes_unavailable');return response.bytes;}});
|
||||
// 默认显示地址走同源预览代理;upload/query只委托统一执行器,不复制另一套任务状态。
|
||||
return Object.freeze({ authority, sourceURL, displayURL: options.displayURL ?? ((id: Id) => `/api/foundry/${path}/${encodeURIComponent(id)}?variant=preview`), accept,
|
||||
|
||||
Reference in New Issue
Block a user