@zhin.js/host-http 1.0.14 → 1.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/host-http",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Minimal HTTP and WebSocket host for Plugin Runtime (no Koa)",
   "type": "module",
   "main": "./lib/index.js",

package/src/console-events.ts

@@ -7,6 +7,7 @@ import type {
   ConsoleEventPayloadMap,
   KnownConsoleEventType,
 } from '@zhin.js/console-protocol';
+import { createToken } from '@zhin.js/plugin-runtime';
 
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
@@ -27,12 +28,17 @@ export interface ConsoleEventHub {
     Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
   >;
   history(query?: ConsoleEventHistoryQuery): ConsoleEventHistoryPage;
+  /** In-process delivery for trusted Host bridges such as Device Protocol. */
+  listen(listener: (event: ConsoleEventEnvelope) => void): () => void;
   /** Atomically replay the resumable suffix, then join live fan-out. */
   subscribe(response: ServerResponse, options?: ConsoleEventSubscriptionOptions): () => void;
   readonly runtimeId: string;
   readonly subscriberCount: number;
 }
 
+/** Shared Console event authority installed by the Plugin Runtime composition root. */
+export const consoleEventHubToken = createToken<ConsoleEventHub>('zhin.host.console-events');
+
 export interface ConsoleEventHubOptions {
   readonly runtimeId?: string;
   readonly historyLimit?: number;
@@ -65,6 +71,7 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
   const journal: JournalEntry[] = [];
   let journalBytes = 0;
   const subscribers = new Set<ServerResponse>();
+  const listeners = new Set<(event: ConsoleEventEnvelope) => void>();
 
   const remove = (response: ServerResponse): void => {
     subscribers.delete(response);
@@ -120,6 +127,9 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
           remove(response);
         }
       }
+      for (const listener of [...listeners]) {
+        try { listener(event); } catch { /* isolate trusted bridge failures */ }
+      }
       return event as ConsoleEventEnvelope<
         Type,
         Type extends KnownConsoleEventType ? ConsoleEventPayloadMap[Type] : unknown
@@ -158,6 +168,10 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
         gap,
       });
     },
+    listen(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
     subscribe(response, options = {}) {
       // Replay and subscription are synchronous relative to publish(), closing
       // the race between HTTP recovery and the live stream hand-off.

package/src/console-rpc-extended.ts

@@ -66,6 +66,15 @@ export interface ConsoleRpcExtendedCtx {
 }
 
 export interface ConsoleWorkroomProfileControlPort {
+  getPlanningStatus(projectId: string,
+    authenticatedPrincipal?: Readonly<{ principalId: string }>): Promise<unknown>;
+  bootstrapPlanning(command: Readonly<{
+    operationId: string;
+    projectId: string;
+    expectedRegistryRevision: number;
+    includeTools?: readonly string[];
+    includeSkills?: readonly string[];
+  }>, authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
   publishPack(command: Readonly<{ operationId: string; pack: unknown }>,
     authenticatedPrincipal: Readonly<{ principalId: string }>): Promise<unknown>;
   publishProfile(command: Readonly<{
@@ -208,6 +217,8 @@ export async function dispatchExtendedConsoleRpc(
       return listInbox(d, ctx, TABLE_NOTICE, 'notices', mapNoticeRow);
     case 'inbox.messages':
       return listInboxMessages(d, ctx);
+    case 'inbox.recent':
+      return listRecentInboxMessages(d, ctx);
 
     case 'request.approve':
     case 'request.reject':
@@ -258,6 +269,8 @@ export async function dispatchExtendedConsoleRpc(
     case 'endpoint.delete_friend':
       return deleteFriend(d, ctx);
 
+    case 'workroom.profile.status':
+    case 'workroom.profile.bootstrap':
     case 'workroom.profile.pack.publish':
     case 'workroom.profile.publish':
     case 'workroom.profile.rollback':
@@ -275,7 +288,8 @@ export async function dispatchExtendedConsoleRpc(
 }
 
 async function mutateWorkroomProfile(
-  type: 'workroom.profile.pack.publish' | 'workroom.profile.publish'
+  type: 'workroom.profile.status' | 'workroom.profile.bootstrap'
+    | 'workroom.profile.pack.publish' | 'workroom.profile.publish'
     | 'workroom.profile.rollback' | 'workroom.profile.policy.publish',
   data: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
@@ -287,10 +301,36 @@ async function mutateWorkroomProfile(
   ]) {
     if (forbidden in data) return { error: `Console Workroom Profile request cannot carry ${forbidden}` };
   }
+  if (type === 'workroom.profile.status') {
+    try {
+      return { data: await control.getPlanningStatus(
+        requiredRpcText(data.projectId, 'projectId'),
+        ctx.authenticatedPrincipal,
+      ) };
+    } catch (error) {
+      return { error: errorMessage(error) };
+    }
+  }
   const principal = ctx.authenticatedPrincipal;
   if (!principal) return { error: 'Workroom Profile control requires an authenticated principal' };
   try {
     const operationId = requiredRpcText(data.operationId, 'operationId');
+    if (type === 'workroom.profile.bootstrap') {
+      const projectId = requiredRpcText(data.projectId, 'projectId');
+      const includeTools = optionalRpcTextArray(data.includeTools, 'includeTools');
+      const includeSkills = optionalRpcTextArray(data.includeSkills, 'includeSkills');
+      return { data: await control.bootstrapPlanning(Object.freeze({
+        operationId,
+        projectId,
+        expectedRegistryRevision: requiredRpcInteger(
+          data.expectedRegistryRevision,
+          'expectedRegistryRevision',
+          -1,
+        ),
+        ...(includeTools ? { includeTools } : {}),
+        ...(includeSkills ? { includeSkills } : {}),
+      }), principal) };
+    }
     if (type === 'workroom.profile.pack.publish') {
       return { data: await control.publishPack(Object.freeze({ operationId, pack: requiredRpcValue(data.pack, 'pack') }), principal) };
     }
@@ -374,6 +414,14 @@ function optionalRpcText(value: unknown, name: string): string | undefined {
   return value === undefined ? undefined : requiredRpcText(value, name);
 }
 
+function optionalRpcTextArray(value: unknown, name: string): readonly string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new Error(`${name} is invalid`);
+  const result = value.map((item, index) => requiredRpcText(item, `${name}.${index}`));
+  if (new Set(result).size !== result.length) throw new Error(`${name} contains duplicates`);
+  return Object.freeze(result);
+}
+
 function requiredRpcInteger(value: unknown, name: string, minimum = 1): number {
   if (!Number.isSafeInteger(value) || Number(value) < minimum) throw new Error(`${name} is invalid`);
   return Number(value);
@@ -673,6 +721,51 @@ async function listInboxMessages(
   return { data: { messages, inboxEnabled: enabled } };
 }
 
+/**
+ * Cross-endpoint recent inbox used by paired Mobile Console clients.
+ * Unlike endpoint-detail `inbox.messages`, every row carries its complete
+ * routable address so selecting a conversation can safely call
+ * `endpoint.send_message` through the Device Protocol write allowlist.
+ */
+async function listRecentInboxMessages(
+  d: Record<string, unknown>,
+  ctx: ConsoleRpcExtendedCtx,
+): Promise<ExtendedRpcResult> {
+  const limit = boundedIntegerField(d, 50, 1, 100, '$limit', 'limit');
+  const [messagePage, requestPage] = await Promise.all([
+    readInboxRows(ctx, TABLE_MESSAGE, {}, {
+      orderBy: {field: 'created_at', direction: 'DESC'}, limit,
+    }),
+    readInboxRows(ctx, TABLE_REQUEST, {resolved: 0}, {
+      orderBy: {field: 'created_at', direction: 'DESC'}, limit,
+    }),
+  ]);
+  const messages = messagePage.rows
+    .slice()
+    .sort((left, right) => Number(right.created_at ?? 0) - Number(left.created_at ?? 0))
+    .slice(0, limit)
+    .map(row => ({
+      id: row.id,
+      adapter: row.adapter,
+      endpoint_id: row.endpoint_id,
+      platform_message_id: row.platform_message_id,
+      sender_id: row.sender_id,
+      sender_name: row.sender_name,
+      content: row.content,
+      raw: row.raw,
+      created_at: row.created_at,
+      channel: channelFromStoredRow(row),
+      parent: parentFromStoredRow(row),
+    }));
+  const requests = requestPage.rows
+    .filter(row => Number(row.resolved ?? 0) === 0)
+    .slice()
+    .sort((left, right) => Number(right.created_at ?? 0) - Number(left.created_at ?? 0))
+    .slice(0, limit)
+    .map(row => ({...mapRequestRow(row), adapter: row.adapter, endpoint_id: row.endpoint_id}));
+  return {data: {messages, requests, inboxEnabled: messagePage.enabled || requestPage.enabled}};
+}
+
 function mapRequestRow(row: Record<string, unknown>): Record<string, unknown> {
   const actorId = row.actor_id;
   const actorName = row.actor_name ?? undefined;
@@ -790,6 +883,12 @@ async function actOnRequest(
       ? strField(d, '$remark', 'remark')
       : strField(d, '$reason', 'reason');
     await method.call(management, requestId, extra || undefined);
+    const model = getInboxModel(ctx, TABLE_REQUEST);
+    if (model && typeof model.update === 'function') {
+      await model.update({resolved: 1, resolved_at: Date.now()}).where({
+        adapter, endpoint_id: endpointKey, platform_request_id: requestId,
+      });
+    }
     return { data: { success: true } };
   });
 }

package/src/console-rpc.ts

@@ -81,6 +81,11 @@ export type RuntimeConsoleRpcContext = {
    * Returns whether a process restart is required (always true without ConfigFeature).
    */
   setConfigKey?(pluginName: string, data: unknown): Promise<{ restartRequired: boolean }>;
+  /** Persist a declared child Plugin lifecycle state. Takes effect after restart. */
+  setPluginEnabled?(
+    instanceKey: string,
+    enabled: boolean,
+  ): Promise<Readonly<{ disabled: readonly string[] }>>;
   /** Atomic, revision-checked runtime Workroom Catalog read/write. */
   readWorkroomCatalog?(): Promise<Readonly<{
     agents: Readonly<Record<string, unknown>>;
@@ -754,6 +759,41 @@ export async function dispatchRuntimeConsoleRpc(
       }
       return payloads;
     }
+    case 'plugin:set-enabled': {
+      try {
+        const instanceKey = typeof message.instanceKey === 'string' ? message.instanceKey : '';
+        const enabled = message.enabled;
+        if (!instanceKey || typeof enabled !== 'boolean') {
+          emit({ requestId, error: 'instanceKey and boolean enabled are required' });
+          return payloads;
+        }
+        if (!ctx.setPluginEnabled) {
+          emit({ requestId, error: 'Plugin lifecycle management is not configured' });
+          return payloads;
+        }
+        const lifecycle = await ctx.setPluginEnabled(instanceKey, enabled);
+        ctx.publishEvent?.('plugin:lifecycle-updated', { instanceKey, enabled });
+        emit({
+          requestId,
+          data: {
+            success: true,
+            instanceKey,
+            enabled,
+            disabled: lifecycle.disabled,
+            restartRequired: true,
+            message: `${instanceKey} 已${enabled ? '启用' : '停用'}，Host 正在重启`,
+          },
+        });
+        if (ctx.requestRestart) {
+          setTimeout(() => {
+            void Promise.resolve(ctx.requestRestart?.()).catch(() => undefined);
+          }, 500);
+        }
+      } catch (error) {
+        emit({ requestId, error: error instanceof Error ? error.message : String(error) });
+      }
+      return payloads;
+    }
     default:
       if (type.startsWith('db:')) {
         emit({

package/src/http-host.ts

@@ -1,9 +1,14 @@
 import {
-  createServer,
+  createServer as createHttpServer,
   type IncomingMessage,
-  type Server,
+  type Server as HttpServer,
   type ServerResponse,
 } from 'node:http';
+import {
+  createServer as createHttpsServer,
+  type Server as HttpsServer,
+  type ServerOptions as HttpsServerOptions,
+} from 'node:https';
 import type { Socket } from 'node:net';
 import { WebSocket, WebSocketServer } from 'ws';
 import { formatCompact, getLogger } from '@zhin.js/logger';
@@ -46,9 +51,29 @@ export interface WsHandle {
   close(): void;
 }
 
+export interface WsRouteOptions {
+  /**
+   * `host` applies the Host Bearer-token registry before upgrade. `protocol`
+   * leaves upgrade authentication to the registered application protocol.
+   */
+  readonly auth?: 'host' | 'protocol';
+}
+
 export interface HttpHostAddress {
   readonly host: string;
   readonly port: number;
+  readonly protocol: 'http' | 'https';
+  readonly secure: boolean;
+  readonly origin: string;
+}
+
+export interface HttpHostTlsOptions {
+  readonly key: NonNullable<HttpsServerOptions['key']>;
+  readonly cert: NonNullable<HttpsServerOptions['cert']>;
+  readonly ca?: HttpsServerOptions['ca'];
+  readonly passphrase?: string;
+  readonly minVersion?: HttpsServerOptions['minVersion'];
+  readonly ciphers?: string;
 }
 
 export interface HttpHostOptions {
@@ -67,6 +92,8 @@ export interface HttpHostOptions {
   readonly apiBase?: string;
   /** Extra HTTP path prefixes that skip auth even under `apiBase`. */
   readonly authExemptPaths?: readonly string[];
+  /** Enables HTTPS and WSS on this listener. Certificate lifecycle belongs to the process composition root. */
+  readonly tls?: HttpHostTlsOptions;
 }
 
 export type HttpHandler = (
@@ -83,7 +110,7 @@ export interface HttpRouteRegistration {
 
 /** @public Stable HTTP and WebSocket Host contract resolved through `httpHostToken`. */
 export interface HttpHost {
-  ws(path: string): WsHandle;
+  ws(path: string, options?: WsRouteOptions): WsHandle;
   route(
     method: string,
     path: string,
@@ -117,6 +144,7 @@ interface AdmissionBoundHttpHost extends HttpHost, GenerationAdmissionBindable<H
 interface WsRoute {
   readonly listener: (connection: WsConnection) => void;
   readonly admission?: GenerationAdmissionGate;
+  readonly options: WsRouteOptions;
 }
 
 /** @public Stable Plugin Runtime HTTP Host token. */
@@ -143,9 +171,13 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   let closed = false;
   let closeResult: Promise<void> | undefined;
 
-  const server: Server = createServer((request, response) => {
+  const secure = options.tls !== undefined;
+  const handleRequest = (request: IncomingMessage, response: ServerResponse): void => {
     void dispatchHttp(request, response);
-  });
+  };
+  const server: HttpServer | HttpsServer = secure
+    ? createHttpsServer(options.tls, handleRequest)
+    : createHttpServer(handleRequest);
 
   // Track live TCP sockets so close() can destroy long-lived connections
   // (SSE /api/events, keep-alive) that would otherwise block server.close().
@@ -184,7 +216,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
     handler: (request: IncomingMessage, response: ServerResponse) => {
       const hostHeader = headerValue(request.headers.host) ?? 'localhost';
-      const proto = headerValue(request.headers['x-forwarded-proto']) ?? 'http';
+      const proto = headerValue(request.headers['x-forwarded-proto']) ?? (secure ? 'https' : 'http');
       writeJson(response, 200, buildOpenApiDocument(listListedRoutes(), {
         apiBase,
         serverUrl: `${proto}://${hostHeader}`,
@@ -210,7 +242,10 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
       socket.destroy();
       return;
     }
-    const auth = authenticateUpgrade(request, pathname);
+    const protocolAuthenticated = admitted.every(({ entry }) => entry.options.auth === 'protocol');
+    const auth = protocolAuthenticated
+      ? { ok: true as const, scope: 'full' as const }
+      : authenticateUpgrade(request, pathname);
     if (!auth.ok) {
       socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
       socket.destroy();
@@ -406,6 +441,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   function registerWs(
     pathname: string,
     admission?: GenerationAdmissionGate,
+    options: WsRouteOptions = {},
   ): WsHandle {
     const normalized = normalizePath(pathname);
     let listeners = wsRoutes.get(normalized);
@@ -416,7 +452,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
     const owned = new Set<WsRoute>();
     return {
       onConnection(listener) {
-        const entry = Object.freeze({ listener, admission });
+        const entry = Object.freeze({ listener, admission, options: Object.freeze({ ...options }) });
         listeners!.add(entry);
         owned.add(entry);
         return () => {
@@ -463,7 +499,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   ): AdmissionBoundHttpHost {
     const bound: AdmissionBoundHttpHost = {
       [generationAdmissionBinder]: (next) => createBoundHost(next),
-      ws: (path) => registerWs(path, admission),
+      ws: (path, options) => registerWs(path, admission, options),
       route: (method, path, handler, meta) => registerRoute(
         method,
         path,
@@ -481,7 +517,7 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
   const runtime: ProcessHttpHost = {
     [generationAdmissionBinder]: (admission) => createBoundHost(admission),
 
-    ws: (pathname) => registerWs(pathname),
+    ws: (pathname, options) => registerWs(pathname, undefined, options),
 
     route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
 
@@ -506,9 +542,14 @@ export function createHttpHost(options: HttpHostOptions = {}): ProcessHttpHost {
           const bound = server.address();
           const listenPort = typeof bound === 'object' && bound ? bound.port : port;
           const publicHost = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
-          address = Object.freeze({ host: publicHost, port: listenPort });
+          const protocol = secure ? 'https' : 'http';
+          const originHost = publicHost.includes(':') ? `[${publicHost}]` : publicHost;
+          address = Object.freeze({
+            host: publicHost, port: listenPort, protocol, secure,
+            origin: `${protocol}://${originHost}:${listenPort}`,
+          });
           logger.info(
-            `listening http://${publicHost}:${listenPort}`
+            `listening ${address.origin}`
             + ` | routes: ${httpRoutes.length}`
             + ` | token: ${tokenRegistry.hasAnyToken()
               ? `${tokenRegistry.primaryTokenPrefixForLog()}…`

package/src/index.ts

@@ -7,22 +7,30 @@ export {
   type ProcessHttpHost,
   type HttpHostAddress,
   type HttpHostOptions,
+  type HttpHostTlsOptions,
   type HttpRouteRegistration,
   type WsConnection,
   type WsHandle,
+  type WsRouteOptions,
 } from './http-host.js';
+export {
+  createHttpHostGroup,
+  listHttpHostAddresses,
+} from './listener-group.js';
 export {
   TokenRegistry,
   extractBearerToken,
   isDemoWebSocketPath,
   type AuthenticatedTokenPrincipal,
   type AuthScope,
+  type DynamicTokenConfig,
   type ScopedTokenConfig,
   type TokenRegistryConfig,
 } from './token-registry.js';
 export { timingSafeEqualString } from './timing-safe-equal.js';
 export {
   createConsoleEventHub,
+  consoleEventHubToken,
   type ConsoleEventHub,
 } from './console-events.js';
 export {

package/src/listener-group.ts

@@ -0,0 +1,108 @@
+import {
+  bindGenerationAdmission,
+  generationAdmissionBinder,
+  type GenerationAdmissionBindable,
+  type GenerationAdmissionGate,
+} from '@zhin.js/plugin-runtime';
+import {
+  createHttpHost,
+  type HttpHost,
+  type HttpHostAddress,
+  type HttpHostOptions,
+  type HttpRouteRegistration,
+  type ProcessHttpHost,
+  type WsHandle,
+  type WsRouteOptions,
+} from './http-host.js';
+
+const addressProvider = Symbol('HttpHostAddressProvider');
+
+interface AddressAwareHttpHost {
+  readonly [addressProvider]: () => readonly HttpHostAddress[];
+}
+
+type BoundHttpHost = HttpHost & GenerationAdmissionBindable<HttpHost> & AddressAwareHttpHost;
+
+/**
+ * Runs one logical Host surface on multiple network listeners. Route and WS
+ * registration stays generation-owned and is mirrored to every listener,
+ * while `address` intentionally remains the primary/local listener.
+ */
+export function createHttpHostGroup(
+  options: readonly HttpHostOptions[],
+): ProcessHttpHost {
+  if (options.length === 0) throw new Error('HttpHostGroup requires at least one listener');
+  const listeners = options.map((entry) => createHttpHost(entry));
+
+  const createSurface = (hosts: readonly HttpHost[]): BoundHttpHost => {
+    const primary = hosts[0]!;
+    const surface: BoundHttpHost = {
+      [generationAdmissionBinder](admission: GenerationAdmissionGate): HttpHost {
+        return createSurface(hosts.map((host) => bindGenerationAdmission(host, admission)));
+      },
+      [addressProvider]: () => listeners.flatMap((host) => host.address ? [host.address] : []),
+      ws(path: string, wsOptions?: WsRouteOptions): WsHandle {
+        const handles = hosts.map((host) => host.ws(path, wsOptions));
+        return {
+          onConnection(listener) {
+            const disposers = handles.map((handle) => handle.onConnection(listener));
+            return () => { for (const dispose of disposers.reverse()) dispose(); };
+          },
+          close() { for (const handle of handles) handle.close(); },
+        };
+      },
+      route(method, path, handler, meta): HttpRouteRegistration {
+        const disposers = hosts.map((host) => host.route(method, path, handler, meta));
+        return () => { for (const dispose of disposers.reverse()) dispose(); };
+      },
+      listRoutes: () => primary.listRoutes(),
+      get address() { return primary.address; },
+      get tokenRegistry() { return primary.tokenRegistry; },
+    };
+    return Object.freeze(surface);
+  };
+
+  const surface = createSurface(listeners);
+  let closeResult: Promise<void> | undefined;
+  const runtime: ProcessHttpHost & AddressAwareHttpHost = {
+    [generationAdmissionBinder](admission: GenerationAdmissionGate): HttpHost {
+      return surface[generationAdmissionBinder](admission);
+    },
+    [addressProvider]: surface[addressProvider],
+    ws: (path, wsOptions) => surface.ws(path, wsOptions),
+    route: (method, path, handler, meta) => surface.route(method, path, handler, meta),
+    listRoutes: () => surface.listRoutes(),
+    get address() { return surface.address; },
+    get tokenRegistry() { return surface.tokenRegistry; },
+    async listen(): Promise<HttpHostAddress> {
+      try {
+        for (const listener of listeners) {
+          await listener.listen();
+        }
+      } catch (error) {
+        await Promise.allSettled([...listeners].reverse().map((listener) => listener.close()));
+        throw error;
+      }
+      return listeners[0]!.address!;
+    },
+    close(): Promise<void> {
+      closeResult ??= closeListeners(listeners);
+      return closeResult;
+    },
+  };
+  return Object.freeze(runtime);
+}
+
+/** Returns every bound listener, ordered primary/local first. */
+export function listHttpHostAddresses(host: HttpHost): readonly HttpHostAddress[] {
+  const provider = (host as Partial<AddressAwareHttpHost>)[addressProvider];
+  if (typeof provider === 'function') return Object.freeze([...provider.call(host)]);
+  return Object.freeze(host.address ? [host.address] : []);
+}
+
+async function closeListeners(listeners: readonly ProcessHttpHost[]): Promise<void> {
+  const results = await Promise.allSettled([...listeners].reverse().map((listener) => listener.close()));
+  const errors = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, 'multiple HTTP listeners failed to close');
+}