@zhin.js/host-http 1.1.16 → 1.2.0

package/lib/console-events.js

@@ -16,27 +16,60 @@ export function createConsoleEventHub(options = {}) {
     const historyPageByteLimit = positiveInteger(options.historyPageByteLimit, DEFAULT_HISTORY_PAGE_BYTE_LIMIT);
     const journal = [];
     let journalBytes = 0;
-    const subscribers = new Set();
+    /**
+     * `null` while a subscriber is live. During replay catch-up it holds the frames
+     * (replay suffix, then live events) still waiting for the socket to drain.
+     */
+    const subscribers = new Map();
     const listeners = new Set();
     const remove = (response) => {
         subscribers.delete(response);
     };
-    const write = (response, entry) => {
-        let failed = false;
-        const accepted = response.write(entry.frame, (error) => {
-            if (error) {
-                failed = true;
-                remove(response);
+    const drop = (response) => {
+        remove(response);
+        response.error(new Error('Console event subscriber backpressure limit reached'));
+    };
+    /** Returns false when the consumer asks the producer to wait for drain. */
+    const write = (response, entry) => response.write(entry.frame);
+    /** Write queued frames until the socket pushes back again or the queue is empty. */
+    const flush = (response) => {
+        const pending = subscribers.get(response);
+        if (!pending)
+            return;
+        try {
+            while (pending.length > 0) {
+                if (!write(response, pending.shift())) {
+                    const stop = response.onDrain(() => {
+                        stop();
+                        flush(response);
+                    });
+                    return;
+                }
             }
-        });
-        if (failed)
-            throw new Error('Console event subscriber rejected replay');
-        if (!accepted) {
+            subscribers.set(response, null);
+        }
+        catch {
             remove(response);
-            response.destroy(new Error('Console event subscriber backpressure limit reached'));
-            throw new Error('Console event subscriber backpressure limit reached');
         }
     };
+    const deliver = (response, entry) => {
+        const pending = subscribers.get(response);
+        if (pending === undefined)
+            return;
+        if (pending === null) {
+            // A live subscriber that cannot keep up is disconnected; it resumes from history.
+            if (!write(response, entry))
+                drop(response);
+            return;
+        }
+        pending.push(entry);
+        // Catch-up may not outgrow what the journal itself is allowed to retain.
+        let bytes = 0;
+        for (const queued of pending)
+            bytes += queued.bytes;
+        if (pending.length > historyLimit || bytes > historyByteLimit)
+            drop(response);
+    };
     return {
         runtimeId,
         get subscriberCount() {
@@ -58,9 +91,9 @@ export function createConsoleEventHub(options = {}) {
             while (journal.length > historyLimit || journalBytes > historyByteLimit) {
                 journalBytes -= journal.shift()?.bytes ?? 0;
             }
-            for (const response of [...subscribers]) {
+            for (const response of [...subscribers.keys()]) {
                 try {
-                    write(response, entry);
+                    deliver(response, entry);
                 }
                 catch {
                     remove(response);
@@ -121,18 +154,11 @@ export function createConsoleEventHub(options = {}) {
                 || requestedAfter > nextId
                 ? 0
                 : requestedAfter;
-            try {
-                for (const entry of journal) {
-                    if (entry.event.eventId > after)
-                        write(response, entry);
-                }
-                subscribers.add(response);
-            }
-            catch {
-                remove(response);
-            }
-            response.once('close', () => remove(response));
-            response.once('error', () => remove(response));
+            // Backpressure during replay is expected for a large suffix: the remaining frames
+            // (and any event published meanwhile) wait in order for the socket to drain.
+            subscribers.set(response, journal.filter((entry) => entry.event.eventId > after));
+            response.onClose(() => remove(response));
+            flush(response);
             return () => remove(response);
         },
     };

package/lib/console-plugin-rpc.d.ts

@@ -1,3 +1,7 @@
 import type { RuntimeConsoleRpcContext, RuntimeConsoleRpcMessage, RuntimeConsoleRpcReply } from './console-rpc.js';
-/** Dispatches the plugin-management slice; undefined means the type belongs elsewhere. */
+/**
+ * Dispatches the plugin-management slice; undefined means the type belongs elsewhere. Package
+ * installs / updates / uninstalls are not handled in the instance: they are gateway dependency
+ * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first.
+ */
 export declare function dispatchPluginConsoleRpc(type: string, message: RuntimeConsoleRpcMessage, ctx: RuntimeConsoleRpcContext): Promise<RuntimeConsoleRpcReply | undefined>;

package/lib/console-plugin-rpc.js

@@ -1,5 +1,9 @@
 import { PLUGIN_RPC } from '@zhin.js/console-protocol';
-/** Dispatches the plugin-management slice; undefined means the type belongs elsewhere. */
+/**
+ * Dispatches the plugin-management slice; undefined means the type belongs elsewhere. Package
+ * installs / updates / uninstalls are not handled in the instance: they are gateway dependency
+ * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first.
+ */
 export async function dispatchPluginConsoleRpc(type, message, ctx) {
     const requestId = message.requestId;
     try {
@@ -71,17 +75,6 @@ export async function dispatchPluginConsoleRpc(type, message, ctx) {
                     return { requestId, error: 'Plugin management is not configured' };
                 return { requestId, data: await ctx.pluginManagement.planInstall(packageName) };
             }
-            case PLUGIN_RPC.INSTALL: {
-                const packageName = stringField(message, 'packageName');
-                if (!packageName)
-                    return { requestId, error: 'packageName is required' };
-                if (!ctx.pluginManagement?.install) {
-                    return { requestId, error: 'Plugin installation is not configured' };
-                }
-                const result = await ctx.pluginManagement.install(packageName, optionalString(message.expectedRevision), optionalString(message.expectedProjectRevision));
-                ctx.publishEvent?.('plugin:installed', { packageName, restartRequired: result.restartRequired });
-                return { requestId, data: { success: true, ...result } };
-            }
             case PLUGIN_RPC.PLAN_UNINSTALL: {
                 const packageName = stringField(message, 'packageName');
                 if (!packageName)
@@ -91,18 +84,6 @@ export async function dispatchPluginConsoleRpc(type, message, ctx) {
                 }
                 return { requestId, data: await ctx.pluginManagement.planUninstall(packageName) };
             }
-            case PLUGIN_RPC.UNINSTALL: {
-                const packageName = stringField(message, 'packageName');
-                if (!packageName || stringField(message, 'confirmation') !== packageName) {
-                    return { requestId, error: 'confirmation must exactly match packageName' };
-                }
-                if (!ctx.pluginManagement?.uninstall) {
-                    return { requestId, error: 'Plugin uninstall is not configured' };
-                }
-                const result = await ctx.pluginManagement.uninstall(packageName, optionalString(message.expectedRevision), optionalString(message.expectedProjectRevision));
-                ctx.publishEvent?.('plugin:uninstalled', { packageName, restartRequired: result.restartRequired });
-                return { requestId, data: { success: true, ...result } };
-            }
             case PLUGIN_RPC.PLAN_UPDATE: {
                 const packageName = stringField(message, 'packageName');
                 const targetVersion = stringField(message, 'targetVersion');
@@ -114,22 +95,6 @@ export async function dispatchPluginConsoleRpc(type, message, ctx) {
                 }
                 return { requestId, data: await ctx.pluginManagement.planUpdate(packageName, targetVersion) };
             }
-            case PLUGIN_RPC.UPDATE: {
-                const packageName = stringField(message, 'packageName');
-                const targetVersion = stringField(message, 'targetVersion');
-                if (!packageName || !targetVersion) {
-                    return { requestId, error: 'packageName and targetVersion are required' };
-                }
-                if (!ctx.pluginManagement?.update)
-                    return { requestId, error: 'Plugin update is not configured' };
-                const result = await ctx.pluginManagement.update(packageName, targetVersion, optionalString(message.expectedRevision), optionalString(message.expectedProjectRevision));
-                ctx.publishEvent?.('plugin:updated', {
-                    packageName,
-                    version: result.installedVersion,
-                    restartRequired: result.restartRequired,
-                });
-                return { requestId, data: { success: true, ...result } };
-            }
             case PLUGIN_RPC.VALIDATE_CONFIG: {
                 const pluginName = stringField(message, 'pluginName');
                 if (!pluginName)

package/lib/console-rest-pages-helpers.d.ts

@@ -1,6 +1,6 @@
-import type { ServerResponse } from 'node:http';
 import type { HttpHost } from './http-host.js';
-import type { AuthScope } from './token-registry.js';
+/** Logs an unexpected failure server-side; clients only get a generic message. */
+export declare function logInternalError(op: string, error: unknown): void;
 import type { ConsoleRestCtx, ConsoleRestPagesOptions } from './console-rest-pages.js';
 export declare function registerIntrospectionRoutes(route: HttpHost['route'], base: string, ctx: ConsoleRestCtx, options: ConsoleRestPagesOptions): void;
 export declare function clampPositiveInt(value: number | undefined, fallback: number, ceiling: number): number;
@@ -15,9 +15,8 @@ export declare function paginateItems<T>(all: T[], page: number, pageSize: numbe
 export declare function filterByFields<T>(items: T[], filter: string | undefined, fields: Array<(item: T) => string | undefined>): T[];
 export declare function stringProp(value: unknown, key: string): string | undefined;
 export declare function parsePositiveInt(raw: string | null, fallback: number): number;
-/** 写操作门禁：demo 部署（ctx.fullScope=false）或 demo token 均 403。 */
-export declare function requireWriteScope(response: ServerResponse, ctx: ConsoleRestCtx, authScope: AuthScope): boolean;
+/** 写操作门禁：demo 部署（ctx.fullScope=false）返回 403 响应，放行时返回 undefined。 */
+export declare function requireWriteScope(ctx: ConsoleRestCtx): Response | undefined;
 export declare function decodePathParam(raw: string): string;
 export declare function trimTrailingSlashes(s: string): string;
 export declare function normalizeBase(value: string): string;
-export declare function writeJson(response: ServerResponse, status: number, body: unknown): void;

package/lib/console-rest-pages-helpers.js

@@ -1,4 +1,11 @@
 import { HttpBodyError, readJsonBody } from './json-body.js';
+import { jsonResponse } from '@zhin.js/host-http-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('console');
+/** Logs an unexpected failure server-side; clients only get a generic message. */
+export function logInternalError(op, error) {
+    logger.warn(formatCompact({ op, error: error instanceof Error ? error.message : String(error) }));
+}
 const INTROSPECTION_PAGE_SIZES = {
     commands: 25,
     middlewares: 30,
@@ -102,7 +109,7 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
         },
     ];
     for (const { kind, collect, fields } of collectors) {
-        route('GET', `${base}/introspection/${kind}`, async (_request, response, url) => {
+        route('GET', `${base}/introspection/${kind}`, async (_request, { url }) => {
             const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
             try {
                 const introspection = lease?.value.introspection;
@@ -119,16 +126,17 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
                         ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
                         : 'Agent runtime 未装配（basic/cli 未接线 acquireAgentRuntime）'
                     : undefined);
-                writeJson(response, 200, {
+                return jsonResponse(200, {
                     success: true,
                     data: { ...slice, filter, note: degradedNote },
                 });
             }
             catch (err) {
-                writeJson(response, 503, {
+                logInternalError(`introspection_${kind}_failed`, err);
+                return jsonResponse(503, {
                     success: false,
                     data: { items: [], page: 1, pageSize: 0, total: 0, totalPages: 0 },
-                    error: err instanceof Error ? err.message : String(err),
+                    error: 'Introspection unavailable',
                 });
             }
             finally {
@@ -137,28 +145,26 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
         }, { summary: `Introspection: ${kind}`, tags: ['console', 'introspection'] });
     }
     let activeComponentPreviews = 0;
-    route('POST', `${base}/introspection/components/render`, async (request, response, _url, authScope) => {
-        if (!requireWriteScope(response, ctx, authScope))
-            return;
+    route('POST', `${base}/introspection/components/render`, async (request) => {
+        const denied = requireWriteScope(ctx);
+        if (denied)
+            return denied;
         const body = (await readJsonBody(request)) ?? {};
         const requester = typeof body.requester === 'string' ? body.requester.trim() : '';
         const name = typeof body.name === 'string' ? body.name.trim() : '';
         if (!requester || !name || requester.length > 256 || name.length > 160) {
-            writeJson(response, 400, { success: false, error: '请提供有效的 requester 与 component name' });
-            return;
+            return jsonResponse(400, { success: false, error: '请提供有效的 requester 与 component name' });
         }
         const maxConcurrent = clampPositiveInt(options.componentPreviewMaxConcurrent, 2, 8);
         if (activeComponentPreviews >= maxConcurrent) {
-            writeJson(response, 503, { success: false, error: 'Component preview 正忙，请稍后重试' });
-            return;
+            return jsonResponse(503, { success: false, error: 'Component preview 正忙，请稍后重试' });
         }
         const lease = ctx.acquireAgentRuntime?.();
         const render = lease?.value.introspection?.renderComponent;
         const previewDelivery = lease?.value.introspection?.previewComponentDelivery;
         if (!lease || !render) {
             lease?.release();
-            writeJson(response, 503, { success: false, error: 'Component Runtime 未就绪' });
-            return;
+            return jsonResponse(503, { success: false, error: 'Component Runtime 未就绪' });
         }
         const controller = new AbortController();
         const timeoutMs = clampPositiveInt(options.componentPreviewTimeoutMs, 5_000, 30_000);
@@ -187,15 +193,19 @@ export function registerIntrospectionRoutes(route, base, ctx, options) {
         try {
             const preview = await raceWithAbort(renderPromise, controller.signal);
             assertPreviewOutput(preview, options.componentPreviewMaxBytes ?? 256 * 1024);
-            writeJson(response, 200, { success: true, data: { requester, name, ...preview } });
+            return jsonResponse(200, { success: true, data: { requester, name, ...preview } });
         }
         catch (error) {
             const status = error instanceof ComponentPreviewTimeoutError
                 ? 408
                 : error instanceof ComponentPreviewLimitError ? 413 : 422;
-            writeJson(response, status, {
+            // Timeout / size limit messages are ours; a component's own failure detail stays in the log.
+            const known = error instanceof ComponentPreviewTimeoutError || error instanceof ComponentPreviewLimitError;
+            if (!known)
+                logInternalError('component_preview_failed', error);
+            return jsonResponse(status, {
                 success: false,
-                error: error instanceof Error ? error.message : String(error),
+                error: known ? error.message : 'Component preview failed',
             });
         }
         finally {
@@ -280,77 +290,67 @@ export function registerAgentSessionRoutes(route, base, ctx) {
         }
         return { tree, release: () => lease.release() };
     };
-    const unavailable = (response) => {
-        writeJson(response, 503, {
+    const unavailable = (headers) => {
+        return jsonResponse(503, {
             success: false,
             error: 'Agent session tree runtime 未就绪（新 Runtime 需经 acquireAgentRuntime 装配 sessionTree）',
-        });
+        }, headers);
     };
     // HttpHost 无 `:param` 路由，用前缀路由匹配 `<sessionKey>/tree|message|leaf`。
-    route('GET', `${base}/agent/sessions/*`, async (_request, response, url) => {
+    route('GET', `${base}/agent/sessions/*`, async (_request, { url }) => {
         const messageAction = parseSessionAction(url.pathname, prefix, 'message');
-        if (messageAction)
-            response.setHeader('Cache-Control', 'no-store');
+        const headers = messageAction ? { 'cache-control': 'no-store' } : undefined;
+        const reply = (status, body) => jsonResponse(status, body, headers);
         const parsed = messageAction ?? parseSessionAction(url.pathname, prefix, 'tree');
         if (!parsed) {
-            writeJson(response, 404, { success: false, error: 'Not found' });
-            return;
+            return reply(404, { success: false, error: 'Not found' });
         }
         const messageId = Number(url.searchParams.get('messageId'));
         const expectedSessionId = url.searchParams.get('sessionId');
         if (messageAction && (!Number.isSafeInteger(messageId) || messageId < 1 || !expectedSessionId)) {
-            writeJson(response, 400, { success: false, error: '需要 sessionId 和正安全整数 messageId' });
-            return;
+            return reply(400, { success: false, error: '需要 sessionId 和正安全整数 messageId' });
         }
         const lease = acquireSessionTree();
         if (!lease) {
-            unavailable(response);
-            return;
+            return unavailable(headers);
         }
         const runtime = lease.tree;
         try {
             if (messageAction && !runtime.readBranchMessage) {
-                writeJson(response, 501, { success: false, error: '当前 Agent runtime 不支持读取完整消息' });
-                return;
+                return reply(501, { success: false, error: '当前 Agent runtime 不支持读取完整消息' });
             }
             const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
             if (messageAction) {
                 if (!sessionId) {
-                    writeJson(response, 404, { success: false, error: '未找到活跃会话' });
-                    return;
+                    return reply(404, { success: false, error: '未找到活跃会话' });
                 }
                 if (sessionId !== expectedSessionId) {
-                    writeJson(response, 409, { success: false, error: '会话已变化，请重新读取会话列表' });
-                    return;
+                    return reply(409, { success: false, error: '会话已变化，请重新读取会话列表' });
                 }
                 const text = await runtime.readBranchMessage(sessionId, messageId);
                 if (text === null) {
-                    writeJson(response, 404, { success: false, error: '未找到此会话的用户消息' });
-                    return;
+                    return reply(404, { success: false, error: '未找到此会话的用户消息' });
                 }
-                writeJson(response, 200, { success: true, data: { messageId, text } });
-                return;
+                return reply(200, { success: true, data: { messageId, text } });
             }
             if (!sessionId) {
                 if (!isRuntimeImSessionKey(parsed.sessionKey)) {
-                    writeJson(response, 404, {
+                    return reply(404, {
                         success: false,
                         error: `未找到会话：${parsed.sessionKey}`,
                     });
-                    return;
                 }
                 const knownConversation = await ctx.isKnownConversationSession?.(parsed.sessionKey);
                 if (knownConversation === false) {
-                    writeJson(response, 404, {
+                    return reply(404, {
                         success: false,
                         error: `未找到会话：${parsed.sessionKey}`,
                     });
-                    return;
                 }
                 // 渠道会话与 Agent 会话的生命周期不同：用户可以先在 Console
                 // 选中一个真实渠道会话，而该会话尚未触发过 Agent。树查询是只读操作，
                 // 因而将这种正常状态返回为可渲染空态，而不是误报资源不存在。
-                writeJson(response, 200, {
+                return reply(200, {
                     success: true,
                     data: {
                         state: 'not_started',
@@ -360,11 +360,10 @@ export function registerAgentSessionRoutes(route, base, ctx) {
                         points: [],
                     },
                 });
-                return;
             }
             const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
             const points = await runtime.listBranchPoints(sessionId);
-            writeJson(response, 200, {
+            return reply(200, {
                 success: true,
                 data: {
                     state: 'active',
@@ -379,22 +378,21 @@ export function registerAgentSessionRoutes(route, base, ctx) {
             lease.release();
         }
     }, { summary: 'Get agent session tree or message', tags: ['console', 'agent'] });
-    route('POST', `${base}/agent/sessions/*`, async (request, response, url, authScope) => {
+    route('POST', `${base}/agent/sessions/*`, async (request, { url }) => {
         const parsed = parseSessionAction(url.pathname, prefix, 'leaf');
         if (!parsed) {
-            writeJson(response, 404, { success: false, error: 'Not found' });
-            return;
+            return jsonResponse(404, { success: false, error: 'Not found' });
         }
-        if (!requireWriteScope(response, ctx, authScope))
-            return;
+        const denied = requireWriteScope(ctx);
+        if (denied)
+            return denied;
         let body;
         try {
             body = (await readJsonBody(request) ?? {});
         }
         catch (error) {
             if (error instanceof HttpBodyError) {
-                writeJson(response, error.statusCode, { success: false, error: error.message });
-                return;
+                return jsonResponse(error.statusCode, { success: false, error: error.message });
             }
             throw error;
         }
@@ -405,42 +403,37 @@ export function registerAgentSessionRoutes(route, base, ctx) {
         if (messageIdRaw != null && messageIdRaw !== '') {
             const value = Number(messageIdRaw);
             if (!Number.isFinite(value) || value < 1) {
-                writeJson(response, 400, { success: false, error: 'messageId 须为正整数' });
-                return;
+                return jsonResponse(400, { success: false, error: 'messageId 须为正整数' });
             }
             messageId = value;
         }
         else if (indexRaw != null && indexRaw !== '') {
             const value = Number(indexRaw);
             if (!Number.isFinite(value) || value < 1) {
-                writeJson(response, 400, { success: false, error: 'index 须为正整数' });
-                return;
+                return jsonResponse(400, { success: false, error: 'index 须为正整数' });
             }
             branchIndex = value;
         }
         else {
-            writeJson(response, 400, { success: false, error: '需要 messageId 或 index 之一' });
-            return;
+            return jsonResponse(400, { success: false, error: '需要 messageId 或 index 之一' });
         }
         const lease = acquireSessionTree();
         if (!lease) {
-            unavailable(response);
-            return;
+            return unavailable();
         }
         const runtime = lease.tree;
         try {
             const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
             if (!sessionId) {
-                writeJson(response, 404, {
+                return jsonResponse(404, {
                     success: false,
                     error: `未找到活跃会话：${parsed.sessionKey}`,
                 });
-                return;
             }
             if (branchIndex !== undefined) {
                 const result = await runtime.jumpToBranchIndex(sessionId, branchIndex);
                 const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-                writeJson(response, result.ok ? 200 : 400, {
+                return jsonResponse(result.ok ? 200 : 400, {
                     success: result.ok,
                     message: result.message,
                     data: {
@@ -449,11 +442,10 @@ export function registerAgentSessionRoutes(route, base, ctx) {
                         activeLeafMessageId,
                     },
                 });
-                return;
             }
             const ok = await runtime.switchActiveLeaf(sessionId, messageId);
             const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-            writeJson(response, ok ? 200 : 400, {
+            return jsonResponse(ok ? 200 : 400, {
                 success: ok,
                 message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
                 data: {
@@ -531,15 +523,14 @@ export function parsePositiveInt(raw, fallback) {
 // ---------------------------------------------------------------------------
 // helpers
 // ---------------------------------------------------------------------------
-/** 写操作门禁：demo 部署（ctx.fullScope=false）或 demo token 均 403。 */
-export function requireWriteScope(response, ctx, authScope) {
-    if (ctx.fullScope && authScope === 'full')
-        return true;
-    writeJson(response, 403, {
+/** 写操作门禁：demo 部署（ctx.fullScope=false）返回 403 响应，放行时返回 undefined。 */
+export function requireWriteScope(ctx) {
+    if (ctx.fullScope)
+        return undefined;
+    return jsonResponse(403, {
         success: false,
         error: 'Demo scope: 只读访问，写操作被拒绝',
     });
-    return false;
 }
 export function decodePathParam(raw) {
     try {
@@ -560,11 +551,3 @@ export function normalizeBase(value) {
         return `/${value}`;
     return trimTrailingSlashes(value) || '/api';
 }
-export function writeJson(response, status, body) {
-    const payload = JSON.stringify(body);
-    response.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'content-length': Buffer.byteLength(payload),
-    });
-    response.end(payload);
-}