@zhin.js/host-http 1.1.17 → 1.2.0

package/lib/http-host.js

@@ -1,91 +1,113 @@
-import { createServer as createHttpServer, } from 'node:http';
-import { createServer as createHttpsServer, } from 'node:https';
-import { WebSocket, WebSocketServer } from 'ws';
+/**
+ * Transport-independent HTTP/WebSocket route surface (ADR 0054 §2).
+ *
+ * Routes take a Web standard `Request` and return a `Response`; WebSocket routes
+ * receive a {@link WsConnection}. The router owns matching, CORS, Console
+ * authentication and generation admission. A transport (the in-process Node
+ * server in `@zhin.js/host-http/node`, later the gateway bridge) feeds it
+ * `Request`s and upgrade requests. Nothing here imports `node:http` or `ws`.
+ */
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { createToken, generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
-import { TokenRegistry, extractBearerToken, isDemoWebSocketPath, } from './token-registry.js';
+import { HttpBodyError, jsonResponse } from '@zhin.js/host-http-contract';
+import { TokenRegistry, extractBearerToken, } from './token-registry.js';
 import { buildOpenApiDocument, } from './openapi.js';
-import { isDemoHttpAllowed } from './console-rpc.js';
-import { HttpBodyError } from './json-body.js';
+import { auditActor, authorizeConsoleHttp, authorizeConsoleWebSocket, requestMeta, } from './access-control.js';
 const logger = getLogger('http');
 export const REMOTE_CONSOLE_ORIGIN = 'https://console.zhin.dev';
 const DEFAULT_CORS_ORIGINS = Object.freeze([REMOTE_CONSOLE_ORIGIN]);
 /** @public Stable Plugin Runtime HTTP Host token. */
 export const httpHostToken = createToken('zhin.host.http');
-/** @internal CLI composition-root factory. */
-export function createHttpHost(options = {}) {
-    const host = options.host ?? '127.0.0.1';
-    const port = options.port ?? 8086;
+const NO_PARAMS = Object.freeze({});
+export function createHttpRouter(options = {}) {
     const apiBase = normalizePath(options.apiBase ?? '/api');
     const corsOrigins = Object.freeze([
         ...new Set([...DEFAULT_CORS_ORIGINS, ...(options.corsOrigins ?? [])]),
     ]);
     const authExempt = Object.freeze((options.authExemptPaths ?? []).map((path) => normalizePath(path)));
-    const tokenRegistry = new TokenRegistry({
+    const tokenRegistry = options.tokenRegistry ?? new TokenRegistry({
         primaryToken: options.token,
-        scopedTokens: options.tokens,
     });
+    const secure = options.secure === true;
+    const readAddress = options.address ?? (() => undefined);
+    const forwarded = options.authentication === 'forwarded';
     const wsRoutes = new Map();
     const httpRoutes = [];
-    let address;
+    const changeListeners = new Set();
     let closed = false;
-    let closeResult;
-    let listenResult;
-    const secure = options.tls !== undefined;
-    const handleRequest = (request, response) => {
-        void dispatchHttp(request, response);
+    const routesChanged = () => {
+        for (const listener of [...changeListeners]) {
+            try {
+                listener();
+            }
+            catch { /* observers never break registration */ }
+        }
     };
-    const server = 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().
-    const sockets = new Set();
-    server.on('connection', (socket) => {
-        sockets.add(socket);
-        socket.once('close', () => {
-            sockets.delete(socket);
-        });
-    });
-    const wss = new WebSocketServer({ noServer: true });
-    // Built-in public health probe (parity with host-router `/pub/health`).
-    httpRoutes.push(Object.freeze({
-        method: 'GET',
-        path: '/pub/health',
-        pattern: '/pub/health',
-        prefix: false,
-        meta: Object.freeze({ summary: 'Health probe', tags: ['pub'] }),
-        handler: (_request, response) => {
-            writeJson(response, 200, {
+    if (options.builtinRoutes !== false)
+        registerBuiltinRoutes();
+    function registerBuiltinRoutes() {
+        // Built-in public health probe (parity with host-router `/pub/health`).
+        httpRoutes.push(Object.freeze({
+            method: 'GET',
+            path: '/pub/health',
+            pattern: '/pub/health',
+            prefix: false,
+            meta: Object.freeze({ summary: 'Health probe', tags: ['pub'] }),
+            handler: () => jsonResponse(200, {
                 success: true,
                 status: 'ok',
                 timestamp: new Date().toISOString(),
-            });
-        },
-    }));
-    // OpenAPI catalog (parity with host-router `/pub/openapi.json`).
-    httpRoutes.push(Object.freeze({
-        method: 'GET',
-        path: '/pub/openapi.json',
-        pattern: '/pub/openapi.json',
-        prefix: false,
-        meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
-        handler: (request, response) => {
-            const hostHeader = headerValue(request.headers.host) ?? 'localhost';
-            const proto = headerValue(request.headers['x-forwarded-proto']) ?? (secure ? 'https' : 'http');
-            writeJson(response, 200, buildOpenApiDocument(listListedRoutes(), {
-                apiBase,
-                serverUrl: `${proto}://${hostHeader}`,
-                version: process.env.npm_package_version ?? '0.0.0',
-            }));
-        },
-    }));
-    server.on('upgrade', (request, socket, head) => {
-        if (closed) {
-            socket.destroy();
+            }),
+        }));
+        // OpenAPI catalog (parity with host-router `/pub/openapi.json`).
+        httpRoutes.push(Object.freeze({
+            method: 'GET',
+            path: '/pub/openapi.json',
+            pattern: '/pub/openapi.json',
+            prefix: false,
+            meta: Object.freeze({ summary: 'OpenAPI 3.1 document', tags: ['pub'] }),
+            handler: (request) => {
+                const hostHeader = request.headers.get('host') ?? 'localhost';
+                const proto = request.headers.get('x-forwarded-proto') ?? (secure ? 'https' : 'http');
+                return jsonResponse(200, buildOpenApiDocument(listListedRoutes(), {
+                    apiBase,
+                    serverUrl: `${proto}://${hostHeader}`,
+                    version: process.env.npm_package_version ?? '0.0.0',
+                }));
+            },
+        }));
+    }
+    async function authenticateUpgrade(request, pathname) {
+        const { url, headers, remoteAddress } = request;
+        const principal = forwarded
+            ? request.principal
+            : await tokenRegistry.authenticate(extractBearerToken(headers.get('authorization') ?? undefined, url.searchParams.get('token')), requestMeta({ headers }, remoteAddress));
+        if (!principal)
+            return undefined;
+        if (!authorizeConsoleWebSocket(principal, pathname)) {
+            audit(principal, remoteAddress, `ws:${pathname}`, 'denied');
+            return undefined;
+        }
+        return principal;
+    }
+    function audit(principal, remoteAddress, action, outcome) {
+        const sink = tokenRegistry.accessProvider?.audit;
+        if (!sink)
             return;
+        try {
+            sink.call(tokenRegistry.accessProvider, {
+                actor: auditActor(principal),
+                action,
+                outcome,
+                ...(remoteAddress ? { ip: remoteAddress } : {}),
+            });
         }
-        const pathname = upgradePath(request.url);
+        catch { /* audit never breaks a request */ }
+    }
+    async function upgrade(request) {
+        if (closed)
+            return Object.freeze({ accepted: false, status: 404 });
+        const pathname = normalizePath(request.url.pathname);
         const listeners = wsRoutes.get(pathname);
         const admitted = listeners ? [...listeners].flatMap((entry) => {
             const release = entry.admission?.acquire();
@@ -95,42 +117,50 @@ export function createHttpHost(options = {}) {
         }) : [];
         if (admitted.length === 0) {
             logger.debug(formatCompact({ op: 'ws_upgrade_unmatched', path: pathname }));
-            socket.destroy();
-            return;
+            return Object.freeze({ accepted: false, status: 404 });
         }
-        const protocolAuthenticated = admitted.every(({ entry }) => entry.options.auth === 'protocol');
-        const auth = protocolAuthenticated
-            ? { ok: true, scope: 'full' }
-            : authenticateUpgrade(request, pathname);
-        if (!auth.ok) {
-            socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
-            socket.destroy();
+        let settled = false;
+        const releaseAll = () => {
+            if (settled)
+                return;
+            settled = true;
             for (const item of admitted)
                 item.release?.();
-            return;
+        };
+        const protocolAuthenticated = admitted.every(({ entry }) => entry.options.auth === 'protocol');
+        let principal;
+        if (!protocolAuthenticated) {
+            principal = await authenticateUpgrade(request, pathname).catch(() => undefined);
+            if (!principal || closed) {
+                releaseAll();
+                return Object.freeze({ accepted: false, status: 401 });
+            }
         }
-        try {
-            wss.handleUpgrade(request, socket, head, (ws) => {
-                let settled = false;
+        return Object.freeze({
+            accepted: true,
+            reject: releaseAll,
+            accept(transport) {
+                if (settled) {
+                    transport.close(1012, 'Root stopped');
+                    return;
+                }
                 const stopSubscriptions = [];
-                const releaseAdmissions = () => {
-                    if (settled)
+                let finished = false;
+                transport.onClose(() => {
+                    if (finished)
                         return;
-                    settled = true;
+                    finished = true;
                     for (const unsubscribe of stopSubscriptions)
                         unsubscribe();
-                    for (const item of admitted)
-                        item.release?.();
-                };
-                ws.once('close', releaseAdmissions);
-                ws.once('error', releaseAdmissions);
+                    releaseAll();
+                });
                 // Replacement closes new upgrades, not accepted plugin work. Explicit Root stop
                 // still closes its sockets before waiting for their admission leases to drain.
                 const stops = new Set(admitted.map(item => item.entry.admission?.stopSignal).filter(signal => signal !== undefined));
                 for (const signal of stops) {
                     const stop = () => {
-                        if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
-                            ws.close(1012, 'Root stopped');
+                        if (!finished)
+                            transport.close(1012, 'Root stopped');
                     };
                     signal.addEventListener('abort', stop, { once: true });
                     stopSubscriptions.push(() => signal.removeEventListener('abort', stop));
@@ -138,161 +168,124 @@ export function createHttpHost(options = {}) {
                         stop();
                 }
                 const connection = Object.freeze({
-                    socket: ws,
-                    request,
-                    authScope: auth.scope,
+                    url: request.url,
+                    headers: request.headers,
+                    ...(principal ? { principal } : {}),
+                    ...(request.remoteAddress ? { remoteAddress: request.remoteAddress } : {}),
+                    send: (data) => transport.send(data),
+                    close: (code, reason) => transport.close(code, reason),
+                    onMessage: (listener) => transport.onMessage(listener),
+                    onClose: (listener) => transport.onClose(listener),
+                    get bufferedAmount() { return transport.bufferedAmount; },
                 });
-                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,
-                error: err instanceof Error ? err.message : String(err),
-            }));
-            try {
-                socket.destroy();
-            }
-            catch {
-                /* already destroyed */
-            }
-        }
-    });
-    function authenticateUpgrade(request, pathname) {
-        if (!tokenRegistry.hasAnyToken())
-            return { ok: true, scope: 'full' };
-        let url;
-        try {
-            url = new URL(request.url ?? '/', 'http://localhost');
-        }
-        catch {
-            return { ok: false };
-        }
-        const token = extractBearerToken(headerValue(request.headers.authorization), url.searchParams.get('token'));
-        const scope = tokenRegistry.resolve(token);
-        if (!scope)
-            return { ok: false };
-        if (scope === 'demo' && !isDemoWebSocketPath(pathname))
-            return { ok: false };
-        return { ok: true, scope };
+                for (const item of admitted) {
+                    try {
+                        item.entry.listener(connection);
+                    }
+                    catch (error) {
+                        logger.warn(formatCompact({
+                            op: 'ws_listener_failed',
+                            path: pathname,
+                            error: error instanceof Error ? error.message : String(error),
+                        }));
+                    }
+                }
+            },
+        });
     }
-    async function dispatchHttp(request, response) {
-        if (closed) {
-            response.writeHead(503);
-            response.end();
-            return;
-        }
-        const method = (request.method ?? 'GET').toUpperCase();
+    async function handle(request, info = {}) {
+        if (closed)
+            return new Response(null, { status: 503 });
+        const method = request.method.toUpperCase();
         let url;
         try {
-            url = new URL(request.url ?? '/', 'http://localhost');
+            url = new URL(request.url);
         }
         catch {
-            response.writeHead(400);
-            response.end();
-            return;
+            return new Response(null, { status: 400 });
         }
         const pathname = normalizePath(url.pathname);
-        const origin = headerValue(request.headers.origin);
-        const corsOk = corsMatch(origin, corsOrigins);
-        if (method === 'OPTIONS') {
-            if (corsOk && origin)
-                applyCors(response, origin, corsOrigins);
-            response.writeHead(204);
-            response.end();
-            return;
-        }
-        const auth = authenticateHttp(request, url, pathname);
+        const origin = request.headers.get('origin') ?? undefined;
+        const cors = origin && corsMatch(origin, corsOrigins) ? corsHeaders(origin, corsOrigins) : undefined;
+        if (method === 'OPTIONS')
+            return withHeaders(new Response(null, { status: 204 }), cors);
+        const auth = await authenticateHttp(request, url, pathname, method, info);
         if (!auth.ok) {
-            if (corsOk && origin)
-                applyCors(response, origin, corsOrigins);
-            writeJson(response, auth.forbidden ? 403 : 401, {
+            return withHeaders(jsonResponse(auth.status, {
                 success: false,
-                code: auth.forbidden ? 'forbidden' : 'unauthorized',
+                code: auth.code,
                 requestOutcome: 'not-dispatched',
-                error: auth.forbidden ? 'Token scope does not allow this route' : 'Invalid or missing token',
-            });
-            return;
+                error: auth.error,
+            }), cors);
         }
         const route = matchHttpRoute(httpRoutes, method, pathname);
-        if (!route) {
-            if (corsOk && origin)
-                applyCors(response, origin, corsOrigins);
-            response.writeHead(404);
-            response.end();
-            return;
+        if (!route)
+            return withHeaders(new Response(null, { status: 404 }), cors);
+        const defaults = { ...cors, 'x-content-type-options': 'nosniff', 'x-frame-options': 'SAMEORIGIN' };
+        const release = route.admission?.acquire();
+        if (route.admission && !release) {
+            return withHeaders(jsonResponse(503, { success: false, code: 'unavailable', requestOutcome: 'not-dispatched' }), defaults);
         }
+        const context = Object.freeze({
+            url,
+            params: route.prefix ? Object.freeze({ '*': prefixRemainder(route.path, pathname) }) : NO_PARAMS,
+            ...(auth.principal ? { principal: auth.principal } : {}),
+            ...(info.remoteAddress ? { remoteAddress: info.remoteAddress } : {}),
+        });
+        let response;
         try {
-            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) {
-                writeJson(response, 503, { success: false, code: 'unavailable', requestOutcome: 'not-dispatched' });
-                return;
-            }
-            if (!release) {
-                await route.handler(request, response, url, auth.scope, auth.principal);
-                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, auth.principal);
-            if (response.writableFinished || response.destroyed)
-                releaseResponse();
+            response = await route.handler(request, context);
+            if (!(response instanceof Response))
+                throw new TypeError('HTTP route handler did not return a Response');
         }
         catch (err) {
+            release?.();
             // 统一把请求体错误（400/413）映射回对应状态码，
             // 避免个别端点未捕获时退化成 500 空响应。
             if (err instanceof HttpBodyError) {
-                if (!response.headersSent) {
-                    writeJson(response, err.statusCode, { success: false, error: err.message });
-                }
-                return;
+                return withHeaders(jsonResponse(err.statusCode, { success: false, error: err.message }), defaults);
             }
             logger.warn(formatCompact({
                 op: 'http_handler_failed',
                 path: pathname,
                 error: err instanceof Error ? err.message : String(err),
             }));
-            if (!response.headersSent) {
-                response.writeHead(500);
-                response.end();
-            }
+            return withHeaders(new Response(null, { status: 500 }), defaults);
         }
+        return withHeaders(response, defaults, release);
     }
-    function authenticateHttp(request, url, pathname) {
-        if (!requiresHttpAuth(pathname, apiBase, authExempt)) {
-            return { ok: true, scope: 'full' };
+    async function authenticateHttp(request, url, pathname, method, info) {
+        const remoteAddress = info.remoteAddress;
+        if (forwarded) {
+            // The gateway authenticated; authorization still happens here (ADR 0054 §3).
+            const principal = info.principal;
+            if (!requiresHttpAuth(pathname, apiBase, authExempt))
+                return { ok: true, ...(principal ? { principal } : {}) };
+            return authorizeApi(principal, method, pathname, remoteAddress);
         }
-        if (!tokenRegistry.hasAnyToken()) {
-            return { ok: true, scope: 'full' };
+        const token = extractBearerToken(request.headers.get('authorization') ?? undefined, url.searchParams.get('token'));
+        const meta = requestMeta(request, remoteAddress, { inProcess: info.inProcess === true });
+        if (!requiresHttpAuth(pathname, apiBase, authExempt)) {
+            // Public route: still attach a presented credential so page catalogs can filter by it.
+            if (token || !tokenRegistry.hasAnyToken()) {
+                const principal = await tokenRegistry.authenticate(token, meta);
+                if (principal)
+                    return { ok: true, principal };
+            }
+            return { ok: true };
         }
-        const token = extractBearerToken(headerValue(request.headers.authorization), url.searchParams.get('token'));
-        const scope = tokenRegistry.resolve(token);
-        if (!scope)
-            return { ok: false };
-        if (scope === 'demo') {
-            const method = (request.method ?? 'GET').toUpperCase();
-            if (!isDemoHttpAllowed(method, pathname, apiBase))
-                return { ok: false, forbidden: true };
+        const principal = await tokenRegistry.authenticate(token, meta) ?? undefined;
+        return authorizeApi(principal, method, pathname, remoteAddress);
+    }
+    function authorizeApi(principal, method, pathname, remoteAddress) {
+        const relative = pathname === apiBase ? '/' : pathname.slice(apiBase.length);
+        const decision = authorizeConsoleHttp(principal, method, relative);
+        if (!decision.allowed) {
+            if (principal)
+                audit(principal, remoteAddress, `http:${method} ${relative}`, 'denied');
+            return { ok: false, status: decision.status, code: decision.code, error: decision.error };
         }
-        const principal = tokenRegistry.resolvePrincipal(token);
-        return { ok: true, scope, ...(principal ? { principal } : {}) };
+        return { ok: true, ...(principal ? { principal } : {}) };
     }
     function listListedRoutes() {
         return Object.freeze(httpRoutes
@@ -303,7 +296,7 @@ export function createHttpHost(options = {}) {
             meta: route.meta,
         })));
     }
-    function registerWs(pathname, admission, options = {}) {
+    function registerWs(pathname, admission, wsOptions = {}) {
         const normalized = normalizePath(pathname);
         let listeners = wsRoutes.get(normalized);
         if (!listeners) {
@@ -313,18 +306,24 @@ export function createHttpHost(options = {}) {
         const owned = new Set();
         return {
             onConnection(listener) {
-                const entry = Object.freeze({ listener, admission, options: Object.freeze({ ...options }) });
+                const entry = Object.freeze({ listener, admission, options: Object.freeze({ ...wsOptions }) });
                 listeners.add(entry);
                 owned.add(entry);
+                routesChanged();
                 return () => {
+                    if (!owned.delete(entry))
+                        return;
                     listeners.delete(entry);
-                    owned.delete(entry);
+                    routesChanged();
                 };
             },
             close() {
+                if (owned.size === 0)
+                    return;
                 for (const entry of owned)
                     listeners.delete(entry);
                 owned.clear();
+                routesChanged();
             },
         };
     }
@@ -343,120 +342,120 @@ export function createHttpHost(options = {}) {
             admission,
         });
         httpRoutes.push(entry);
+        routesChanged();
         return () => {
             const index = httpRoutes.indexOf(entry);
-            if (index >= 0)
-                httpRoutes.splice(index, 1);
+            if (index < 0)
+                return;
+            httpRoutes.splice(index, 1);
+            routesChanged();
         };
     }
     function createBoundHost(admission) {
         const bound = {
             [generationAdmissionBinder]: (next) => createBoundHost(next),
-            ws: (path, options) => registerWs(path, admission, options),
+            ws: (path, wsOptions) => registerWs(path, admission, wsOptions),
             route: (method, path, handler, meta) => registerRoute(method, path, handler, meta, admission),
             listRoutes: () => listListedRoutes(),
-            get address() { return runtime.address; },
+            get address() { return readAddress(); },
             get tokenRegistry() { return tokenRegistry; },
         };
         return Object.freeze(bound);
     }
-    const runtime = {
+    return {
         [generationAdmissionBinder]: (admission) => createBoundHost(admission),
-        ws: (pathname, options) => registerWs(pathname, undefined, options),
+        ws: (pathname, wsOptions) => registerWs(pathname, undefined, wsOptions),
         route: (method, path, handler, meta) => registerRoute(method, path, handler, meta),
-        listRoutes() {
-            return listListedRoutes();
-        },
-        get address() {
-            return address;
-        },
-        get tokenRegistry() {
-            return tokenRegistry;
+        listRoutes: () => listListedRoutes(),
+        get address() { return readAddress(); },
+        get tokenRegistry() { return tokenRegistry; },
+        handle,
+        upgrade,
+        get routeCount() { return httpRoutes.length; },
+        get wsPaths() { return Object.freeze([...wsRoutes.keys()]); },
+        listWsRoutes() {
+            const listed = [];
+            for (const [path, entries] of wsRoutes) {
+                const active = [...entries].filter((entry) => !entry.admission || entry.admission.active);
+                if (active.length === 0)
+                    continue;
+                const auth = active.every((entry) => entry.options.auth === 'protocol') ? 'protocol' : 'host';
+                listed.push(Object.freeze({ path, auth }));
+            }
+            return Object.freeze(listed);
         },
-        listen() {
-            if (closed)
-                return Promise.reject(new Error('HTTP Host is closed'));
-            if (listenResult)
-                return listenResult;
-            if (address)
-                return Promise.resolve(address);
-            listenResult = new Promise((resolve, reject) => {
-                const onError = (error) => {
-                    listenResult = undefined;
-                    reject(error);
-                };
-                server.once('error', onError);
-                server.listen({ host, port }, () => {
-                    server.off('error', onError);
-                    if (closed) {
-                        reject(new Error('HTTP Host closed before listen completed'));
-                        return;
-                    }
-                    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;
-                    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 ${address.origin}`
-                        + ` | routes: ${httpRoutes.length}`
-                        + ` | token: ${tokenRegistry.hasAnyToken()
-                            ? `${tokenRegistry.primaryTokenPrefixForLog()}…`
-                            : '(none)'}`);
-                    logger.debug(`listen detail | cors: ${corsOrigins.join(',')}`
-                        + ` | ws: ${[...wsRoutes.keys()].join(',') || '(none)'}`);
-                    resolve(address);
-                });
-            });
-            return listenResult;
+        onRoutesChanged(listener) {
+            changeListeners.add(listener);
+            return () => { changeListeners.delete(listener); };
         },
+        apiBase,
+        corsOrigins,
         close() {
-            if (closeResult)
-                return closeResult;
             closed = true;
             wsRoutes.clear();
             httpRoutes.length = 0;
-            closeResult = (async () => {
-                // A pending listen must settle before deciding whether there is a
-                // listener to close. Otherwise it can bind after close has resolved.
-                await listenResult?.catch(() => undefined);
-                if (!server.listening) {
-                    address = undefined;
-                    return;
-                }
-                await 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.
-                    for (const socket of sockets)
-                        socket.destroy();
-                    sockets.clear();
-                    for (const client of wss.clients)
-                        client.terminate();
-                    wss.close((wssError) => {
-                        if (wssError) {
-                            reject(wssError);
-                            return;
-                        }
-                        server.close((serverError) => {
-                            if (serverError) {
-                                reject(serverError);
-                                return;
-                            }
-                            logger.debug(formatCompact({ op: 'http_host_closed' }));
-                            address = undefined;
-                            resolve();
-                        });
-                    });
-                });
-            })();
-            return closeResult;
+            changeListeners.clear();
         },
     };
-    return runtime;
+}
+/**
+ * Adds host default headers (handler headers win) and, when `release` is given, keeps the
+ * generation lease until the body is fully delivered or cancelled.
+ */
+function withHeaders(response, defaults, release) {
+    const entries = defaults ? Object.entries(defaults) : [];
+    if (entries.length === 0 && !release)
+        return response;
+    const headers = new Headers(response.headers);
+    for (const [name, value] of entries)
+        if (!headers.has(name))
+            headers.set(name, value);
+    let body = response.body;
+    if (release) {
+        if (!body)
+            release();
+        else
+            body = releaseWhenDrained(body, release);
+    }
+    try {
+        return new Response(body, { status: response.status, statusText: response.statusText, headers });
+    }
+    catch {
+        // Response.error() and friends cannot be re-wrapped.
+        return new Response(null, { status: 500 });
+    }
+}
+function releaseWhenDrained(source, release) {
+    const reader = source.getReader();
+    let done = false;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        release();
+    };
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    finish();
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(next.value);
+                }
+            }
+            catch (error) {
+                finish();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            finish();
+            await reader.cancel(reason).catch(() => undefined);
+        },
+    }, { highWaterMark: 0 });
 }
 function requiresHttpAuth(pathname, apiBase, authExempt) {
     if (pathname === '/pub' || pathname.startsWith('/pub/'))
@@ -473,24 +472,15 @@ function corsMatch(origin, allowed) {
         || allowed.some((entry) => (entry === origin
             || (entry.endsWith('*') && origin.startsWith(entry.slice(0, -1)))));
 }
-function applyCors(response, origin, allowed) {
-    response.setHeader('Access-Control-Allow-Origin', allowed.includes('*') ? '*' : origin);
-    response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-    response.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Accept');
-    response.setHeader('Access-Control-Max-Age', '86400');
-}
-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);
-}
-function headerValue(value) {
-    if (Array.isArray(value))
-        return value[0];
-    return value;
+function corsHeaders(origin, allowed) {
+    return {
+        'access-control-allow-origin': allowed.includes('*') ? '*' : origin,
+        'access-control-allow-methods': 'GET, POST, PUT, DELETE, OPTIONS',
+        'access-control-allow-headers': 'Authorization, Content-Type, Accept',
+        'access-control-max-age': '86400',
+        // Browsers hide non-safelisted response headers unless exposed (503 instance-unavailable).
+        'access-control-expose-headers': 'Retry-After',
+    };
 }
 function matchHttpRoute(routes, method, pathname) {
     let best;
@@ -517,7 +507,12 @@ function matchHttpRoute(routes, method, pathname) {
     }
     return best;
 }
-function normalizePath(pathname) {
+function prefixRemainder(prefix, pathname) {
+    if (prefix === '/')
+        return pathname.slice(1);
+    return pathname.length > prefix.length ? pathname.slice(prefix.length + 1) : '';
+}
+export function normalizePath(pathname) {
     if (!pathname.startsWith('/'))
         return `/${pathname}`;
     // 线性裁剪尾部斜杠（等价于 /\/+$/u，但避免长串 `/` 无匹配时的
@@ -527,11 +522,3 @@ function normalizePath(pathname) {
         end -= 1;
     return pathname.slice(0, end) || '/';
 }
-function upgradePath(url) {
-    try {
-        return normalizePath(new URL(url ?? '/', 'http://localhost').pathname);
-    }
-    catch {
-        return '/';
-    }
-}