hiwork-core 0.0.30 → 0.0.37

package/lib/image-rpc.js

@@ -0,0 +1,306 @@
+/**
+ * `/hiwork-image` loopback RPC 的 Host 实现（浏览器半边 ⇄ 生图的唯一通道）。
+ *
+ * 设计要点（与 `src/voice-rpc.ts` / `src/daily-rpc.ts` 完全同构）：
+ *  - 只注册**一个** channel，五个 endpoint 的白名单在 {@link IMAGE_RPC_ENDPOINTS}，未知
+ *    endpoint 直接 `bad-request`；一个能力一个频道，`list`/`fetch`/`save` 与
+ *    `status`/`generate` 共用它（与 managed-mcp 的 snapshot/refresh/assertion 同款）；
+ *  - payload 严格校验：每个 endpoint 只放行它声明的字段与类型，任何其它字段一律
+ *    `bad-request`（拼错字段的失败方式必须是响的，不是静默用默认值）；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方只拿到端点结果，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - 网关 `GatewayError` 的稳定 code 原样透传，message 先经
+ *    {@link displayImageGatewayMessage} 消毒——baseURL / HTTP 状态码这类实现细节不进 UI；
+ *  - 其余异常收敛为通用失败（code `internal`），Host 只记日志、不把堆栈或原始消息交给客户端。
+ *
+ * 两处**与 voice 不同**的语义，都写在这里免得后来的人「对齐」掉：
+ *  1. `status` 的失败**不是错误信封**——网关故障时回落 {@link IMAGE_FALLBACK_CONFIG}
+ *     （`enabled:false`）。理由与语音逐字相同：这条端点回答的是「该不该显示生图能力」，
+ *     网关挂了就报红字，只会让一个本来就没有的功能显得像坏了；
+ *  2. `fetch` 有**体积闸**：超过 {@link MAX_IMAGE_BYTES} 直接拒绝（`IMAGE_TOO_LARGE`），
+ *     不把巨图塞进 loopback RPC 信封（语音那条的大对象在**上行**，本条的在下行）。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link ImageRpcContext} 端口，便于单测伪造。
+ */
+import { GatewayError } from "./ai-router-client.js";
+import { IMAGE_DEFAULT_SIZE, IMAGE_GENERIC_FAILURE_MESSAGE, IMAGE_SESSION_EXPIRED_MESSAGE, IMAGE_SIZES, MAX_IMAGE_BYTES, displayImageGatewayMessage, generateImageFile, readImageConfig, saveImageToWorkspace, } from "./imagegen.js";
+/** RPC 频道；必须与 client 半边 `src/client/images-data.ts` 的 `IMAGE_CHANNEL` 一致（由测试锁定）。 */
+export const IMAGE_RPC_CHANNEL = '/hiwork-image';
+/** 端点白名单：生图（`status`/`generate`）与「我的图片」画廊页（`list`/`fetch`/`save`）。 */
+export const IMAGE_RPC_ENDPOINTS = ['status', 'generate', 'list', 'fetch', 'save'];
+/** 画廊页 `list` 的分页缺省与上限（Host 侧夹紧：网关的 page_size 是它自己的缺省）。 */
+export const IMAGE_LIST_DEFAULT_PAGE = 1;
+export const IMAGE_LIST_DEFAULT_PAGE_SIZE = 20;
+export const IMAGE_LIST_MAX_PAGE_SIZE = 100;
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class ImageRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ImageRequestError';
+    }
+}
+/** 各稳定错误码的用户可见文案（与卡片侧 `IMAGE_ERROR_TEXT` 逐字对齐）。 */
+export { IMAGE_GENERIC_FAILURE_MESSAGE, IMAGE_MESSAGE_FALLBACK, IMAGE_SESSION_EXPIRED_MESSAGE, displayImageGatewayMessage, } from "./imagegen.js";
+/**
+ * `status` 端点读不到配置时的回落值（**成功信封**，见模块头注释第 1 条）：
+ * 能力消失，而不是弹一条用户看不懂的错误。
+ */
+export const IMAGE_FALLBACK_CONFIG = {
+    enabled: false,
+    model: '',
+    defaultSize: IMAGE_DEFAULT_SIZE,
+    sizes: [...IMAGE_SIZES],
+    quality: '',
+};
+/**
+ * 网关 message 消毒 / 错误码兜底文案都从 `imagegen.ts` 再导出（那里是唯一实现，
+ * 因为工具的失败收敛与这里的信封都要用它，而反向 import 会成环）。
+ *
+ * 为什么还要 `export`：`/hiwork-image` 的消费方（以及 spec §6.7 点名的用例）拿的是
+ * **频道模块**的公开面——消毒规则属于这条频道的契约，不该逼调用方去 import 服务层。
+ */
+/** 是否为白名单端点。 */
+export function isImageRpcEndpoint(endpoint) {
+    return IMAGE_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 正整数（页码 / 图片 id）；非法即 undefined。 */
+function readPositiveInt(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+/** 非空字符串（去空白后仍非空）；非法即 undefined。 */
+function readNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * payload 校验：每个 endpoint 只放行它声明的字段，其余字段 / 类型不符一律 `bad-request`。
+ *
+ * 缺省 / null 一律等价于空对象（页面挂载时 `status` 的调用就是 `{}` 或不带 payload）。
+ * **不在这里做业务校验**（prompt 长度、size 枚举由网关与 `imagegen.ts` 负责）——
+ * 这里只做协议形状，越早失败越便宜，但重复实现一遍业务规则只会多一处漂移。
+ */
+export function parseImagePayload(endpoint, raw) {
+    if (raw === undefined || raw === null) {
+        if (endpoint === 'fetch' || endpoint === 'save') {
+            throw new ImageRequestError('bad-request', '图片请求缺少图片 id。');
+        }
+        if (endpoint === 'generate')
+            throw new ImageRequestError('bad-request', '生图请求缺少 prompt。');
+        return {};
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ImageRequestError('bad-request', '图片请求参数不合法。');
+    }
+    const record = raw;
+    for (const key of Object.keys(record)) {
+        if (!allowedKeys(endpoint).includes(key)) {
+            throw new ImageRequestError('bad-request', `图片请求包含未知字段 '${key}'。`);
+        }
+    }
+    if (endpoint === 'status')
+        return {};
+    if (endpoint === 'generate') {
+        const prompt = readNonEmptyString(record.prompt);
+        if (prompt === undefined) {
+            throw new ImageRequestError('bad-request', '生图请求的 prompt 必须是非空字符串。');
+        }
+        const size = record.size;
+        if (size !== undefined && !IMAGE_SIZES.includes(String(size))) {
+            throw new ImageRequestError('bad-request', `生图请求的 size '${String(size)}' 不在允许的尺寸里。`);
+        }
+        return { prompt, ...(size === undefined ? {} : { size: String(size) }) };
+    }
+    if (endpoint === 'list') {
+        const page = record.page;
+        if (page !== undefined && readPositiveInt(page) === undefined) {
+            throw new ImageRequestError('bad-request', '图片列表的 page 必须是正整数。');
+        }
+        const pageSize = record.pageSize;
+        if (pageSize !== undefined && readPositiveInt(pageSize) === undefined) {
+            throw new ImageRequestError('bad-request', '图片列表的 pageSize 必须是正整数。');
+        }
+        return {
+            ...(page === undefined ? {} : { page: readPositiveInt(page) }),
+            ...(pageSize === undefined ? {} : { pageSize: readPositiveInt(pageSize) }),
+        };
+    }
+    const id = readPositiveInt(record.id);
+    if (id === undefined)
+        throw new ImageRequestError('bad-request', '图片请求的 id 必须是正整数。');
+    if (endpoint === 'fetch')
+        return { id };
+    const workspaceId = record.workspaceId;
+    if (workspaceId !== undefined && readNonEmptyString(workspaceId) === undefined) {
+        throw new ImageRequestError('bad-request', '保存请求的 workspaceId 必须是非空字符串。');
+    }
+    const prompt = record.prompt;
+    if (prompt !== undefined && typeof prompt !== 'string') {
+        throw new ImageRequestError('bad-request', '保存请求的 prompt 必须是字符串。');
+    }
+    return {
+        id,
+        ...(workspaceId === undefined ? {} : { workspaceId: readNonEmptyString(workspaceId) }),
+        ...(prompt === undefined ? {} : { prompt }),
+    };
+}
+/** 每个 endpoint 放行的字段集合（唯一事实源，解析与断言都读它）。 */
+function allowedKeys(endpoint) {
+    switch (endpoint) {
+        case 'status': return [];
+        case 'generate': return ['prompt', 'size'];
+        case 'list': return ['page', 'pageSize'];
+        case 'fetch': return ['id'];
+        case 'save': return ['id', 'workspaceId', 'prompt'];
+    }
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/** base64 字符串对应的解码后字节数（不实际解码；用于信封体积闸的第二道网）。 */
+function decodedByteSize(base64) {
+    return Math.floor((base64.length * 3) / 4);
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ *
+ * `status` 走 {@link readImageConfigSafe} 的**降级**分支：网关故障 → 成功信封里的
+ * `enabled:false`。「没有会话」「网关地址未配置」两条**不是**降级——那时还没有任何功能
+ * 状态可言，照常回错误信封。
+ */
+export async function handleImageEndpoint(endpoint, rawPayload, deps, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', '图片请求已取消。');
+        if (!isImageRpcEndpoint(endpoint)) {
+            throw new ImageRequestError('bad-request', `未知的生图端点 '${endpoint}'`);
+        }
+        const payload = parseImagePayload(endpoint, rawPayload);
+        const sessionCookie = await deps.resolveSession();
+        if (sessionCookie === undefined || sessionCookie === '') {
+            return failure('SESSION_EXPIRED', IMAGE_SESSION_EXPIRED_MESSAGE);
+        }
+        const gateway = deps.gateway();
+        if (gateway === undefined) {
+            return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+        }
+        if (isAborted(signal))
+            return failure('cancelled', '图片请求已取消。');
+        switch (endpoint) {
+            case 'status': return { ok: true, value: await readImageConfigSafe(deps, gateway, sessionCookie) };
+            case 'generate': return await generate(deps, gateway, sessionCookie, payload);
+            case 'list': return await list(gateway, sessionCookie, payload);
+            case 'fetch': return await fetchOne(gateway, sessionCookie, payload);
+            case 'save': return await save(deps, payload);
+        }
+    }
+    catch (error) {
+        if (error instanceof ImageRequestError)
+            return failure(error.code, error.message);
+        if (error instanceof GatewayError) {
+            // code 原样透传（稳定契约），message 消毒后再给客户端。
+            return failure(error.code, displayImageGatewayMessage(error.code, error.message));
+        }
+        deps.log?.(`hiwork-core: 生图 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return failure('internal', IMAGE_GENERIC_FAILURE_MESSAGE);
+    }
+}
+/**
+ * `status` 端点取数：**读不到配置就让能力消失**（返回 {@link IMAGE_FALLBACK_CONFIG}），
+ * 而不是回错误信封。
+ *
+ * 这条端点会被页面挂载时调一次，它的唯一用途是「该不该显示生图入口」；网关故障、
+ * 会话在途中过期、响应形状不对……对用户而言都只有同一个结论：现在用不了。
+ * 抛错误信封会让一个**默认关闭**的功能冒出红字。所以这里把全部异常咽成禁用配置，
+ * 只留一条 Host 日志（日志里也不带 cookie / 响应原文）。
+ */
+async function readImageConfigSafe(deps, gateway, sessionCookie) {
+    try {
+        // 缓存读取器（index.ts 注入）自己就是不抛的实现；这里再兜一层，防注入的实现违约。
+        const config = await (deps.imageConfig ?? ((cookie) => readImageConfig(gateway, cookie, deps.log)))(sessionCookie);
+        if (config === undefined)
+            return { ...IMAGE_FALLBACK_CONFIG };
+        return config;
+    }
+    catch (error) {
+        deps.log?.(`hiwork-core: 生图配置读取失败，按禁用回落（${error instanceof Error ? error.name : typeof error}）`);
+        return { ...IMAGE_FALLBACK_CONFIG };
+    }
+}
+/** `generate` 端点：交 `imagegen.ts` 生图 + 写盘；失败按稳定 code 回错误信封。 */
+async function generate(deps, gateway, sessionCookie, payload) {
+    const outcome = await generateImageFile({
+        resolveSession: async () => sessionCookie,
+        gateway: () => gateway,
+        ...(deps.imageConfig === undefined ? {} : { imageConfig: deps.imageConfig }),
+        ...(deps.now === undefined ? {} : { now: deps.now }),
+        ...(deps.log === undefined ? {} : { log: deps.log }),
+    }, { prompt: payload.prompt ?? '', ...(payload.size === undefined ? {} : { size: payload.size }) });
+    if (!outcome.ok)
+        return failure(outcome.code, outcome.message);
+    return { ok: true, value: outcome };
+}
+/** `list` 端点：原样透出网关分页视图（含 `size`），分页缺省与上限在 Host 侧夹紧。 */
+async function list(gateway, sessionCookie, payload) {
+    const view = await gateway.getMyImages(sessionCookie, {
+        page: payload.page ?? IMAGE_LIST_DEFAULT_PAGE,
+        pageSize: Math.min(payload.pageSize ?? IMAGE_LIST_DEFAULT_PAGE_SIZE, IMAGE_LIST_MAX_PAGE_SIZE),
+    });
+    // `file_url` 在网关客户端层已被丢弃（见 GatewayImageRow）；这里不再二次投影。
+    return { ok: true, value: view };
+}
+/** `fetch` 端点：**点哪张取哪张**，超过 20MiB 直接拒（不塞进 RPC 信封）。 */
+async function fetchOne(gateway, sessionCookie, payload) {
+    const id = payload.id;
+    if (id === undefined)
+        throw new ImageRequestError('bad-request', '图片请求缺少图片 id。');
+    const file = await gateway.fetchMyImage(sessionCookie, id);
+    if (file.byteSize > MAX_IMAGE_BYTES || decodedByteSize(file.dataBase64) > MAX_IMAGE_BYTES) {
+        return failure('IMAGE_TOO_LARGE', '生成的图片太大了，换个小一点的尺寸（如 1024x1024）');
+    }
+    return { ok: true, value: { dataBase64: file.dataBase64, mimeType: file.mimeType, byteSize: file.byteSize } };
+}
+/**
+ * `save` 端点：取本体 → 落工作区 → 回 `{ path }` 绝对路径。
+ *
+ * 两类失败都走**错误信封**（不是成功信封里的 `{ok:false}`）：页面这半边拿的是
+ * `save(id) => {path}` 一个签名（`src/client/images-data.ts` 的 `ImageDataSource`），
+ * 业务失败要在**同一处**冒出来（页面把它显示在行内红字里），成功信封里塞一个失败对象
+ * 只会让页面渲染出一个空路径。
+ *  - 网关 / 会话失败：`saveImageToWorkspace` 抛 `GatewayError` → 由
+ *    {@link handleImageEndpoint} 统一映射成稳定 code；
+ *  - 工作区不存在 / 越界 / 写盘失败：`{ok:false, code, reason}` → 这里转成同款错误信封，
+ *    code 用 `IMAGE_WORKSPACE_NOT_FOUND` / `IMAGE_SAVE_FAILED`（冻结契约，页面按 code 分支）。
+ */
+async function save(deps, payload) {
+    const id = payload.id;
+    if (id === undefined)
+        throw new ImageRequestError('bad-request', '图片请求缺少图片 id。');
+    const outcome = await saveImageToWorkspace({
+        resolveSession: deps.resolveSession,
+        gateway: deps.gateway,
+        ...(deps.workspaces === undefined ? {} : { workspaces: deps.workspaces }),
+        ...(deps.now === undefined ? {} : { now: deps.now }),
+        ...(deps.log === undefined ? {} : { log: deps.log }),
+    }, {
+        id,
+        ...(payload.workspaceId === undefined ? {} : { workspaceId: payload.workspaceId }),
+        ...(payload.prompt === undefined ? {} : { prompt: payload.prompt }),
+    });
+    if (!outcome.ok)
+        return failure(outcome.code, outcome.reason);
+    return { ok: true, value: { path: outcome.path } };
+}
+/**
+ * 注册 `/hiwork-image` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerImageRpc(ctx, deps) {
+    const handler = (endpoint, payload, signal) => handleImageEndpoint(endpoint, payload, deps, signal);
+    const remove = ctx.connection.rpc.handle(IMAGE_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}