harper 5.1.20 → 5.2.0-alpha.5

package/dist/server/http.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bunServeConfigs = exports.universalHeaders = void 0;
+exports.uwsServeConfigs = exports.bunServeConfigs = exports.universalHeaders = void 0;
 exports.registerUdsCleanupPaths = registerUdsCleanupPaths;
 exports.cleanupUdsFiles = cleanupUdsFiles;
 exports.writeUdsMetadata = writeUdsMetadata;
@@ -47,8 +47,10 @@ exports.deliverSocket = deliverSocket;
 exports.proxyRequest = proxyRequest;
 exports.registerServer = registerServer;
 exports.httpServer = httpServer;
-exports.registerBunFastifyInstance = registerBunFastifyInstance;
+exports.registerFastifyInstance = registerFastifyInstance;
+exports.describeMiddlewareChains = describeMiddlewareChains;
 exports.enableProxyProtocol = enableProxyProtocol;
+exports.createH2CProxyFront = createH2CProxyFront;
 exports.logRequest = logRequest;
 exports.getRequestId = getRequestId;
 // @ts-nocheck
@@ -68,6 +70,7 @@ const keys_ts_1 = require("../security/keys.js");
 const node_http2_1 = require("node:http2");
 const node_https_1 = require("node:https");
 const node_http_1 = require("node:http");
+const node_net_2 = require("node:net");
 const Request_ts_1 = require("./serverHelpers/Request.js");
 const Headers_ts_1 = require("./serverHelpers/Headers.js");
 const blob_ts_1 = require("../resources/blob.js");
@@ -81,7 +84,7 @@ const componentLoader_ts_1 = require("../components/componentLoader.js");
 const throttle_ts_1 = require("./throttle.js");
 const middlewareChain_ts_1 = require("./middlewareChain.js");
 const ws_1 = require("ws");
-const { errorToString } = harper_logger_ts_1.default;
+const { errorToString, errorForLog } = harper_logger_ts_1.default;
 Server_ts_1.server.http = httpServer;
 Server_ts_1.server.request = onRequest;
 Server_ts_1.server.ws = onWebSocket;
@@ -92,8 +95,15 @@ let httpOptions = {};
 exports.universalHeaders = [];
 // Bun-specific: stores fetch handler configs per port, used by threadServer.js to call Bun.serve()
 exports.bunServeConfigs = {};
-// Bun-specific: stores non-function listeners (e.g. Fastify servers) per port for fallback delegation
-const bunFallbackServers = {};
+// uWS backend (#914): stores { socketPath, secure, handler } configs keyed by UDS path. When
+// HARPER_UWS_UDS is set, the per-worker UDS mirror is served by uWebSockets.js instead of a Node
+// http server; threadServer.js consumes these and calls createUwsServer(). Symphony must forward
+// client identity via X-Forwarded-For (not the PROXY protocol) on these sockets, as the Bun path does.
+exports.uwsServeConfigs = {};
+// Stores non-function listeners (e.g. Fastify servers) per port for fallback delegation on the
+// backends that don't register their own Node http server (Bun, and the uWS HTTP path). Keeping
+// them out of SERVERS is what prevents a competing Node server from binding the same port.
+const fallbackServers = {};
 const udsCleanupPaths = [];
 function registerUdsCleanupPaths(socketPath, yamlPath) {
     udsCleanupPaths.push({ socketPath, yamlPath });
@@ -111,9 +121,13 @@ function cleanupUdsFiles() {
     }
 }
 /** Write YAML metadata for a UDS mirror socket, describing the TLS certs from the corresponding secure server. */
-function writeUdsMetadata(yamlPath, port, secureServer) {
+function writeUdsMetadata(yamlPath, port, secureServer, protocol) {
     const contexts = secureServer.secureContexts;
     let yaml = `pid: ${process.pid}\ntid: ${(0, rocksdb_js_1.currentThreadId)()}\nport: ${port}\n`;
+    // Which application protocol this socket speaks (absent = http/1.1, the historical
+    // default) — lets a fronting proxy route by negotiated ALPN.
+    if (protocol)
+        yaml += `protocol: ${protocol}\n`;
     yaml += `certificates:\n`;
     if (contexts?.size > 0) {
         const seen = new Set();
@@ -359,7 +373,17 @@ function httpServer(listener, options) {
         }
         else if (Request_ts_1.isBun) {
             // On Bun, store non-function listeners (e.g. Fastify's http.Server) for fallback delegation
-            bunFallbackServers[port] = listener;
+            fallbackServers[port] = listener;
+        }
+        else if (httpServers[port]?.uws) {
+            // uWS HTTP path (#914, HARPER_UWS_HTTP): the port is backed by uWebSockets.js, not a Node
+            // http server, so a raw non-function listener (e.g. Fastify's http.Server via
+            // server.http(fastify.server)) must NOT go through registerServer() — that would put it in
+            // SERVERS and threadServer would bind a Node http server competing with uWS on the same TCP
+            // port. Divert it to the fallback map like the Bun path; makeUwsHandler delegates unhandled
+            // requests to it via inject(). The { uws: true } marker is guaranteed present here: the
+            // getServer(port) call above (same loop iteration) sets it before this branch runs.
+            fallbackServers[port] = listener;
         }
         else {
             listener.isSecure = secure;
@@ -376,6 +400,29 @@ function getHTTPServer(port, secure, options) {
     if (!httpServers[port]) {
         // TODO: These should all come from httpOptions or operationsApiOptions
         const serverPrefix = isOperationsServer ? 'operationsApi_network' : (usageType ?? 'http');
+        // uWS plaintext-HTTP path (#914, HARPER_UWS_HTTP): back a non-secure TCP HTTP port with
+        // uWebSockets.js directly instead of a Node http server. This is the flag used to run the
+        // integration suite through uWS (no symphony/UDS needed). WebSocket upgrades are wired on this
+        // path via onWebSocket's uWS branch; it's opt-in and separate from HARPER_UWS_UDS.
+        const lastColon = String(port).lastIndexOf(':');
+        const uwsPort = lastColon > 0 ? +String(port).slice(lastColon + 1) : +port;
+        if (process.env.HARPER_UWS_HTTP &&
+            !secure &&
+            !isOperationsServer &&
+            !String(port).includes('/') &&
+            !Number.isNaN(uwsPort)) {
+            exports.uwsServeConfigs[port] = {
+                port: uwsPort,
+                host: lastColon > 0 ? String(port).slice(0, lastColon).replace(/[[\]]/g, '') : undefined,
+                secure: false,
+                handler: makeUwsHandler(port, isOperationsServer, env.get(serverPrefix + '_requestQueueLimit')),
+            };
+            // Marker so the httpServers guard is satisfied and the caller has a truthy handle; the
+            // actual listen happens in threadServer.js from uwsServeConfigs. onWebSocket() detects
+            // this marker (server.uws) and wires native uWS WebSocket handling into the same config.
+            httpServers[port] = { uws: true, port };
+            return httpServers[port];
+        }
         const keepAliveTimeout = env.get(serverPrefix + '_keepAliveTimeout');
         const requestTimeout = env.get(serverPrefix + '_timeout');
         const headersTimeout = env.get(serverPrefix + '_headersTimeout');
@@ -564,7 +611,9 @@ function getHTTPServer(port, secure, options) {
             }
             function onError(error) {
                 const headers = error.headers;
-                const status = error.statusCode || 500;
+                // the HTTP status may be carried as `statusCode` (our error classes) or `status` (e.g. a thrown plain object)
+                const statusCode = error.statusCode ?? error.status;
+                const status = statusCode || 500;
                 try {
                     nodeResponse.writeHead(status, (0, Headers_ts_1.toWriteHeadHeaders)(headers));
                 }
@@ -572,14 +621,14 @@ function getHTTPServer(port, secure, options) {
                 nodeResponse.end(errorToString(error));
                 logRequest(nodeRequest, status, requestId, performance.now() - startTime);
                 // a status code is interpreted as an expected error, so just info or warn, otherwise log as error
-                if (error.statusCode) {
-                    if (error.statusCode === 500)
-                        harper_logger_ts_1.default.warn(error);
+                if (statusCode) {
+                    if (statusCode === 500)
+                        harper_logger_ts_1.default.warn(errorForLog(error));
                     else
-                        harper_logger_ts_1.default.info(error);
+                        harper_logger_ts_1.default.info(errorForLog(error));
                 }
                 else
-                    harper_logger_ts_1.default.error(error);
+                    harper_logger_ts_1.default.error(errorForLog(error));
             }
         };
         // create a throttled version of the request handler, so we can throttle POST requests
@@ -638,34 +687,278 @@ function getHTTPServer(port, secure, options) {
             const socketName = `${(0, manageThreads_js_1.getWorkerIndex)()}-${port}`;
             const udsPath = (0, node_path_1.join)(socketsDir, `${socketName}.sock`);
             const yamlPath = (0, node_path_1.join)(socketsDir, `${socketName}.yaml`);
-            // Create a plain HTTP server (no TLS) with the same request handler
-            const udsServer = (0, node_http_1.createServer)({
-                keepAliveTimeout,
-                headersTimeout,
-                requestTimeout,
-                highWaterMark: 128 * 1024,
-                noDelay: true,
-                keepAlive: true,
-                keepAliveInitialDelay: 600,
-                maxHeaderSize: env.get(terms.CONFIG_PARAMS.HTTP_MAXHEADERSIZE),
-            }, (nodeRequest, nodeResponse) => {
-                const method = nodeRequest.method;
-                if (method === 'GET' || method === 'OPTIONS' || method === 'HEAD')
-                    requestHandler(nodeRequest, nodeResponse);
-                else
-                    throttledRequestHandler(nodeRequest, nodeResponse);
-            });
-            udsServer.isPerThreadSocket = true;
-            enableProxyProtocol(udsServer);
-            serverRegistry_ts_1.SERVERS[udsPath] = udsServer;
+            if (process.env.HARPER_UWS_UDS) {
+                // uWS backend (#914): serve the UDS mirror with uWebSockets.js instead of a Node http
+                // server. threadServer.js consumes uwsServeConfigs and calls createUwsServer(). uWS does
+                // not parse the PROXY protocol, so symphony must use sourceAddressHeader: 'xForwardedFor'
+                // for this socket (the same mode it uses for the Bun path).
+                exports.uwsServeConfigs[udsPath] = {
+                    socketPath: udsPath,
+                    secure: true,
+                    handler: makeUwsHandler(port, isOperationsServer, env.get(serverPrefix + '_requestQueueLimit')),
+                };
+            }
+            else {
+                // Create a plain HTTP server (no TLS) with the same request handler
+                const udsServer = (0, node_http_1.createServer)({
+                    keepAliveTimeout,
+                    headersTimeout,
+                    requestTimeout,
+                    highWaterMark: 128 * 1024,
+                    noDelay: true,
+                    keepAlive: true,
+                    keepAliveInitialDelay: 600,
+                    maxHeaderSize: env.get(terms.CONFIG_PARAMS.HTTP_MAXHEADERSIZE),
+                }, (nodeRequest, nodeResponse) => {
+                    const method = nodeRequest.method;
+                    if (method === 'GET' || method === 'OPTIONS' || method === 'HEAD')
+                        requestHandler(nodeRequest, nodeResponse);
+                    else
+                        throttledRequestHandler(nodeRequest, nodeResponse);
+                });
+                udsServer.isPerThreadSocket = true;
+                enableProxyProtocol(udsServer);
+                serverRegistry_ts_1.SERVERS[udsPath] = udsServer;
+            }
             registerUdsCleanupPaths(udsPath, yamlPath);
             const writeMetadata = () => writeUdsMetadata(yamlPath, port, server);
             options.SNICallback.ready.then(writeMetadata);
             server.secureContextsListeners.push(writeMetadata);
+            // Optional cleartext HTTP/2 mirror (spike: HARPER_H2C_UDS=1). A separate socket
+            // (`<worker>-<port>-h2.sock`) so a fronting proxy can route by negotiated ALPN:
+            // h2 connections here, http/1.1 to the plain mirror above. The metadata yaml
+            // carries `protocol: h2` so the proxy can discover which socket speaks what.
+            if (process.env.HARPER_H2C_UDS) {
+                const udsPathH2 = (0, node_path_1.join)(socketsDir, `${socketName}-h2.sock`);
+                const yamlPathH2 = (0, node_path_1.join)(socketsDir, `${socketName}-h2.yaml`);
+                const h2Server = (0, node_http2_1.createServer)({}, (nodeRequest, nodeResponse) => {
+                    const method = nodeRequest.method;
+                    if (method === 'GET' || method === 'OPTIONS' || method === 'HEAD')
+                        requestHandler(nodeRequest, nodeResponse);
+                    else
+                        throttledRequestHandler(nodeRequest, nodeResponse);
+                });
+                // A stray non-h2 client (or a truncated preface) fails the session, not the worker.
+                h2Server.on('sessionError', (error) => {
+                    harper_logger_ts_1.default.debug('h2c UDS session error:', error);
+                });
+                const h2Front = createH2CProxyFront(h2Server);
+                h2Front.isPerThreadSocket = true;
+                serverRegistry_ts_1.SERVERS[udsPathH2] = h2Front;
+                registerUdsCleanupPaths(udsPathH2, yamlPathH2);
+                const writeMetadataH2 = () => writeUdsMetadata(yamlPathH2, port, server, 'h2');
+                options.SNICallback.ready.then(writeMetadataH2);
+                server.secureContextsListeners.push(writeMetadataH2);
+            }
         }
     }
     return httpServers[port];
 }
+/**
+ * uWS backend (#914): builds the per-request handler for a uWS UDS server. Mirrors the Bun
+ * fetchHandler's post-processing (httpChain, unhandled, universalHeaders, Server-Timing,
+ * analytics, logging) but returns a plain Harper response descriptor for createUwsServer to
+ * serialize onto the uWS HttpResponse. When the chain doesn't handle the request (status === -1)
+ * and a Fastify fallback is registered for the port, it delegates via inject() (see injectToFastify),
+ * mirroring the Bun path — so legacy Fastify routes work behind uWS too.
+ */
+function makeUwsHandler(port, isOperationsServer, requestQueueLimit) {
+    // Build a fresh response descriptor rather than mutating what the chain returned: a handler may
+    // return a WHATWG `Response` (read-only `status`/`body` accessors), which the Bun path also never
+    // mutates. `headers` is normalized in place the same way the Bun path does.
+    const handle = async (request) => {
+        const startTime = performance.now();
+        let requestId = 0;
+        if (isOperationsServer)
+            request.isOperationsServer = true;
+        if (httpOptions.logging?.id)
+            request.requestId = requestId = getRequestId();
+        let response = await httpChain[port](request);
+        if (!response)
+            response = unhandled(request);
+        let headers = response.headers;
+        if (!headers?.set)
+            headers = new Headers_ts_1.Headers(headers);
+        for (const [key, value] of exports.universalHeaders)
+            headers.set(key, value);
+        if (response.status === -1) {
+            // The chain didn't handle it. If a Fastify fallback is registered for this port (legacy
+            // custom-function routes via server.http(fastify.server)), delegate to it via inject(),
+            // mirroring the Bun path; otherwise it's a genuine 404.
+            const fastify = fastifyInstances[port];
+            if (fastify) {
+                const injectResult = await injectToFastify(fastify, {
+                    method: request.method,
+                    url: request.url,
+                    headers: request.headers.asObject,
+                    body: request.body, // stream; inject() consumes it as the payload
+                    user: request.user,
+                });
+                const respHeaders = new Headers_ts_1.Headers();
+                for (const [k, v] of Object.entries(injectResult.headers)) {
+                    if (v == null)
+                        continue;
+                    // Keep Set-Cookie multi-valued (Harper Headers + writeHeaders emit each separately);
+                    // only comma-join other repeated headers.
+                    if (Array.isArray(v))
+                        respHeaders.set(k, k.toLowerCase() === 'set-cookie' ? v : v.join(', '));
+                    else
+                        respHeaders.set(k, String(v));
+                }
+                logHttpRequest(request, injectResult.statusCode, requestId, performance.now() - startTime);
+                const responseStream = injectResult.stream();
+                // Event-stream (SSE) responses must reach the client incrementally — stream the body and,
+                // on client disconnect, destroy the inject response so the Fastify reply's teardown runs
+                // (matches the Bun path). Finite responses buffer so Content-Length stays set.
+                if (String(injectResult.headers['content-type'] ?? '').includes('text/event-stream')) {
+                    const injectResponse = injectResult.raw?.res;
+                    if (injectResponse && typeof injectResponse.destroy === 'function') {
+                        responseStream.once('close', () => injectResponse.destroy());
+                    }
+                    return { status: injectResult.statusCode, headers: respHeaders, body: responseStream };
+                }
+                const chunks = [];
+                for await (const chunk of responseStream)
+                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                return {
+                    status: injectResult.statusCode,
+                    headers: respHeaders,
+                    body: chunks.length > 0 ? Buffer.concat(chunks) : null,
+                };
+            }
+            logHttpRequest(request, 404, requestId, performance.now() - startTime);
+            return { status: 404, headers: new Headers_ts_1.Headers({ 'content-type': 'text/plain' }), body: 'Not found\n' };
+        }
+        const status = response.status || 200;
+        const executionTime = performance.now() - startTime;
+        if (!response.handlesHeaders) {
+            let serverTiming = `hdb;dur=${executionTime.toFixed(2)}`;
+            if (response.wasCacheMiss)
+                serverTiming += ', miss';
+            (0, Headers_ts_1.appendHeader)(headers, 'Server-Timing', serverTiming, true);
+        }
+        (0, write_ts_1.recordAction)(executionTime, 'duration', request.handlerPath, request.method, response.wasCacheMiss == undefined ? undefined : response.wasCacheMiss ? 'cache-miss' : 'cache-hit');
+        (0, write_ts_1.recordActionBinary)(status < 400, 'success', request.handlerPath, request.method);
+        (0, write_ts_1.recordActionBinary)(1, 'response_' + status, request.handlerPath, request.method);
+        logHttpRequest(request, status, requestId, executionTime);
+        // Static handlers (the only handlesHeaders producers) return a `send` SendStream that writes
+        // its own headers/body to a Node ServerResponse via .pipe(). uWS has no such object, and a
+        // SendStream doesn't start until piped, so streaming it directly hangs (headers never flush).
+        // Pipe it into a Writable shim that captures the headers and buffers the file, mirroring the
+        // Bun path. Non-handlesHeaders bodies keep streaming through normalizeUwsBody.
+        if (response.handlesHeaders && response.body && typeof response.body.pipe === 'function') {
+            // send() may return 304 (conditional GET) or 206/416 (Range) — honor the status it set.
+            const sent = await bufferSendStream(response.body, headers, status, request.signal);
+            return { status: sent.status, headers, handlesHeaders: true, body: sent.body };
+        }
+        const body = await normalizeUwsBody(response.body, request.signal);
+        return { status, headers, handlesHeaders: response.handlesHeaders, body };
+    };
+    // Shed data-modifying requests when the event queue is backed up (503), mirroring the Node UDS
+    // path — GET/OPTIONS/HEAD are cheap and always run, everything else goes through the throttle.
+    const throttledHandle = (0, throttle_ts_1.throttle)(handle, (_request) => {
+        (0, write_ts_1.recordAction)(true, 'service-unavailable', port);
+        return {
+            status: 503,
+            headers: new Headers_ts_1.Headers({ 'content-type': 'text/plain' }),
+            body: 'Service unavailable, exceeded request queue limit',
+        };
+    }, requestQueueLimit);
+    return (request) => {
+        const method = request.method;
+        if (method === 'GET' || method === 'OPTIONS' || method === 'HEAD')
+            return handle(request);
+        return throttledHandle(request);
+    };
+}
+/**
+ * uWS: normalize a Harper response body into what the adapter can serialize. Finite bodies collapse
+ * to a string/Buffer; a Node stream or async-iterable is returned as a Readable so writeResponse can
+ * stream it incrementally (buffering an SSE/event-stream body here would never return). `signal`
+ * aborts the collapse of a sync iterable if the client disconnects mid-response.
+ */
+/**
+ * Drive a `send` SendStream to completion against a Writable shim, capturing the headers it writes
+ * (setHeader/writeHead) onto `headers` and the status it sets (statusCode/writeHead) and buffering
+ * the file body. `send` targets an http.ServerResponse (setHeader/writeHead/statusCode/finished);
+ * uWS has none, so we adapt — mirrors the Bun fetchHandler's SendStream path. The captured status
+ * carries send's conditional-GET (304) and Range (206/416) results. Buffering is fine for static
+ * assets and keeps Content-Length set. `defaultStatus` is used when send sets none.
+ */
+function bufferSendStream(body, headers, defaultStatus, signal) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const dest = new node_stream_1.Writable({
+            write(chunk, _encoding, callback) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                callback();
+            },
+            final(callback) {
+                callback();
+                resolve({ body: Buffer.concat(chunks), status: dest.statusCode || defaultStatus });
+            },
+        });
+        Object.assign(dest, {
+            setHeader: (n, v) => headers.set(n, v),
+            getHeader: (n) => headers.get(n),
+            removeHeader: (n) => headers.delete(n.toLowerCase()),
+            // send conveys 304/206/416 via statusCode and/or writeHead's status arg — capture both so
+            // conditional-GET and Range responses aren't flattened to the default 200.
+            writeHead: (s, hdrs) => {
+                if (s)
+                    dest.statusCode = s;
+                if (hdrs)
+                    for (const k in hdrs)
+                        headers.set(k, hdrs[k]);
+            },
+            statusCode: defaultStatus,
+            headersSent: false,
+            // 'on-finished' (used by 'send') treats a non-false `finished` as already-done and destroys
+            // the read stream before data flows; keep it false so it waits for the 'finish' event.
+            finished: false,
+        });
+        const onAbort = () => {
+            body.destroy?.();
+            dest.destroy?.();
+            reject(new Error('client aborted'));
+        };
+        if (signal) {
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        body.on('error', reject);
+        dest.on('error', reject);
+        body.pipe(dest);
+    });
+}
+async function normalizeUwsBody(body, signal) {
+    if (body == null)
+        return null;
+    if (typeof body === 'string' || Buffer.isBuffer(body) || body instanceof Uint8Array)
+        return body;
+    if (body instanceof blob_ts_1.Blob)
+        return Buffer.from(await body.arrayBuffer());
+    if (typeof body.then === 'function')
+        return normalizeUwsBody(await body, signal);
+    // Already a Node stream — stream it as-is (re-wrapping in Readable.from breaks destroy propagation).
+    if (typeof body.pipe === 'function')
+        return body;
+    // Async-iterable (e.g. an event queue) — adapt to a Readable and stream it.
+    if (body[Symbol.asyncIterator])
+        return node_stream_1.Readable.from(body);
+    // Sync iterable — small/finite, collapse to a buffer.
+    if (body[Symbol.iterator]) {
+        const chunks = [];
+        for (const chunk of body) {
+            if (signal?.aborted)
+                throw new Error('client aborted');
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    return String(body);
+}
 /**
  * Bun-specific HTTP server setup. Instead of creating a Node http.Server, we store a fetch handler config
  * that will be passed to Bun.serve() when listenOnPorts() is called in threadServer.js.
@@ -696,14 +989,14 @@ function getBunHTTPServer(port, secure, options) {
                     response.headers.set(key, value);
                 }
                 if (response.status === -1) {
-                    const fallbackServer = bunFallbackServers[port];
+                    const fallbackServer = fallbackServers[port];
                     if (fallbackServer) {
                         // Delegate to the fallback server (e.g. Fastify) via node:http compatibility.
                         // We create a Node-compatible IncomingMessage/ServerResponse and emit 'request'
                         // on the fallback server, then capture the response.
                         return await bunDelegateToNodeServer(fallbackServer, webRequest, request);
                     }
-                    logBunRequest(request, 404, requestId, performance.now() - startTime);
+                    logHttpRequest(request, 404, requestId, performance.now() - startTime);
                     return new Response('Not found\n', { status: 404 });
                 }
                 const status = response.status || 200;
@@ -758,7 +1051,7 @@ function getBunHTTPServer(port, secure, options) {
                 (0, write_ts_1.recordAction)(executionTime, 'duration', handlerPath, method, response.wasCacheMiss == undefined ? undefined : response.wasCacheMiss ? 'cache-miss' : 'cache-hit');
                 (0, write_ts_1.recordActionBinary)(status < 400, 'success', handlerPath, method);
                 (0, write_ts_1.recordActionBinary)(1, 'response_' + status, handlerPath, method);
-                logBunRequest(request, status, requestId, executionTime);
+                logHttpRequest(request, status, requestId, executionTime);
                 // Convert body to something Bun's Response can accept
                 if (body instanceof ReadableStream) {
                     return new Response(body, { status, headers: responseHeaders });
@@ -813,16 +1106,18 @@ function getBunHTTPServer(port, secure, options) {
                 return new Response(body, { status, headers: responseHeaders });
             }
             catch (error) {
-                const status = error.statusCode || 500;
-                logBunRequest(null, status, requestId, performance.now() - startTime);
-                if (error.statusCode) {
-                    if (error.statusCode === 500)
-                        harper_logger_ts_1.default.warn(error);
+                // the HTTP status may be carried as `statusCode` (our error classes) or `status` (e.g. a thrown plain object)
+                const statusCode = error.statusCode ?? error.status;
+                const status = statusCode || 500;
+                logHttpRequest(null, status, requestId, performance.now() - startTime);
+                if (statusCode) {
+                    if (statusCode === 500)
+                        harper_logger_ts_1.default.warn(errorForLog(error));
                     else
-                        harper_logger_ts_1.default.info(error);
+                        harper_logger_ts_1.default.info(errorForLog(error));
                 }
                 else
-                    harper_logger_ts_1.default.error(error);
+                    harper_logger_ts_1.default.error(errorForLog(error));
                 return new Response(errorToString(error), { status });
             }
         };
@@ -858,42 +1153,53 @@ function getBunHTTPServer(port, secure, options) {
  * Bridge a Bun fetch request to a Node.js http.Server (e.g. Fastify) by using Fastify's inject()
  * method to send the request through its internal router without needing a real socket.
  */
-let bunFastifyInstances = {};
-function registerBunFastifyInstance(port, instance) {
-    bunFastifyInstances[port] = instance;
+let fastifyInstances = {};
+function registerFastifyInstance(port, instance) {
+    fastifyInstances[port] = instance;
 }
 const INTERNAL_USER_HEADER = 'x-harper-internal-pre-auth-user';
+/**
+ * Run a request through a Fastify instance via inject() — its internal router, no socket needed.
+ * Shared by the Bun and uWS fallback-delegation paths. Strips any forged pre-auth header from the
+ * client and, when Harper's auth middleware resolved a user without credentials (e.g. AUTHORIZE_LOCAL
+ * for loopback in dev), forwards it so Fastify can skip its own auth — only when no Authorization
+ * header was supplied, otherwise Fastify's Passport validates the credentials normally.
+ * `payloadAsStream` makes inject() resolve as soon as the response headers are written and exposes
+ * the body as a Readable, so a long-lived SSE response (the MCP server-push GET) streams instead of
+ * buffering forever.
+ */
+function injectToFastify(fastify, req) {
+    const headers = {};
+    for (const key in req.headers) {
+        if (key.toLowerCase() !== INTERNAL_USER_HEADER)
+            headers[key] = req.headers[key];
+    }
+    // Both callers pass already-lowercased header keys (uWS lowercases at the protocol level →
+    // RequestHeaders.asObject; Bun's webRequest.headers.forEach yields lowercase), so the literal
+    // 'authorization' lookup is reliable — the pre-auth user is only forwarded when the client sent
+    // no credentials of its own.
+    if (req.user && !headers['authorization']) {
+        headers[INTERNAL_USER_HEADER] = JSON.stringify(req.user);
+    }
+    return fastify.inject({ method: req.method, url: req.url, headers, payload: req.body, payloadAsStream: true });
+}
 async function bunDelegateToNodeServer(nodeServer, webRequest, bunRequest) {
     // Check if there's a Fastify instance registered for this port (preferred path)
-    for (const port in bunFallbackServers) {
-        if (bunFallbackServers[port] === nodeServer && bunFastifyInstances[port]) {
-            const fastify = bunFastifyInstances[port];
+    for (const port in fallbackServers) {
+        if (fallbackServers[port] === nodeServer && fastifyInstances[port]) {
+            const fastify = fastifyInstances[port];
             const url = new URL(webRequest.url);
             const body = webRequest.body ? Buffer.from(await webRequest.arrayBuffer()) : undefined;
             const headers = {};
             webRequest.headers.forEach((value, key) => {
-                // Strip any forged pre-auth header from real clients
-                if (key.toLowerCase() !== INTERNAL_USER_HEADER)
-                    headers[key] = value;
+                headers[key] = value;
             });
-            // If Harper's auth middleware authenticated this request without credentials (e.g. via
-            // AUTHORIZE_LOCAL for loopback connections in dev mode), pass the user so Fastify can
-            // skip its own auth. Only applies when there is no Authorization header — if credentials
-            // were provided, let Fastify's Passport validate them normally.
-            if (bunRequest?.user && !headers['authorization']) {
-                headers[INTERNAL_USER_HEADER] = JSON.stringify(bunRequest.user);
-            }
-            // `payloadAsStream` makes inject() resolve as soon as the response headers are
-            // written and exposes the body as a Readable, instead of buffering the whole
-            // payload and resolving only on response end. Without it a long-lived SSE
-            // response (the MCP server-push GET) never ends, so `await inject()` would
-            // hang forever and the client would never receive headers.
-            const injectResult = await fastify.inject({
+            const injectResult = await injectToFastify(fastify, {
                 method: webRequest.method,
                 url: url.pathname + url.search,
                 headers,
-                payload: body,
-                payloadAsStream: true,
+                body,
+                user: bunRequest?.user,
             });
             const webHeaders = new globalThis.Headers();
             for (const [k, v] of Object.entries(injectResult.headers)) {
@@ -940,14 +1246,68 @@ async function bunDelegateToNodeServer(nodeServer, webRequest, bunRequest) {
     // No Fastify instance found — return 404
     return new Response('Not found\n', { status: 404 });
 }
-function makeCallbackChain(responders, portNum, requestArgIndex = 0) {
-    return (0, middlewareChain_ts_1.makeCallbackChain)(responders, portNum, unhandled, () => {
-        harper_logger_ts_1.default.warn(`Cycle detected in middleware before/after ordering on port ${portNum}; falling back to registration order.`);
-    }, requestArgIndex);
+// Resolved order captured at chain-build time, keyed identically to httpChain/upgradeChains/
+// websocketChains (kind → port → routes). Reporting the stored build-time order rather than
+// recomputing from current responders guarantees get_status matches the callback chain actually
+// serving that port — including cases where a late `port: 'all'` registration rebuilds only the
+// 'all' chain and leaves a concrete port's chain (and this description) unchanged (#1573).
+const resolvedChainDescriptions = {
+    http: {},
+    upgrade: {},
+    websocket: {},
+};
+function makeCallbackChain(responders, portNum, requestArgIndex = 0, kind = 'http') {
+    const onCycle = () => {
+        harper_logger_ts_1.default.warn(`Cycle detected in ${kind} middleware before/after ordering on port ${portNum}; falling back to registration order.`);
+    };
+    // describeChains reuses the same resolvers as buildCallbackChain, so this is the served order.
+    // onCycle is omitted: the build call owns the single cycle warning, and on a cycle describeChains
+    // falls back to registration order exactly as the built chain does.
+    const routes = (0, middlewareChain_ts_1.describeChains)(responders, portNum).map((route) => ({
+        host: route.host,
+        urlPath: route.urlPath,
+        order: route.order.map((entry) => entry.name ?? '(anonymous)'),
+    }));
+    resolvedChainDescriptions[kind][portNum] = routes;
+    if (harper_logger_ts_1.default.debug) {
+        for (const route of routes) {
+            const scope = route.host || route.urlPath ? ` [${route.host ?? '*'}${route.urlPath ?? ''}]` : '';
+            harper_logger_ts_1.default.debug(`Resolved ${kind} middleware chain on port ${portNum}${scope}: ${route.order.join(' → ') || '(empty)'}`);
+        }
+    }
+    return (0, middlewareChain_ts_1.makeCallbackChain)(responders, portNum, unhandled, onCycle, requestArgIndex, ({ entryName, kind: refKind, target }) => {
+        harper_logger_ts_1.default.warn(`Middleware ordering: ${entryName ? `'${entryName}'` : 'a handler'} requested \`${refKind}: '${target}'\` but no handler named '${target}' is registered on port ${portNum}, so the constraint is ignored. Handler names are the config keys as registered (e.g. 'rest').`);
+    });
+}
+/**
+ * Returns the resolved middleware order for every built HTTP, upgrade, and WebSocket chain on the
+ * current thread, as plain serializable data (listeners omitted). Surfaced via the `get_status`
+ * operation so chain placement can be verified on a running instance (#1573). The 'all' pseudo-port
+ * is excluded: makeCallbackChain builds a chain for it, but it is not a bound listener (its
+ * responders already fold into every concrete port's chain).
+ *
+ * Note: this reflects the calling thread's built chains. All HTTP worker threads register
+ * identically, so any worker's view is representative.
+ */
+function describeMiddlewareChains() {
+    const concretePorts = (byPort) => {
+        const out = {};
+        for (const port of Object.keys(byPort))
+            if (port !== 'all')
+                out[port] = byPort[port];
+        return out;
+    };
+    return {
+        http: concretePorts(resolvedChainDescriptions.http),
+        upgrade: concretePorts(resolvedChainDescriptions.upgrade),
+        websocket: concretePorts(resolvedChainDescriptions.websocket),
+    };
 }
 function unhandled(request) {
-    if (request.user) {
-        // pass on authentication information to the next server
+    if (request.user && request._nodeRequest) {
+        // pass on authentication information to the next server (Node fallback delegation via the
+        // 'unhandled' event chain). The Bun/uWS adapters have no _nodeRequest; they forward the
+        // resolved user to the Fastify fallback via injectToFastify's INTERNAL_USER_HEADER instead.
         request._nodeRequest.user = request.user;
     }
     return {
@@ -982,7 +1342,7 @@ function onUpgrade(listener, options) {
             host: options?.host || undefined,
         };
         upgradeListeners[options?.runFirst ? 'unshift' : 'push'](entry);
-        upgradeChains[port] = makeCallbackChain(upgradeListeners, port);
+        upgradeChains[port] = makeCallbackChain(upgradeListeners, port, 0, 'upgrade');
     }
 }
 const websocketListeners = [], websocketChains = {};
@@ -1000,7 +1360,39 @@ function onWebSocket(listener, options) {
             name: (0, componentLoader_ts_1.getComponentName)(),
         });
         const server = getHTTPServer(port, secure, options);
-        if (!websocketServers[port]) {
+        if (server?.uws) {
+            // uWS-backed port (HARPER_UWS_HTTP): uWS owns the socket, so route upgrades through uWS's
+            // native app.ws() rather than the Node ws.WebSocketServer + server 'upgrade' event. We wire a
+            // wsHandler into the shared uwsServeConfig; createUwsServer registers app.ws() when it listens.
+            const cfg = exports.uwsServeConfigs[port];
+            if (cfg && !cfg.wsHandler) {
+                // Honor a configured WebSocket maxPayload on the uWS transport too (else it defaults to 100 MiB).
+                if (options.maxPayload != null)
+                    cfg.wsMaxPayload = options.maxPayload;
+                cfg.wsHandler = (ws, upgrade) => {
+                    try {
+                        const request = new Request_ts_1.UwsRequest({
+                            method: 'GET',
+                            url: upgrade.url,
+                            headers: upgrade.headers,
+                            secure,
+                            ip: upgrade.ip,
+                        });
+                        request.isWebSocket = true;
+                        const chainCompletion = httpChain[port](request);
+                        websocketChains[port](ws, request, chainCompletion);
+                    }
+                    catch (error) {
+                        harper_logger_ts_1.default.warn('Error in handling WS connection', error);
+                        try {
+                            ws.close();
+                        }
+                        catch { }
+                    }
+                };
+            }
+        }
+        else if (!websocketServers[port]) {
             websocketServers[port] = new ws_1.WebSocketServer({
                 noServer: true,
                 // TODO: this should be a global config and not per ws listener
@@ -1050,7 +1442,7 @@ function onWebSocket(listener, options) {
             host: options?.host || undefined,
         };
         websocketListeners[options?.runFirst ? 'unshift' : 'push'](wsEntry);
-        websocketChains[port] = makeCallbackChain(websocketListeners, port, 1);
+        websocketChains[port] = makeCallbackChain(websocketListeners, port, 1, 'websocket');
         // mqtt doesn't invoke the http handler so this needs to be here to load up the http chains.
         httpChain[port] = makeCallbackChain(httpResponders, port);
     }
@@ -1128,6 +1520,97 @@ function enableProxyProtocol(httpServer) {
         });
     });
 }
+/**
+ * Front a cleartext HTTP/2 server with optional PROXY v1 handling on a Unix domain socket.
+ *
+ * enableProxyProtocol() can't be used here: Node's Http2Session consumes the socket's
+ * native handle directly, so data never surfaces as JS 'data' events to intercept. The
+ * PROXY header must instead be consumed *before* the socket is handed to the HTTP/2
+ * server. Bytes beyond the header (typically the coalesced h2 connection preface) are
+ * unshifted back onto the socket; the native session picks them up (verified on Node 24
+ * — covered by a unit test so a Node upgrade regressing this fails loudly).
+ *
+ * The returned server's close() also gracefully closes live h2 sessions (GOAWAY,
+ * in-flight streams finish) so closeServers()'s generic server.close() drains instead
+ * of riding its 5s force-exit backstop — the h1 mirror gets this via http.Server's
+ * closeIdleConnections drain, which a net.Server doesn't have.
+ */
+function createH2CProxyFront(h2Server, prehandoffTimeout = 10_000) {
+    const sessions = new Set();
+    const prehandoffSockets = new Set();
+    let closing = false;
+    h2Server.on('session', (session) => {
+        // A connection can be mid-handoff (header read, session not yet created) when
+        // close() runs — its session forms after the close sweep, so close it here or
+        // it would never receive GOAWAY and would ride the 5s force-exit backstop.
+        if (closing)
+            session.close();
+        sessions.add(session);
+        session.on('close', () => sessions.delete(session));
+    });
+    const front = (0, node_net_2.createServer)({ noDelay: true }, (socket) => {
+        let buf = null;
+        // Until handoff the h2 session's own handlers aren't attached yet: swallow socket
+        // errors (a reset mid-header) and bound how long we'll wait for the header, so a
+        // stalled connection can't hold an fd forever.
+        prehandoffSockets.add(socket);
+        socket.on('close', () => prehandoffSockets.delete(socket));
+        const onPrehandoffError = () => socket.destroy();
+        socket.on('error', onPrehandoffError);
+        const onPrehandoffTimeout = () => socket.destroy();
+        socket.setTimeout(prehandoffTimeout, onPrehandoffTimeout);
+        const handoff = (rest) => {
+            prehandoffSockets.delete(socket);
+            socket.removeListener('readable', onReadable);
+            socket.removeListener('error', onPrehandoffError);
+            socket.setTimeout(0);
+            socket.removeListener('timeout', onPrehandoffTimeout);
+            if (rest.length > 0)
+                socket.unshift(rest);
+            h2Server.emit('connection', socket);
+        };
+        const onReadable = () => {
+            let chunk;
+            while ((chunk = socket.read()) !== null) {
+                buf = buf ? Buffer.concat([buf, chunk]) : chunk;
+                // Compare against "PROXY " for as many bytes as we have so far; a non-PROXY
+                // prefix (e.g. a direct h2 client with no fronting proxy) is handed off as-is.
+                const cmpLen = Math.min(PROXY_V1_PREFIX.length, buf.length);
+                if (buf.compare(PROXY_V1_PREFIX, 0, cmpLen, 0, cmpLen) !== 0)
+                    return handoff(buf);
+                const eol = buf.indexOf('\r\n');
+                if (eol !== -1) {
+                    // Complete header: "PROXY TCP4 <src-ip> <dst-ip> <src-port> <dst-port>"
+                    const parts = buf.toString('latin1', 0, eol).split(' ');
+                    if (parts.length === 6) {
+                        // Override the UDS socket's undefined remoteAddress/remotePort with the real
+                        // client values; http2's compat req.socket proxies through to these.
+                        Object.defineProperty(socket, 'remoteAddress', { value: parts[2], configurable: true });
+                        Object.defineProperty(socket, 'remotePort', { value: parseInt(parts[4], 10), configurable: true });
+                    }
+                    return handoff(buf.subarray(eol + 2));
+                }
+                // No CRLF within the spec max — not a valid PROXY header after all.
+                if (buf.length >= PROXY_V1_MAX_HEADER)
+                    return handoff(buf);
+            }
+        };
+        socket.on('readable', onReadable);
+    });
+    const netClose = front.close.bind(front);
+    front.close = (callback) => {
+        closing = true;
+        for (const session of sessions)
+            session.close();
+        // Header-waiting sockets carry no in-flight work; drop them so they can't hold
+        // the close callback open for the rest of the pre-handoff timeout.
+        for (const socket of prehandoffSockets)
+            socket.destroy();
+        h2Server.close();
+        return netClose(callback);
+    };
+    return front;
+}
 function defaultNotFound(request, response) {
     if (response.headersSent || response.writableEnded)
         return;
@@ -1136,7 +1619,7 @@ function defaultNotFound(request, response) {
     logRequest(request, 404, 0, request.requestId);
 }
 let httpLogger;
-function logBunRequest(request, status, requestId, executionTime) {
+function logHttpRequest(request, status, requestId, executionTime) {
     const logging = httpOptions.logging;
     if (logging) {
         if (!httpLogger) {