@zhin.js/host-http 1.0.8 → 1.0.10

package/README.md

@@ -7,6 +7,11 @@ Console can register path-scoped WebSocket / HTTP routes without importing Koa o
 Root installs the host via `installResources` (see `basic/cli/src/plugin-runtime/http-host-installer.ts`
 and `console-host-installer.ts`).
 
+The composition root owns the process listener through `ProcessHttpHost`. Generation scopes receive
+only the `HttpHost` routing port: they may register HTTP/WS routes but cannot listen or close the
+shared server. Registrations are bound to generation admission, so candidate routes stay invisible
+until snapshot commit and retired routes stop matching immediately while their leases drain.
+
 ## Capabilities (this slice)
 
 - Path-scoped WebSocket upgrades (`ws(path)`)

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

@@ -11,8 +11,8 @@
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
  *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
  *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
- *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
+ * - 社交/群管：`ctx.withEndpointManagement` 在固定 generation lease 内
+ *   消费 `management` 语义端口；平台 SDK 字段归一化由 Adapter 负责。
  */
 export interface ConsoleRpcExtendedCtx {
     /** full scope 才允许写操作；demo scope 只放行只读 RPC。 */
@@ -20,10 +20,8 @@ export interface ConsoleRpcExtendedCtx {
     projectRoot: string;
     /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
     scheduleHost?: unknown;
-    /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
-    resolveEndpointManagement?: (adapter: string, endpointKey: string) => EndpointManagementPort | null | undefined;
-    /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-    resolveEndpoint?: (adapter: string, endpointKey: string) => unknown;
+    /** 在固定 generation lease 内执行一次 Endpoint 管理操作。 */
+    withEndpointManagement?: <T>(adapter: string, endpointKey: string, run: (management: EndpointManagementPort) => T | Promise<T>) => Promise<T | null>;
     /** Plugin Runtime DatabaseHost 的 models 视图。 */
     databaseHost?: {
         models: {

package/lib/console-rpc-extended.js

@@ -11,8 +11,8 @@
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
  *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
  *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
- *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
+ * - 社交/群管：`ctx.withEndpointManagement` 在固定 generation lease 内
+ *   消费 `management` 语义端口；平台 SDK 字段归一化由 Adapter 负责。
  */
 /** 新 Runtime 统一收件箱表名（SSOT：@zhin.js/plugin-runtime inbox.js）。 */
 import { assertDemoConsoleRpcAllowed, normalizeConsoleRpcType, } from '@zhin.js/console-protocol';
@@ -398,77 +398,58 @@ async function actOnRequest(type, d, ctx) {
     if (!adapter || !endpointKey || !requestId) {
         return { error: '$adapter, $endpoint, $id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-    if ('error' in resolved)
-        return resolved;
-    const management = resolved.management;
-    const approve = type === 'request.approve';
-    const method = approve ? management.approveRequest : management.rejectRequest;
-    if (!method) {
-        return {
-            error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
-                '且新 Runtime 尚未挂载 pending request 注册表',
-        };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const approve = type === 'request.approve';
+        const method = approve ? management.approveRequest : management.rejectRequest;
+        if (!method) {
+            return {
+                error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
+                    '且新 Runtime 尚未挂载 pending request 注册表',
+            };
+        }
         const extra = approve
             ? strField(d, '$remark', 'remark')
             : strField(d, '$reason', 'reason');
         await method.call(management, requestId, extra || undefined);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 // ---------------------------------------------------------------- 社交读取
 async function listFriends(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listFriends) {
             const friends = [...await management.listFriends()];
             return { data: { friends, count: friends.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持好友列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+    });
 }
 async function listGroups(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listGroups) {
             const groups = [...await management.listGroups()];
             return { data: { groups, count: groups.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持群列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+    });
 }
 async function listChannels(d, ctx) {
-    const resolved = requireEndpoint(d, ctx);
-    if ('error' in resolved)
-        return resolved;
-    const { management, adapter } = resolved;
-    try {
+    const endpoint = requireEndpointAddress(d);
+    if ('error' in endpoint)
+        return endpoint;
+    return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
         if (management.listChannels) {
             const channels = [...await management.listChannels()];
             return { data: { channels, count: channels.length } };
         }
-        return { error: `当前适配器（${adapter}）不支持频道列表` };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+        return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+    });
 }
 async function listGroupMembers(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
@@ -477,21 +458,14 @@ async function listGroupMembers(d, ctx) {
     if (!adapter || !endpointKey || !groupId) {
         return { error: '$adapter, $endpoint, $group_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
         const method = management.listGroupMembers;
         if (!method) {
             return { error: `当前适配器（${adapter}）不支持群成员列表` };
         }
         const members = [...await method(groupId)];
         return { data: { members, count: members.length } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 async function groupWriteOp(d, ctx, spec) {
     const adapter = strField(d, '$adapter', 'adapter');
@@ -504,15 +478,11 @@ async function groupWriteOp(d, ctx, spec) {
     if (spec.requireUser && !userId) {
         return { error: '$user_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    const method = management[spec.method];
-    if (!method) {
-        return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const method = management[spec.method];
+        if (!method) {
+            return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
+        }
         const durationRaw = d.$duration ?? d.duration;
         const enableRaw = d.$enable ?? d.enable;
         const args = spec.buildArgs(groupId, userId, {
@@ -523,10 +493,7 @@ async function groupWriteOp(d, ctx, spec) {
         });
         await method.call(management, ...args);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 async function deleteFriend(d, ctx) {
     const adapter = strField(d, '$adapter', 'adapter');
@@ -535,21 +502,14 @@ async function deleteFriend(d, ctx) {
     if (!adapter || !endpointKey || !userId) {
         return { error: '$adapter, $endpoint, $user_id required' };
     }
-    const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-    if ('error' in resolved)
-        return resolved;
-    const { management } = resolved;
-    const method = management.deleteFriend;
-    if (!method) {
-        return { error: '当前适配器暂不支持删除好友' };
-    }
-    try {
+    return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+        const method = management.deleteFriend;
+        if (!method) {
+            return { error: '当前适配器暂不支持删除好友' };
+        }
         await method(userId);
         return { data: { success: true } };
-    }
-    catch (error) {
-        return { error: errorMessage(error) };
-    }
+    });
 }
 // ---------------------------------------------------------------- helpers
 function strField(d, ...keys) {
@@ -592,35 +552,24 @@ function numArrayField(d, ...keys) {
     }
     return [];
 }
-function resolveLiveEndpoint(ctx, adapter, endpointKey) {
-    if (ctx.resolveEndpointManagement) {
-        const management = ctx.resolveEndpointManagement(adapter, endpointKey);
-        if (!management)
-            return { error: 'endpoint not found' };
-        return { management, adapter, endpointKey };
-    }
-    if (!ctx.resolveEndpoint) {
+async function withLiveEndpoint(ctx, adapter, endpointKey, run) {
+    if (!ctx.withEndpointManagement) {
         return { error: 'Endpoint registry is not configured' };
     }
-    const endpoint = ctx.resolveEndpoint(adapter, endpointKey);
-    if (!endpoint || typeof endpoint !== 'object') {
-        return { error: 'endpoint not found' };
+    try {
+        return await ctx.withEndpointManagement(adapter, endpointKey, run)
+            ?? { error: 'endpoint not found' };
+    }
+    catch (error) {
+        return { error: errorMessage(error) };
     }
-    const management = endpoint.management;
-    return {
-        management: management && typeof management === 'object'
-            ? management
-            : {},
-        adapter,
-        endpointKey,
-    };
 }
-function requireEndpoint(d, ctx) {
+function requireEndpointAddress(d) {
     const adapter = strField(d, '$adapter', 'adapter');
     const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
     if (!adapter || !endpointKey)
         return { error: '$adapter and $endpoint required' };
-    return resolveLiveEndpoint(ctx, adapter, endpointKey);
+    return { adapter, endpointKey };
 }
 function normalizeParent(raw) {
     if (!raw || typeof raw !== 'object')

package/lib/http-host.d.ts

@@ -1,5 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type WebSocket } from 'ws';
+import { WebSocket } from 'ws';
+import { type GenerationAdmissionBindable } from '@zhin.js/plugin-runtime';
 import { TokenRegistry, type AuthScope, type ScopedTokenConfig } from './token-registry.js';
 import { type ListedRoute, type RouteMeta } from './openapi.js';
 export declare const REMOTE_CONSOLE_ORIGIN = "https://console.zhin.dev";
@@ -37,14 +38,16 @@ export type HttpHandler = (request: IncomingMessage, response: ServerResponse, u
 export interface HttpRouteRegistration {
     (): void;
 }
-export interface HttpHost {
+export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
     ws(path: string): WsHandle;
     route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
     listRoutes(): readonly ListedRoute[];
-    listen(): Promise<HttpHostAddress>;
-    close(): Promise<void>;
     get address(): HttpHostAddress | undefined;
     get tokenRegistry(): TokenRegistry;
 }
+export interface ProcessHttpHost extends HttpHost {
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+}
 export declare const httpHostToken: import("@zhin.js/plugin-runtime").Token<HttpHost>;
-export declare function createHttpHost(options?: HttpHostOptions): HttpHost;
+export declare function createHttpHost(options?: HttpHostOptions): ProcessHttpHost;

package/lib/http-host.js

@@ -1,7 +1,7 @@
 import { createServer, } from 'node:http';
-import { WebSocketServer } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { createToken } from '@zhin.js/plugin-runtime';
+import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
 import { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
 import { buildOpenApiDocument, } from './openapi.js';
 import { isDemoHttpAllowed } from './console-rpc.js';
@@ -26,6 +26,7 @@ export function createHttpHost(options = {}) {
     const httpRoutes = [];
     let address;
     let closed = false;
+    let closeResult;
     const server = createServer((request, response) => {
         void dispatchHttp(request, response);
     });
@@ -78,7 +79,13 @@ export function createHttpHost(options = {}) {
         }
         const pathname = upgradePath(request.url);
         const listeners = wsRoutes.get(pathname);
-        if (!listeners || listeners.size === 0) {
+        const admitted = listeners ? [...listeners].flatMap((entry) => {
+            const release = entry.admission?.acquire();
+            if (entry.admission && !release)
+                return [];
+            return [{ entry, release }];
+        }) : [];
+        if (admitted.length === 0) {
             logger.debug(formatCompact({ op: 'ws_upgrade_unmatched', path: pathname }));
             socket.destroy();
             return;
@@ -87,20 +94,46 @@ export function createHttpHost(options = {}) {
         if (!auth.ok) {
             socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
             socket.destroy();
+            for (const item of admitted)
+                item.release?.();
             return;
         }
         try {
             wss.handleUpgrade(request, socket, head, (ws) => {
+                let settled = false;
+                const retireSubscriptions = [];
+                const releaseAdmissions = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    for (const dispose of retireSubscriptions)
+                        dispose();
+                    for (const item of admitted)
+                        item.release?.();
+                };
+                ws.once('close', releaseAdmissions);
+                ws.once('error', releaseAdmissions);
+                for (const item of admitted) {
+                    if (item.entry.admission) {
+                        retireSubscriptions.push(item.entry.admission.onDeactivate(() => {
+                            if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+                                ws.close(1012, 'Generation retired');
+                            }
+                        }));
+                    }
+                }
                 const connection = Object.freeze({
                     socket: ws,
                     request,
                     authScope: auth.scope,
                 });
-                for (const listener of listeners)
-                    listener(connection);
+                for (const item of admitted)
+                    item.entry.listener(connection);
             });
         }
         catch (err) {
+            for (const item of admitted)
+                item.release?.();
             logger.warn(formatCompact({
                 op: 'ws_upgrade_failed',
                 path: pathname,
@@ -178,7 +211,30 @@ export function createHttpHost(options = {}) {
                 applyCors(response, origin, corsOrigins);
             response.setHeader('X-Content-Type-Options', 'nosniff');
             response.setHeader('X-Frame-Options', 'SAMEORIGIN');
+            const release = route.admission?.acquire();
+            if (route.admission && !release) {
+                response.writeHead(503);
+                response.end();
+                return;
+            }
+            if (!release) {
+                await route.handler(request, response, url, auth.scope);
+                return;
+            }
+            let released = false;
+            const releaseResponse = () => {
+                if (released)
+                    return;
+                released = true;
+                response.off('finish', releaseResponse);
+                response.off('close', releaseResponse);
+                release();
+            };
+            response.once('finish', releaseResponse);
+            response.once('close', releaseResponse);
             await route.handler(request, response, url, auth.scope);
+            if (response.writableFinished || response.destroyed)
+                releaseResponse();
         }
         catch (err) {
             // 统一把请求体错误（400/413）映射回对应状态码，
@@ -219,57 +275,75 @@ export function createHttpHost(options = {}) {
         return { ok: true, scope };
     }
     function listListedRoutes() {
-        return Object.freeze(httpRoutes.map((route) => Object.freeze({
+        return Object.freeze(httpRoutes
+            .filter((route) => !route.admission || route.admission.active)
+            .map((route) => Object.freeze({
             method: route.method,
             pattern: route.pattern,
             meta: route.meta,
         })));
     }
-    return {
-        ws(pathname) {
-            const normalized = normalizePath(pathname);
-            let listeners = wsRoutes.get(normalized);
-            if (!listeners) {
-                listeners = new Set();
-                wsRoutes.set(normalized, listeners);
-            }
-            const owned = new Set();
-            return {
-                onConnection(listener) {
-                    listeners.add(listener);
-                    owned.add(listener);
-                    return () => {
-                        listeners.delete(listener);
-                        owned.delete(listener);
-                    };
-                },
-                close() {
-                    for (const listener of owned)
-                        listeners.delete(listener);
-                    owned.clear();
-                },
-            };
-        },
-        route(method, path, handler, meta) {
-            const normalizedMethod = method.toUpperCase();
-            const prefix = path.endsWith('/*');
-            const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
-            const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
-            const entry = Object.freeze({
-                method: normalizedMethod,
-                path: normalizedPath,
-                pattern,
-                prefix,
-                handler,
-                meta,
-            });
-            httpRoutes.push(entry);
-            return () => {
-                const index = httpRoutes.indexOf(entry);
-                if (index >= 0)
-                    httpRoutes.splice(index, 1);
-            };
-        },
+    function registerWs(pathname, admission) {
+        const normalized = normalizePath(pathname);
+        let listeners = wsRoutes.get(normalized);
+        if (!listeners) {
+            listeners = new Set();
+            wsRoutes.set(normalized, listeners);
+        }
+        const owned = new Set();
+        return {
+            onConnection(listener) {
+                const entry = Object.freeze({ listener, admission });
+                listeners.add(entry);
+                owned.add(entry);
+                return () => {
+                    listeners.delete(entry);
+                    owned.delete(entry);
+                };
+            },
+            close() {
+                for (const entry of owned)
+                    listeners.delete(entry);
+                owned.clear();
+            },
+        };
+    }
+    function registerRoute(method, path, handler, meta, admission) {
+        const normalizedMethod = method.toUpperCase();
+        const prefix = path.endsWith('/*');
+        const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
+        const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
+        const entry = Object.freeze({
+            method: normalizedMethod,
+            path: normalizedPath,
+            pattern,
+            prefix,
+            handler,
+            meta,
+            admission,
+        });
+        httpRoutes.push(entry);
+        return () => {
+            const index = httpRoutes.indexOf(entry);
+            if (index >= 0)
+                httpRoutes.splice(index, 1);
+        };
+    }
+    function createBoundHost(admission) {
+        const bound = {
+            [generationAdmissionBinder]: (next) => createBoundHost(next),
+            ws: (path) => registerWs(path, admission),
+            route: (method, path, handler, meta) => registerRoute(method, path, handler, meta, admission),
+            listRoutes: () => listListedRoutes(),
+            get address() { return runtime.address; },
+            get tokenRegistry() { return tokenRegistry; },
+        };
+        return Object.freeze(bound);
+    }
+    const runtime = {
+        [generationAdmissionBinder]: (admission) => createBoundHost(admission),
+        ws: (pathname) => registerWs(pathname),
+        route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
         listRoutes() {
             return listListedRoutes();
         },
@@ -302,17 +376,18 @@ export function createHttpHost(options = {}) {
             });
         },
         close() {
-            if (closed)
-                return Promise.resolve();
+            if (closeResult)
+                return closeResult;
             closed = true;
             wsRoutes.clear();
             httpRoutes.length = 0;
             // Rollback paths dispose a host whose generation never reached listen().
             if (!server.listening) {
                 address = undefined;
-                return Promise.resolve();
+                closeResult = Promise.resolve();
+                return closeResult;
             }
-            return new Promise((resolve, reject) => {
+            closeResult = new Promise((resolve, reject) => {
                 // Long-lived connections (SSE, keep-alive, WS) never end on their own:
                 // destroy tracked sockets and terminate WS clients before close(),
                 // otherwise the close callbacks would never fire.
@@ -337,8 +412,10 @@ export function createHttpHost(options = {}) {
                     });
                 });
             });
+            return closeResult;
         },
     };
+    return runtime;
 }
 function requiresHttpAuth(pathname, apiBase, authExempt) {
     if (pathname === '/pub' || pathname.startsWith('/pub/'))
@@ -378,6 +455,8 @@ function matchHttpRoute(routes, method, pathname) {
     let best;
     let bestLength = -1;
     for (const route of routes) {
+        if (route.admission && !route.admission.active)
+            continue;
         if (route.method !== method && route.method !== 'ALL')
             continue;
         if (route.prefix) {

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
+export { createHttpHost, httpHostToken, REMOTE_CONSOLE_ORIGIN, type HttpHandler, type HttpHost, type ProcessHttpHost, type HttpHostAddress, type HttpHostOptions, type HttpRouteRegistration, type WsConnection, type WsHandle, } from './http-host.js';
 export { TokenRegistry, extractBearerToken, isDemoWebSocketPath, type AuthScope, type ScopedTokenConfig, type TokenRegistryConfig, } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export { createConsoleEventHub, type ConsoleEventHub, } from './console-events.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,10 +18,10 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@zhin.js/console-protocol": "1.1.1",
+    "@zhin.js/console-protocol": "1.1.2",
     "@zhin.js/host-http-contract": "1.0.1",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/plugin-runtime": "1.1.5"
+    "@zhin.js/plugin-runtime": "1.1.6"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/console-rpc-extended.ts

@@ -11,8 +11,8 @@
  * - inbox：`ctx.databaseHost.models`（unified_inbox_message/request/notice 三张表，
  *   表不存在或查询失败 → 空数组 + inboxEnabled:false；requestConsumed/noticeConsumed
  *   按行 id update consumed=1，表/model 缺失时报"未接线"）。
- * - 社交/群管：`ctx.resolveEndpoint` 拿 live endpoint 实例，只消费其
- *   `management` 语义端口；平台 SDK 兼容与字段归一化由 Adapter 负责。
+ * - 社交/群管：`ctx.withEndpointManagement` 在固定 generation lease 内
+ *   消费 `management` 语义端口；平台 SDK 字段归一化由 Adapter 负责。
  */
 
 /** 新 Runtime 统一收件箱表名（SSOT：@zhin.js/plugin-runtime inbox.js）。 */
@@ -31,13 +31,12 @@ export interface ConsoleRpcExtendedCtx {
   projectRoot: string;
   /** Plugin Runtime ScheduleHost（basic/cli schedule-host-installer 提供）。 */
   scheduleHost?: unknown;
-  /** 经 ImRuntime / AdapterEndpointIndex 解析管理语义端口。 */
-  resolveEndpointManagement?: (
+  /** 在固定 generation lease 内执行一次 Endpoint 管理操作。 */
+  withEndpointManagement?: <T>(
     adapter: string,
     endpointKey: string,
-  ) => EndpointManagementPort | null | undefined;
-  /** @deprecated Use `resolveEndpointManagement`; accepted for one compatibility cycle. */
-  resolveEndpoint?: (adapter: string, endpointKey: string) => unknown;
+    run: (management: EndpointManagementPort) => T | Promise<T>,
+  ) => Promise<T | null>;
   /** Plugin Runtime DatabaseHost 的 models 视图。 */
   databaseHost?: { models: { get(name: string): unknown } };
   /** Agent Host 持久化调度引擎（@zhin.js/agent getAssistantRuntime().engine），未 init 时返回 null。 */
@@ -530,26 +529,21 @@ async function actOnRequest(
   if (!adapter || !endpointKey || !requestId) {
     return { error: '$adapter, $endpoint, $id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-  if ('error' in resolved) return resolved;
-  const management = resolved.management;
-  const approve = type === 'request.approve';
-  const method = approve ? management.approveRequest : management.rejectRequest;
-  if (!method) {
-    return {
-      error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
-        '且新 Runtime 尚未挂载 pending request 注册表',
-    };
-  }
-  try {
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const approve = type === 'request.approve';
+    const method = approve ? management.approveRequest : management.rejectRequest;
+    if (!method) {
+      return {
+        error: `请求审批未接线：当前平台（${adapter}）endpoint 不支持 ${approve ? 'approveRequest' : 'rejectRequest'}，` +
+          '且新 Runtime 尚未挂载 pending request 注册表',
+      };
+    }
     const extra = approve
       ? strField(d, '$remark', 'remark')
       : strField(d, '$reason', 'reason');
     await method.call(management, requestId, extra || undefined);
     return { data: { success: true } };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+  });
 }
 
 // ---------------------------------------------------------------- 社交读取
@@ -558,54 +552,45 @@ async function listFriends(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  const resolved = requireEndpoint(d, ctx);
-  if ('error' in resolved) return resolved;
-  const { management, adapter } = resolved;
-  try {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
     if (management.listFriends) {
       const friends = [...await management.listFriends()];
       return { data: { friends, count: friends.length } };
     }
-    return { error: `当前适配器（${adapter}）不支持好友列表` };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+    return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+  });
 }
 
 async function listGroups(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  const resolved = requireEndpoint(d, ctx);
-  if ('error' in resolved) return resolved;
-  const { management, adapter } = resolved;
-  try {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
     if (management.listGroups) {
       const groups = [...await management.listGroups()];
       return { data: { groups, count: groups.length } };
     }
-    return { error: `当前适配器（${adapter}）不支持群列表` };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+    return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+  });
 }
 
 async function listChannels(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
 ): Promise<ExtendedRpcResult> {
-  const resolved = requireEndpoint(d, ctx);
-  if ('error' in resolved) return resolved;
-  const { management, adapter } = resolved;
-  try {
+  const endpoint = requireEndpointAddress(d);
+  if ('error' in endpoint) return endpoint;
+  return withLiveEndpoint(ctx, endpoint.adapter, endpoint.endpointKey, async (management) => {
     if (management.listChannels) {
       const channels = [...await management.listChannels()];
       return { data: { channels, count: channels.length } };
     }
-    return { error: `当前适配器（${adapter}）不支持频道列表` };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+    return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+  });
 }
 
 async function listGroupMembers(
@@ -618,19 +603,14 @@ async function listGroupMembers(
   if (!adapter || !endpointKey || !groupId) {
     return { error: '$adapter, $endpoint, $group_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-  if ('error' in resolved) return resolved;
-  const { management } = resolved;
-  try {
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
     const method = management.listGroupMembers;
     if (!method) {
       return { error: `当前适配器（${adapter}）不支持群成员列表` };
     }
     const members = [...await method(groupId)];
     return { data: { members, count: members.length } };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+  });
 }
 
 // ---------------------------------------------------------------- 群管/好友写操作
@@ -658,14 +638,11 @@ async function groupWriteOp(
   if (spec.requireUser && !userId) {
     return { error: '$user_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-  if ('error' in resolved) return resolved;
-  const { management } = resolved;
-  const method = management[spec.method];
-  if (!method) {
-    return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
-  }
-  try {
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const method = management[spec.method];
+    if (!method) {
+      return { error: `当前适配器（${adapter}）不支持${spec.unsupported}` };
+    }
     const durationRaw = d.$duration ?? d.duration;
     const enableRaw = d.$enable ?? d.enable;
     const args = spec.buildArgs(groupId, userId, {
@@ -676,9 +653,7 @@ async function groupWriteOp(
     });
     await (method as (...args: unknown[]) => Promise<void>).call(management, ...args);
     return { data: { success: true } };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+  });
 }
 
 async function deleteFriend(
@@ -691,19 +666,14 @@ async function deleteFriend(
   if (!adapter || !endpointKey || !userId) {
     return { error: '$adapter, $endpoint, $user_id required' };
   }
-  const resolved = resolveLiveEndpoint(ctx, adapter, endpointKey);
-  if ('error' in resolved) return resolved;
-  const { management } = resolved;
-  const method = management.deleteFriend;
-  if (!method) {
-    return { error: '当前适配器暂不支持删除好友' };
-  }
-  try {
+  return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
+    const method = management.deleteFriend;
+    if (!method) {
+      return { error: '当前适配器暂不支持删除好友' };
+    }
     await method(userId);
     return { data: { success: true } };
-  } catch (error) {
-    return { error: errorMessage(error) };
-  }
+  });
 }
 
 // ---------------------------------------------------------------- helpers
@@ -746,47 +716,30 @@ function numArrayField(d: Record<string, unknown>, ...keys: string[]): number[]
   return [];
 }
 
-type ResolveOk = {
-  management: EndpointManagementPort;
-  adapter: string;
-  endpointKey: string;
-};
-
-function resolveLiveEndpoint(
+async function withLiveEndpoint(
   ctx: ConsoleRpcExtendedCtx,
   adapter: string,
   endpointKey: string,
-): ResolveOk | { error: string } {
-  if (ctx.resolveEndpointManagement) {
-    const management = ctx.resolveEndpointManagement(adapter, endpointKey);
-    if (!management) return { error: 'endpoint not found' };
-    return { management, adapter, endpointKey };
-  }
-  if (!ctx.resolveEndpoint) {
+  run: (management: EndpointManagementPort) => ExtendedRpcResult | Promise<ExtendedRpcResult>,
+): Promise<ExtendedRpcResult> {
+  if (!ctx.withEndpointManagement) {
     return { error: 'Endpoint registry is not configured' };
   }
-  const endpoint = ctx.resolveEndpoint(adapter, endpointKey);
-  if (!endpoint || typeof endpoint !== 'object') {
-    return { error: 'endpoint not found' };
+  try {
+    return await ctx.withEndpointManagement(adapter, endpointKey, run)
+      ?? { error: 'endpoint not found' };
+  } catch (error) {
+    return { error: errorMessage(error) };
   }
-  const management = (endpoint as { management?: unknown }).management;
-  return {
-    management: management && typeof management === 'object'
-      ? management as EndpointManagementPort
-      : {},
-    adapter,
-    endpointKey,
-  };
 }
 
-function requireEndpoint(
+function requireEndpointAddress(
   d: Record<string, unknown>,
-  ctx: ConsoleRpcExtendedCtx,
-): ResolveOk | { error: string } {
+): { adapter: string; endpointKey: string } | { error: string } {
   const adapter = strField(d, '$adapter', 'adapter');
   const endpointKey = strField(d, '$endpoint', 'endpointKey', 'endpoint');
   if (!adapter || !endpointKey) return { error: '$adapter and $endpoint required' };
-  return resolveLiveEndpoint(ctx, adapter, endpointKey);
+  return { adapter, endpointKey };
 }
 
 function normalizeParent(raw: unknown): { type: 'group' | 'guild'; id: string; name?: string } | undefined {

package/src/http-host.ts

@@ -5,9 +5,14 @@ import {
   type ServerResponse,
 } from 'node:http';
 import type { Socket } from 'node:net';
-import { WebSocketServer, type WebSocket } from 'ws';
+import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { createToken } from '@zhin.js/plugin-runtime';
+import {
+  createToken,
+  generationAdmissionBinder,
+  type GenerationAdmissionBindable,
+  type GenerationAdmissionGate,
+} from '@zhin.js/plugin-runtime';
 import {
   TokenRegistry,
   extractBearerToken,
@@ -74,7 +79,7 @@ export interface HttpRouteRegistration {
   (): void;
 }
 
-export interface HttpHost {
+export interface HttpHost extends GenerationAdmissionBindable<HttpHost> {
   ws(path: string): WsHandle;
   route(
     method: string,
@@ -83,12 +88,15 @@ export interface HttpHost {
     meta?: RouteMeta,
   ): HttpRouteRegistration;
   listRoutes(): readonly ListedRoute[];
-  listen(): Promise<HttpHostAddress>;
-  close(): Promise<void>;
   get address(): HttpHostAddress | undefined;
   get tokenRegistry(): TokenRegistry;
 }
 
+export interface ProcessHttpHost extends HttpHost {
+  listen(): Promise<HttpHostAddress>;
+  close(): Promise<void>;
+}
+
 interface HttpRoute {
   readonly method: string;
   readonly path: string;
@@ -96,11 +104,17 @@ interface HttpRoute {
   readonly prefix: boolean;
   readonly handler: HttpHandler;
   readonly meta?: RouteMeta;
+  readonly admission?: GenerationAdmissionGate;
+}
+
+interface WsRoute {
+  readonly listener: (connection: WsConnection) => void;
+  readonly admission?: GenerationAdmissionGate;
 }
 
 export const httpHostToken = createToken<HttpHost>('zhin.host.http');
 
-export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
+export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   const host = options.host ?? '127.0.0.1';
   const port = options.port ?? 8086;
   const apiBase = normalizePath(options.apiBase ?? '/api');
@@ -114,10 +128,11 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
     primaryToken: options.token,
     scopedTokens: options.tokens,
   } satisfies TokenRegistryConfig);
-  const wsRoutes = new Map<string, Set<(connection: WsConnection) => void>>();
+  const wsRoutes = new Map<string, Set<WsRoute>>();
   const httpRoutes: HttpRoute[] = [];
   let address: HttpHostAddress | undefined;
   let closed = false;
+  let closeResult: Promise<void> | undefined;
 
   const server: Server = createServer((request, response) => {
     void dispatchHttp(request, response);
@@ -176,7 +191,12 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
     }
     const pathname = upgradePath(request.url);
     const listeners = wsRoutes.get(pathname);
-    if (!listeners || listeners.size === 0) {
+    const admitted = listeners ? [...listeners].flatMap((entry) => {
+      const release = entry.admission?.acquire();
+      if (entry.admission && !release) return [];
+      return [{ entry, release }];
+    }) : [];
+    if (admitted.length === 0) {
       logger.debug(formatCompact({ op: 'ws_upgrade_unmatched', path: pathname }));
       socket.destroy();
       return;
@@ -185,18 +205,39 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
     if (!auth.ok) {
       socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
       socket.destroy();
+      for (const item of admitted) item.release?.();
       return;
     }
     try {
       wss.handleUpgrade(request, socket, head, (ws) => {
+        let settled = false;
+        const retireSubscriptions: Array<() => void> = [];
+        const releaseAdmissions = () => {
+          if (settled) return;
+          settled = true;
+          for (const dispose of retireSubscriptions) dispose();
+          for (const item of admitted) item.release?.();
+        };
+        ws.once('close', releaseAdmissions);
+        ws.once('error', releaseAdmissions);
+        for (const item of admitted) {
+          if (item.entry.admission) {
+            retireSubscriptions.push(item.entry.admission.onDeactivate(() => {
+              if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+              ws.close(1012, 'Generation retired');
+              }
+            }));
+          }
+        }
         const connection = Object.freeze({
           socket: ws,
           request,
           authScope: auth.scope,
         });
-        for (const listener of listeners) listener(connection);
+        for (const item of admitted) item.entry.listener(connection);
       });
     } catch (err) {
+      for (const item of admitted) item.release?.();
       logger.warn(formatCompact({
         op: 'ws_upgrade_failed',
         path: pathname,
@@ -275,7 +316,28 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
       if (corsOk && origin) applyCors(response, origin, corsOrigins);
       response.setHeader('X-Content-Type-Options', 'nosniff');
       response.setHeader('X-Frame-Options', 'SAMEORIGIN');
+      const release = route.admission?.acquire();
+      if (route.admission && !release) {
+        response.writeHead(503);
+        response.end();
+        return;
+      }
+      if (!release) {
+        await route.handler(request, response, url, auth.scope);
+        return;
+      }
+      let released = false;
+      const releaseResponse = () => {
+        if (released) return;
+        released = true;
+        response.off('finish', releaseResponse);
+        response.off('close', releaseResponse);
+        release();
+      };
+      response.once('finish', releaseResponse);
+      response.once('close', releaseResponse);
       await route.handler(request, response, url, auth.scope);
+      if (response.writableFinished || response.destroyed) releaseResponse();
     } catch (err) {
       // 统一把请求体错误（400/413）映射回对应状态码，
       // 避免个别端点未捕获时退化成 500 空响应。
@@ -322,62 +384,96 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
   }
 
   function listListedRoutes(): readonly ListedRoute[] {
-    return Object.freeze(httpRoutes.map((route) => Object.freeze({
-      method: route.method,
-      pattern: route.pattern,
-      meta: route.meta,
-    })));
+    return Object.freeze(httpRoutes
+      .filter((route) => !route.admission || route.admission.active)
+      .map((route) => Object.freeze({
+        method: route.method,
+        pattern: route.pattern,
+        meta: route.meta,
+      })));
   }
 
-  return {
-    ws(pathname: string): WsHandle {
-      const normalized = normalizePath(pathname);
-      let listeners = wsRoutes.get(normalized);
-      if (!listeners) {
-        listeners = new Set();
-        wsRoutes.set(normalized, listeners);
-      }
-      const owned = new Set<(connection: WsConnection) => void>();
-      return {
-        onConnection(listener) {
-          listeners!.add(listener);
-          owned.add(listener);
-          return () => {
-            listeners!.delete(listener);
-            owned.delete(listener);
-          };
-        },
-        close() {
-          for (const listener of owned) listeners!.delete(listener);
-          owned.clear();
-        },
-      };
-    },
+  function registerWs(
+    pathname: string,
+    admission?: GenerationAdmissionGate,
+  ): WsHandle {
+    const normalized = normalizePath(pathname);
+    let listeners = wsRoutes.get(normalized);
+    if (!listeners) {
+      listeners = new Set();
+      wsRoutes.set(normalized, listeners);
+    }
+    const owned = new Set<WsRoute>();
+    return {
+      onConnection(listener) {
+        const entry = Object.freeze({ listener, admission });
+        listeners!.add(entry);
+        owned.add(entry);
+        return () => {
+          listeners!.delete(entry);
+          owned.delete(entry);
+        };
+      },
+      close() {
+        for (const entry of owned) listeners!.delete(entry);
+        owned.clear();
+      },
+    };
+  }
 
-    route(
-      method: string,
-      path: string,
-      handler: HttpHandler,
-      meta?: RouteMeta,
-    ): HttpRouteRegistration {
-      const normalizedMethod = method.toUpperCase();
-      const prefix = path.endsWith('/*');
-      const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
-      const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
-      const entry: HttpRoute = Object.freeze({
-        method: normalizedMethod,
-        path: normalizedPath,
-        pattern,
-        prefix,
+  function registerRoute(
+    method: string,
+    path: string,
+    handler: HttpHandler,
+    meta?: RouteMeta,
+    admission?: GenerationAdmissionGate,
+  ): HttpRouteRegistration {
+    const normalizedMethod = method.toUpperCase();
+    const prefix = path.endsWith('/*');
+    const normalizedPath = normalizePath(prefix ? path.slice(0, -2) : path);
+    const pattern = prefix ? `${normalizedPath}/*` : normalizedPath;
+    const entry: HttpRoute = Object.freeze({
+      method: normalizedMethod,
+      path: normalizedPath,
+      pattern,
+      prefix,
+      handler,
+      meta,
+      admission,
+    });
+    httpRoutes.push(entry);
+    return () => {
+      const index = httpRoutes.indexOf(entry);
+      if (index >= 0) httpRoutes.splice(index, 1);
+    };
+  }
+
+  function createBoundHost(
+    admission: GenerationAdmissionGate,
+  ): HttpHost {
+    const bound: HttpHost = {
+      [generationAdmissionBinder]: (next) => createBoundHost(next),
+      ws: (path) => registerWs(path, admission),
+      route: (method, path, handler, meta) => registerRoute(
+        method,
+        path,
         handler,
         meta,
-      });
-      httpRoutes.push(entry);
-      return () => {
-        const index = httpRoutes.indexOf(entry);
-        if (index >= 0) httpRoutes.splice(index, 1);
-      };
-    },
+        admission,
+      ),
+      listRoutes: () => listListedRoutes(),
+      get address() { return runtime.address; },
+      get tokenRegistry() { return tokenRegistry; },
+    };
+    return Object.freeze(bound);
+  }
+
+  const runtime: ProcessHttpHost = {
+    [generationAdmissionBinder]: (admission) => createBoundHost(admission),
+
+    ws: (pathname) => registerWs(pathname),
+
+    route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
 
     listRoutes(): readonly ListedRoute[] {
       return listListedRoutes();
@@ -418,16 +514,17 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
     },
 
     close(): Promise<void> {
-      if (closed) return Promise.resolve();
+      if (closeResult) return closeResult;
       closed = true;
       wsRoutes.clear();
       httpRoutes.length = 0;
       // Rollback paths dispose a host whose generation never reached listen().
       if (!server.listening) {
         address = undefined;
-        return Promise.resolve();
+        closeResult = Promise.resolve();
+        return closeResult;
       }
-      return new Promise((resolve, reject) => {
+      closeResult = new Promise((resolve, reject) => {
         // Long-lived connections (SSE, keep-alive, WS) never end on their own:
         // destroy tracked sockets and terminate WS clients before close(),
         // otherwise the close callbacks would never fire.
@@ -450,8 +547,10 @@ export function createHttpHost(options: HttpHostOptions = {}): HttpHost {
           });
         });
       });
+      return closeResult;
     },
   };
+  return runtime;
 }
 
 function requiresHttpAuth(
@@ -507,6 +606,7 @@ function matchHttpRoute(routes: readonly HttpRoute[], method: string, pathname:
   let best: HttpRoute | undefined;
   let bestLength = -1;
   for (const route of routes) {
+    if (route.admission && !route.admission.active) continue;
     if (route.method !== method && route.method !== 'ALL') continue;
     if (route.prefix) {
       const matches = route.path === '/'

package/src/index.ts

@@ -4,6 +4,7 @@ export {
   REMOTE_CONSOLE_ORIGIN,
   type HttpHandler,
   type HttpHost,
+  type ProcessHttpHost,
   type HttpHostAddress,
   type HttpHostOptions,
   type HttpRouteRegistration,