@morojs/moro 1.7.30 → 1.8.1

package/dist/core/http/uws-http-server.js

@@ -3,27 +3,13 @@
 import cluster from 'cluster';
 import { randomUUID } from 'crypto';
 import { createFrameworkLogger } from '../logger/index.js';
-function parseUwsQueryString(queryString) {
-    const result = {};
-    if (!queryString)
-        return result;
-    const pairs = queryString.split('&');
-    for (let i = 0; i < pairs.length; i++) {
-        const pair = pairs[i];
-        const eqIdx = pair.indexOf('=');
-        if (eqIdx > 0) {
-            const key = pair.substring(0, eqIdx);
-            const value = pair.substring(eqIdx + 1);
-            try {
-                result[decodeURIComponent(key)] = decodeURIComponent(value);
-            }
-            catch {
-                result[key] = value;
-            }
-        }
-    }
-    return result;
-}
+import { loadNativeEngine, getNativeEngineLoadErrors } from '../utilities/package-utils.js';
+import { parseMultipart as parseMultipartBuffer, } from './utils/multipart-parser.js';
+import { LazyEventEmitter } from './utils/lazy-event-emitter.js';
+import { parseRawQueryString } from './utils/query-parser.js';
+import { resolveCompressionSettings, compressBuffer, isCompressible, negotiateEncoding, } from './utils/compression.js';
+// Back-compat alias (this parser is now the transport-neutral one in utils/)
+const parseUwsQueryString = parseRawQueryString;
 /**
  * Prototype-based request object for the uWS adapter.
  *
@@ -33,7 +19,7 @@ function parseUwsQueryString(queryString) {
  * so `materialize()` MUST be called before any `await` - it snapshots the
  * headers and detaches the native reference.
  */
-export class UwsRequest {
+export class UwsRequest extends LazyEventEmitter {
     method;
     path;
     url;
@@ -48,7 +34,9 @@ export class UwsRequest {
     _cookies = undefined;
     _context = undefined;
     _requestId = undefined;
+    _socket = undefined;
     constructor(server, uwsReq, method, url, queryString) {
+        super();
         this._server = server;
         this._uwsReq = uwsReq;
         this.method = method;
@@ -56,6 +44,35 @@ export class UwsRequest {
         this.url = url;
         this._queryString = queryString || null;
     }
+    // net.Socket-shaped shim so Node-style middleware (CSRF's req.socket.encrypted,
+    // rate-limiters' req.connection.remoteAddress) doesn't throw on this transport.
+    // uWS terminates plaintext HTTP here (TLS via its own listen options or a
+    // proxy); scheme detection should use x-forwarded-proto.
+    get socket() {
+        let s = this._socket;
+        if (s === undefined) {
+            const getIp = () => this.ip; // arrow captures this lexically (no this-alias)
+            s = {
+                get remoteAddress() {
+                    return getIp() || undefined;
+                },
+                remotePort: undefined,
+                encrypted: false,
+                destroyed: false,
+            };
+            this._socket = s;
+        }
+        return s;
+    }
+    set socket(value) {
+        this._socket = value;
+    }
+    get connection() {
+        return this.socket;
+    }
+    set connection(value) {
+        this._socket = value;
+    }
     /** Snapshot uWS-backed data and detach the native request. Idempotent.
      *  Must be called before returning control to the event loop if the
      *  request object outlives the synchronous route callback. */
@@ -109,6 +126,8 @@ export class UwsRequest {
                 const parts = header.split(';');
                 for (let i = 0; i < parts.length; i++) {
                     const part = parts[i];
+                    if (part === undefined)
+                        continue;
                     const eq = part.indexOf('=');
                     if (eq > 0) {
                         const name = part.substring(0, eq).trim();
@@ -157,12 +176,12 @@ export class UwsRequest {
     // ==== Express-compatible request helpers (parity with the Node adapter) ====
     get hostname() {
         const host = this.headers.host || '';
-        return host ? host.split(':')[0] : '';
+        return host ? (host.split(':')[0] ?? '') : '';
     }
     get protocol() {
         const forwardedProto = this.headers['x-forwarded-proto'];
         if (forwardedProto)
-            return forwardedProto.split(',')[0].trim();
+            return (forwardedProto.split(',')[0] ?? '').trim();
         return this._server && this._server.isSsl ? 'https' : 'http';
     }
     get secure() {
@@ -203,7 +222,7 @@ export class UwsRequest {
         const ct = this.headers['content-type'] || '';
         if (!ct)
             return false;
-        const mime = ct.split(';')[0].trim().toLowerCase();
+        const mime = (ct.split(';')[0] ?? '').trim().toLowerCase();
         const t = type.toLowerCase();
         if (t.indexOf('/') === -1) {
             return mime.endsWith(`/${t}`) || mime.endsWith(`+${t}`);
@@ -220,7 +239,7 @@ export class UwsRequest {
         const wanted = Array.isArray(types) ? types : [types];
         if (accept === '*/*' || accept === '')
             return wanted[0] || false;
-        const acceptTypes = accept.split(',').map(s => s.split(';')[0].trim().toLowerCase());
+        const acceptTypes = accept.split(',').map(s => (s.split(';')[0] ?? '').trim().toLowerCase());
         for (const w of wanted) {
             const wl = w.toLowerCase();
             const wMime = wl.indexOf('/') === -1 ? `application/${wl}` : wl;
@@ -246,7 +265,7 @@ export class UwsRequest {
             .split(',')
             .map(s => {
             const parts = s.trim().split(';');
-            const tag = parts[0].toLowerCase();
+            const tag = (parts[0] ?? '').toLowerCase();
             const qPart = parts.find(p => p.trim().startsWith('q='));
             const q = qPart ? parseFloat(qPart.trim().slice(2)) : 1;
             return { tag, q: isNaN(q) ? 0 : q };
@@ -270,6 +289,8 @@ export class UwsRequest {
 export class UWebSocketsHttpServer {
     app; // uWebSockets app instance
     uws; // uWebSockets module reference (stored to avoid re-importing)
+    _limits;
+    multipartLimits;
     listenSocket; // uWebSockets listen socket
     globalMiddleware = [];
     logger = createFrameworkLogger('UWSHttpServer');
@@ -327,6 +348,10 @@ export class UWebSocketsHttpServer {
             this.maxBodySize = options.maxBodySize;
         if (options.maxUploadSize)
             this.maxUploadSize = options.maxUploadSize;
+        if (options.limits)
+            this._limits = options.limits;
+        if (options.limits?.multipart)
+            this.multipartLimits = options.limits.multipart;
         this.initPromise = this.initialize(options);
     }
     // Direct router dispatch - called after global middleware without the
@@ -340,18 +365,34 @@ export class UWebSocketsHttpServer {
     // routes are included.
     setNativeRouteProvider(provider, onError) {
         this.nativeRouteProvider = provider;
-        this.nativeErrorHandler = onError;
+        if (onError)
+            this.nativeErrorHandler = onError;
     }
     async initialize(options) {
         try {
-            // Lazy load uWebSockets.js - only when explicitly configured
-            // This ensures it's an optional dependency with graceful fallback
-            const uwsModule = await import('uWebSockets.js');
+            // The framework preloads the engine synchronously (loadNativeEngine) and
+            // injects it; loading here directly covers standalone construction.
+            // This server is uWS-shaped only: never probe @morojs/engine, whose
+            // Moro-shaped module would pass a generic load but has no App().
+            const uwsModule = options.engineModule ?? loadNativeEngine({ candidates: ['uWebSockets.js'] })?.module;
+            if (!uwsModule) {
+                throw new Error('uWebSockets.js is not available: ' +
+                    (getNativeEngineLoadErrors().join('; ') || 'not installed'));
+            }
             this.uws = uwsModule.default || uwsModule;
+            // A TLS config that was given only as inline PEM cannot be honored by
+            // uWS (it requires on-disk file paths). Surface it loudly rather than
+            // silently booting plain HTTP (the historical footgun).
+            if (options.sslInlineOnly) {
+                this.logger.error('uWebSockets.js requires TLS key/cert as FILE PATHS (keyFile/certFile ' +
+                    'or key_file_name/cert_file_name); inline PEM is not supported. ' +
+                    'Booting WITHOUT TLS - provide file paths or use engine: "moro"/"node".', 'Init');
+            }
             if (options.ssl && options.ssl.key_file_name && options.ssl.cert_file_name) {
                 this.app = this.uws.SSLApp({
                     key_file_name: options.ssl.key_file_name,
                     cert_file_name: options.ssl.cert_file_name,
+                    ...(options.ssl.ca_file_name && { ca_file_name: options.ssl.ca_file_name }),
                     passphrase: options.ssl.passphrase,
                 });
                 this.isSsl = true;
@@ -361,15 +402,32 @@ export class UWebSocketsHttpServer {
                 this.app = this.uws.App();
                 this.logger.info('uWebSockets HTTP server created', 'Init');
             }
+            // uWS has no knobs for TCP timeouts/backlog/maxConnections/maxHeaderSize;
+            // if the user set any, say so once at startup rather than silently
+            // ignoring them (the "no arbitrary caps" contract cuts both ways).
+            const ignored = [];
+            const t = options.limits?.timeouts ?? {};
+            if (t.request || t.idle || t.keepAlive || t.headers)
+                ignored.push('timeouts');
+            if (options.limits?.maxConnections)
+                ignored.push('maxConnections');
+            if (options.limits?.backlog)
+                ignored.push('backlog');
+            if (options.limits?.maxHeaderSize || options.limits?.maxHeaders)
+                ignored.push('header limits');
+            if (ignored.length) {
+                this.logger.info(`uWebSockets.js does not support these server options; they are ignored: ${ignored.join(', ')}`, 'Init');
+            }
             // Setup generic route handler for all HTTP methods and paths
             this.setupRouteHandlers();
         }
         catch (error) {
             // Log helpful error message with installation instructions
-            this.logger.error('Failed to load uWebSockets.js (optional dependency)\n' +
-                'To use uWebSockets, install it with:\n' +
-                '  npm install --save-dev github:uNetworking/uWebSockets.js#v20.52.0\n' +
-                'Or set useUWebSockets: false in your config to use the standard HTTP server.\n' +
+            this.logger.error('Failed to load the native HTTP engine\n' +
+                'Install it with:\n' +
+                '  npm install @morojs/engine\n' +
+                '(or the legacy engine: npm install --save-dev github:uNetworking/uWebSockets.js#v20.52.0)\n' +
+                "Or set engine: 'node' in your server config to use the standard HTTP server.\n" +
                 'Error: ' +
                 (error instanceof Error ? error.message : String(error)), 'Init');
             throw error; // Re-throw so framework.ts can catch and fallback
@@ -381,7 +439,7 @@ export class UWebSocketsHttpServer {
         // method-specific routes registered later take priority in uWS's router
         // (static > parameter > wildcard).
         this.app.any('/*', (res, req) => {
-            this.handleRequest(req, res);
+            void this.handleRequest(req, res);
         });
     }
     // Register fast-path routes (no middleware/auth/validation) directly on
@@ -412,7 +470,7 @@ export class UWebSocketsHttpServer {
                 if (this.globalMiddleware.length !== 0 ||
                     (this.hookManager &&
                         (this.hookManager.hasHooks === undefined || this.hookManager.hasHooks('request')))) {
-                    this.handleRequest(req, res);
+                    void this.handleRequest(req, res);
                     return;
                 }
                 this.handleNativeRoute(req, res, handler, methodInterned, paramNames, needsBody);
@@ -429,20 +487,28 @@ export class UWebSocketsHttpServer {
         if (paramNames) {
             const params = {};
             for (let i = 0; i < paramNames.length; i++) {
-                params[paramNames[i]] = req.getParameter(i);
+                const paramName = paramNames[i];
+                if (paramName === undefined)
+                    continue;
+                params[paramName] = req.getParameter(i);
             }
             httpReq.params = params;
         }
-        const httpRes = new UWebSocketsHttpServer.ResponsePrototype().init(res, req, this.logger);
+        const httpRes = new UWebSocketsHttpServer.ResponsePrototype().init(res, req, this.logger, this._compression);
+        httpRes._moroReq = httpReq;
         if (needsBody) {
             // Body routes always go async: snapshot headers, arm the abort hook,
             // read the body, then run the handler
             httpReq.materialize();
+            res._abortArmed = true;
             res.onAborted(() => {
                 res.aborted = true;
                 const hook = res._abortHook;
                 if (hook)
                     hook();
+                const moroRes = res._moroRes;
+                if (moroRes)
+                    moroRes._handleAbort();
             });
             const contentLength = req.getHeader('content-length');
             const bodyPromise = contentLength && parseInt(contentLength) > 0
@@ -461,6 +527,7 @@ export class UWebSocketsHttpServer {
                 }
                 if (result !== undefined && !httpRes.headersSent)
                     httpRes.json(result);
+                return;
             })
                 .catch(err => this.handleNativeRouteError(err, httpReq, httpRes, res));
             return;
@@ -471,11 +538,15 @@ export class UWebSocketsHttpServer {
                 // Async handler: it is suspended at its first await - snapshot
                 // uWS-backed data and arm abort tracking before returning to the loop
                 httpReq.materialize();
+                res._abortArmed = true;
                 res.onAborted(() => {
                     res.aborted = true;
                     const hook = res._abortHook;
                     if (hook)
                         hook();
+                    const moroRes = res._moroRes;
+                    if (moroRes)
+                        moroRes._handleAbort();
                 });
                 result.then(r => {
                     if (r !== undefined && !httpRes.headersSent && !res.aborted)
@@ -486,6 +557,23 @@ export class UWebSocketsHttpServer {
                 // Fully synchronous: single corked write, no header copy, no promise
                 httpRes.json(result);
             }
+            // A synchronous handler that returned with the response still open
+            // (e.g. SSE: writeHead + periodic write) is about to hand an unfinished
+            // uWS response back to the event loop - uWS forbids that without an
+            // abort handler, and without one client disconnects are never noticed.
+            if (!httpRes.finished && !res.aborted && !res._abortArmed) {
+                res._abortArmed = true;
+                httpReq.materialize();
+                res.onAborted(() => {
+                    res.aborted = true;
+                    const hook = res._abortHook;
+                    if (hook)
+                        hook();
+                    const moroRes = res._moroRes;
+                    if (moroRes)
+                        moroRes._handleAbort();
+                });
+            }
         }
         catch (err) {
             this.handleNativeRouteError(err, httpReq, httpRes, res);
@@ -498,6 +586,12 @@ export class UWebSocketsHttpServer {
             httpRes.end('{"success":false,"error":"Request entity too large"}');
             return;
         }
+        if (err?.statusCode === 400 && !res.aborted && !httpRes.headersSent) {
+            httpRes.statusCode = 400;
+            httpRes.setHeader('Content-Type', 'application/json');
+            httpRes.end('{"success":false,"error":"Invalid request body"}');
+            return;
+        }
         const sendFallback = () => {
             if (!res.aborted && !httpRes.headersSent) {
                 // Same shape as the unified router's fast-path error response
@@ -527,6 +621,10 @@ export class UWebSocketsHttpServer {
             const hook = res._abortHook;
             if (hook)
                 hook();
+            // Fire 'close'/'aborted' on the moro wrappers (SSE/monitor cleanup)
+            const moroRes = res._moroRes;
+            if (moroRes)
+                moroRes._handleAbort();
         });
         let httpReq;
         let httpRes;
@@ -534,6 +632,7 @@ export class UWebSocketsHttpServer {
             // Create Moro-compatible request/response objects
             httpReq = this.createMoroRequest(req, res);
             httpRes = this.createMoroResponse(req, res);
+            httpRes._moroReq = httpReq;
             const method = httpReq.method;
             // Parse body only if there's actually a body (check content-length).
             // Check first char for early exit (all body methods start with 'P')
@@ -544,6 +643,12 @@ export class UWebSocketsHttpServer {
                     // readBody awaits - snapshot uWS-backed data first
                     httpReq.materialize();
                     await this.readBody(res, httpReq);
+                    // A client that disconnects mid-upload resolves readBody with a
+                    // null/partial body; do not run hooks, middleware or the handler for
+                    // a dead request (matches the native fast-path guard at ~line 625 and
+                    // the Node backend, whose aborted stream rejects parseBody).
+                    if (res.aborted)
+                        return;
                 }
             }
             // Execute hooks before request processing - skipped entirely when none registered
@@ -594,6 +699,13 @@ export class UWebSocketsHttpServer {
                 httpRes.end('{"success":false,"error":"Request entity too large"}');
                 return;
             }
+            // Malformed body: a client error (400), not a server error (500)
+            if (error?.statusCode === 400 && !res.aborted && httpRes && !httpRes.headersSent) {
+                httpRes.statusCode = 400;
+                httpRes.setHeader('Content-Type', 'application/json');
+                httpRes.end('{"success":false,"error":"Invalid request body"}');
+                return;
+            }
             this.logger.error(`Request handling error: ${error instanceof Error ? error.message : String(error)}`, 'RequestError');
             // Send error response if not already sent
             if (!res.aborted) {
@@ -620,12 +732,31 @@ export class UWebSocketsHttpServer {
         // materialize() snapshots them before the first await
         return new UwsRequest(this, req, method, url, queryString);
     }
+    // Strip CR/LF from a header value to prevent response-splitting / header
+    // injection, matching Node's setHeader ERR_INVALID_CHAR guarantee. Guarded
+    // with indexOf so the common (clean) path allocates nothing on the hot path.
+    static sanitizeHeaderValue(value) {
+        return value.indexOf('\r') === -1 && value.indexOf('\n') === -1
+            ? value
+            : value.replace(/[\r\n]/g, '');
+    }
     // Optimized helper to write headers
     static writeHeaders(res, headers) {
         // Performance: for...in is the fastest way to iterate response headers
         for (const key in headers) {
             const value = headers[key];
-            res.writeHeader(key, Array.isArray(value) ? value.join(', ') : String(value));
+            if (Array.isArray(value)) {
+                // Emit one header line per element instead of comma-joining. RFC 6265
+                // forbids folding Set-Cookie, and browsers parse a folded
+                // `a=1; Path=/, b=2` as a single cookie, silently dropping the second
+                // (session + CSRF is the canonical breakage). uWS writes a separate
+                // line per writeHeader call with the same key.
+                for (let i = 0; i < value.length; i++) {
+                    res.writeHeader(key, UWebSocketsHttpServer.sanitizeHeaderValue(String(value[i])));
+                }
+                continue;
+            }
+            res.writeHeader(key, UWebSocketsHttpServer.sanitizeHeaderValue(String(value)));
         }
     }
     // Helper to get status string (cached for performance)
@@ -633,14 +764,25 @@ export class UWebSocketsHttpServer {
         return UWebSocketsHttpServer.STATUS_STRINGS.get(code) || `${code} OK`;
     }
     // Pre-define methods on prototype instead of creating new closures for each request
-    static ResponsePrototype = class {
+    static ResponsePrototype = class extends LazyEventEmitter {
         headersSent = false;
         statusCode = 200;
         responseHeaders = {};
         _res;
         _req;
         _logger;
-        init(res, req, logger) {
+        // Terminal-write latch: headersSent means "head flushed" (true mid-stream
+        // after writeHead/write), _ended means the body is complete
+        _ended = false;
+        _drainArmed = false;
+        // Accept-Encoding captured eagerly (uWS req is valid only synchronously)
+        // and the server's compression settings, for buffered-response compression.
+        _acceptEncoding = undefined;
+        _compression = undefined;
+        // The UwsRequest wrapper, linked by the server so lifecycle events reach
+        // req.on('close') listeners (SSE cleanup, monitors)
+        _moroReq = null;
+        init(res, req, logger, compression) {
             this.headersSent = false;
             this.statusCode = 200;
             // Fresh object (a delete-loop reset would push the object into V8
@@ -649,8 +791,122 @@ export class UWebSocketsHttpServer {
             this._res = res;
             this._req = req;
             this._logger = logger;
+            this._ended = false;
+            this._drainArmed = false;
+            this._compression = compression;
+            // Capture Accept-Encoding now: the native req is valid only during the
+            // synchronous handler entry, but compression resolves asynchronously.
+            this._acceptEncoding =
+                compression?.enabled && req ? req.getHeader('accept-encoding') || undefined : undefined;
+            // Route client aborts to the wrapper so 'close' fires (see onAborted)
+            res._moroRes = this;
             return this;
         }
+        // Buffered-response compression for uWS (parity with the engine/Node
+        // paths). Returns true when it took over the write (async), false when the
+        // caller should proceed with its normal synchronous cork+end.
+        _tryCompressedEnd(body, contentType) {
+            const s = this._compression;
+            if (!s || !s.enabled)
+                return false;
+            const bytes = typeof body === 'string' ? Buffer.byteLength(body) : body.length;
+            if (bytes < s.threshold)
+                return false;
+            if ('content-encoding' in this.responseHeaders)
+                return false;
+            if (this.statusCode === 204 || this.statusCode === 304)
+                return false;
+            const ctHeader = this.responseHeaders['content-type'];
+            const ct = contentType ?? (Array.isArray(ctHeader) ? ctHeader[0] : ctHeader);
+            if (!isCompressible(ct))
+                return false;
+            const encoding = negotiateEncoding(this._acceptEncoding, s.encodings);
+            if (!encoding)
+                return false;
+            void compressBuffer(body, encoding, s.level)
+                .then(compressed => {
+                if (this._ended || this._res.aborted)
+                    return;
+                this.responseHeaders['content-encoding'] = encoding;
+                const vary = this.responseHeaders['vary'];
+                this.responseHeaders['vary'] = vary ? `${vary}, Accept-Encoding` : 'Accept-Encoding';
+                this._res.cork(() => {
+                    this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
+                    UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                    this._res.end(compressed);
+                });
+                this.headersSent = true;
+                this._ended = true;
+                this._emitDone();
+            })
+                .catch((err) => {
+                this._logger?.error?.(`uWS response compression failed: ${err instanceof Error ? err.message : String(err)}`, 'Response');
+                if (this._ended || this._res.aborted)
+                    return;
+                this._res.cork(() => {
+                    this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
+                    UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                    this._res.end(body);
+                });
+                this.headersSent = true;
+                this._ended = true;
+                this._emitDone();
+            });
+            return true;
+        }
+        get writableEnded() {
+            return this._ended;
+        }
+        get writableFinished() {
+            return this._ended;
+        }
+        get finished() {
+            return this._ended;
+        }
+        // Node ServerResponse lifecycle: 'finish' then 'close' after the terminal
+        // write; the request wrapper's 'close' fires too (IncomingMessage parity).
+        // No listeners -> two null checks, nothing else.
+        _emitDone() {
+            this._ended = true;
+            if (this._events) {
+                this.emit('finish');
+                this.emit('close');
+            }
+            const req = this._moroReq;
+            if (req && req._events)
+                req.emit('close');
+        }
+        // Client aborted: 'close' without 'finish' (Node semantics), plus
+        // 'aborted'/'close' on the request wrapper
+        _handleAbort() {
+            if (this._ended)
+                return;
+            this._ended = true;
+            if (this._events)
+                this.emit('close');
+            const req = this._moroReq;
+            if (req && req._events) {
+                req.emit('aborted');
+                req.emit('close');
+            }
+        }
+        // Backpressure: surface uWS's onWritable as the 'drain' event pipe()
+        // and manual streaming loops wait on
+        _armDrain() {
+            if (this._drainArmed)
+                return;
+            this._drainArmed = true;
+            try {
+                this._res.onWritable(() => {
+                    this._drainArmed = false;
+                    this.emit('drain');
+                    return true;
+                });
+            }
+            catch {
+                this._drainArmed = false;
+            }
+        }
         status(code) {
             this.statusCode = code;
             return this;
@@ -678,7 +934,12 @@ export class UWebSocketsHttpServer {
                 return;
             // Fast-path JSON serialization for common API patterns
             let body;
-            if (data && typeof data === 'object' && 'success' in data) {
+            // The interpolated fast path is only valid when `success` is a real
+            // boolean (a string/number would produce invalid JSON like
+            // {"success":yes,...}), and each interpolated field must be defined
+            // (JSON.stringify(undefined) yields the literal token "undefined", which
+            // would corrupt the body). Otherwise fall through to JSON.stringify.
+            if (data && typeof data === 'object' && typeof data.success === 'boolean') {
                 let keyCount = 0;
                 let hasData = false;
                 let hasError = false;
@@ -694,16 +955,24 @@ export class UWebSocketsHttpServer {
                             hasTotal = true;
                     }
                 }
-                if (keyCount === 3 && hasData && hasError) {
+                if (keyCount === 3 &&
+                    hasData &&
+                    hasError &&
+                    data.data !== undefined &&
+                    data.error !== undefined) {
                     body = `{"success":${data.success},"data":${JSON.stringify(data.data)},"error":${JSON.stringify(data.error)}}`;
                 }
-                else if (keyCount === 3 && hasData && hasTotal) {
+                else if (keyCount === 3 &&
+                    hasData &&
+                    hasTotal &&
+                    data.data !== undefined &&
+                    typeof data.total === 'number') {
                     body = `{"success":${data.success},"data":${JSON.stringify(data.data)},"total":${data.total}}`;
                 }
-                else if (keyCount === 2 && hasData) {
+                else if (keyCount === 2 && hasData && data.data !== undefined) {
                     body = `{"success":${data.success},"data":${JSON.stringify(data.data)}}`;
                 }
-                else if (keyCount === 2 && hasError) {
+                else if (keyCount === 2 && hasError && data.error !== undefined) {
                     body = `{"success":${data.success},"error":${JSON.stringify(data.error)}}`;
                 }
                 else {
@@ -717,12 +986,17 @@ export class UWebSocketsHttpServer {
                 this.responseHeaders['content-type'] = 'application/json';
             }
             try {
+                // Compression (when enabled + compressible + accepted) takes over the
+                // write asynchronously; otherwise the synchronous corked path runs.
+                if (this._tryCompressedEnd(body, 'application/json'))
+                    return;
                 this._res.cork(() => {
                     this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
                     UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
                     this._res.end(body);
                 });
                 this.headersSent = true;
+                this._emitDone();
             }
             catch {
                 this._logger.error('Failed to send JSON response', 'ResponseError');
@@ -733,30 +1007,103 @@ export class UWebSocketsHttpServer {
                 return;
             const body = typeof data === 'string' ? data : data.toString();
             try {
+                if (this._tryCompressedEnd(body, undefined))
+                    return;
                 this._res.cork(() => {
                     this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
                     UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
                     this._res.end(body);
                 });
                 this.headersSent = true;
+                this._emitDone();
             }
             catch {
                 this._logger.error('Failed to send response', 'ResponseError');
             }
         }
+        // Flush status + headers without ending the response (Node streaming
+        // entry point - SSE and manual chunked responses start here). Supports
+        // both (code, headers) and (code, statusMessage, headers) signatures;
+        // uWS derives the reason phrase from the status string, so a custom
+        // message is folded into it.
+        writeHead(statusCode, reasonOrHeaders, maybeHeaders) {
+            if (this.headersSent || this._res.aborted)
+                return this;
+            this.statusCode = statusCode;
+            const headers = reasonOrHeaders && typeof reasonOrHeaders === 'object' ? reasonOrHeaders : maybeHeaders;
+            if (headers) {
+                for (const key of Object.keys(headers)) {
+                    this.setHeader(key, headers[key]);
+                }
+            }
+            try {
+                this._res.cork(() => {
+                    const status = typeof reasonOrHeaders === 'string'
+                        ? `${statusCode} ${reasonOrHeaders}`
+                        : UWebSocketsHttpServer.getStatusString(statusCode);
+                    this._res.writeStatus(status);
+                    UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                });
+                this.headersSent = true;
+            }
+            catch {
+                this._logger.error('Failed to write response head', 'ResponseError');
+            }
+            return this;
+        }
+        // Stream a body chunk, flushing the head first if needed. Returns uWS's
+        // backpressure signal like Node's Writable.write; 'drain' fires when the
+        // socket can accept more.
+        write(chunk, encoding, callback) {
+            if (typeof encoding === 'function') {
+                callback = encoding;
+                encoding = undefined;
+            }
+            if (this._ended || this._res.aborted)
+                return false;
+            let ok = true;
+            try {
+                this._res.cork(() => {
+                    if (!this.headersSent) {
+                        this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
+                        UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                        this.headersSent = true;
+                    }
+                    ok = this._res.write(chunk);
+                });
+            }
+            catch {
+                this._logger.error('Failed to write response chunk', 'ResponseError');
+                return false;
+            }
+            if (!ok)
+                this._armDrain();
+            if (typeof callback === 'function')
+                callback();
+            return ok;
+        }
         end(data, encoding, callback) {
-            if (this.headersSent || this._res.aborted) {
+            if (typeof encoding === 'function') {
+                callback = encoding;
+                encoding = undefined;
+            }
+            // Guard on _ended, not headersSent: in streaming mode (writeHead/write)
+            // the head is already flushed and end() must still complete the body
+            if (this._ended || this._res.aborted) {
                 if (typeof callback === 'function')
                     callback();
                 return this;
             }
             try {
                 this._res.cork(() => {
-                    this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
-                    UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                    if (!this.headersSent) {
+                        this._res.writeStatus(UWebSocketsHttpServer.getStatusString(this.statusCode));
+                        UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
+                        this.headersSent = true;
+                    }
                     this._res.end(data || '');
                 });
-                this.headersSent = true;
+                this._emitDone();
                 if (typeof callback === 'function')
                     callback();
             }
@@ -775,11 +1122,12 @@ export class UWebSocketsHttpServer {
             try {
                 this._res.cork(() => {
                     this._res.writeStatus(UWebSocketsHttpServer.getStatusString(redirectCode));
-                    this._res.writeHeader('Location', url);
+                    this._res.writeHeader('Location', UWebSocketsHttpServer.sanitizeHeaderValue(url));
                     UWebSocketsHttpServer.writeHeaders(this._res, this.responseHeaders);
                     this._res.end();
                 });
                 this.headersSent = true;
+                this._emitDone();
             }
             catch {
                 this._logger.error('Failed to send redirect', 'ResponseError');
@@ -918,32 +1266,25 @@ export class UWebSocketsHttpServer {
                 },
             });
         }
-        // EventEmitter stubs for middleware compatibility
-        on(_event, _callback) {
-            return this;
-        }
-        once(_event, _callback) {
-            return this;
-        }
-        emit(_event, ..._args) {
-            return true;
-        }
-        removeListener(_event, _callback) {
-            return this;
-        }
         cookie(name, value, options) {
-            // Build cookie string with array join for better performance
-            const parts = [name, '=', value];
+            // Percent-encode the value (matches the Node path and Express) so a value
+            // containing ';'/',' can't inject cookie attributes and control chars
+            // don't corrupt the Set-Cookie header.
+            const parts = [name, '=', encodeURIComponent(value)];
             if (options) {
-                if (options.maxAge) {
+                // maxAge: 0 is meaningful (immediate expiry - clearCookie relies on it)
+                if (options.maxAge !== undefined && options.maxAge !== null) {
                     parts.push('; Max-Age=', String(options.maxAge));
                 }
+                if (options.expires) {
+                    const expires = options.expires instanceof Date
+                        ? options.expires.toUTCString()
+                        : String(options.expires);
+                    parts.push('; Expires=', expires);
+                }
                 if (options.domain) {
                     parts.push('; Domain=', options.domain);
                 }
-                if (options.path) {
-                    parts.push('; Path=', options.path);
-                }
                 if (options.secure) {
                     parts.push('; Secure');
                 }
@@ -954,6 +1295,9 @@ export class UWebSocketsHttpServer {
                     parts.push('; SameSite=', options.sameSite);
                 }
             }
+            // Path defaults to '/' (Express behavior) so clearCookie() from a nested
+            // route can clear a cookie originally set at the site root.
+            parts.push('; Path=', options?.path ?? '/');
             const cookie = parts.join('');
             const lowerKey = 'set-cookie';
             const existing = this.responseHeaders[lowerKey];
@@ -1109,8 +1453,8 @@ export class UWebSocketsHttpServer {
                 headersSent: this.headersSent,
                 statusCode: this.statusCode,
                 headers: this.responseHeaders,
-                finished: this.headersSent,
-                writable: !this.headersSent,
+                finished: this._ended,
+                writable: !this._ended,
             };
         }
     };
@@ -1181,15 +1525,34 @@ export class UWebSocketsHttpServer {
                         });
                         httpReq.body = body;
                     }
+                    else if (isMultipart) {
+                        // Shared parser (same as the Node http server) - stringifying
+                        // multipart would corrupt binary uploads and lose fields/files.
+                        // parseMultipart retains slices of the payload as file Buffers;
+                        // the single-chunk fast path (buffer === view) aliases uWS-owned
+                        // memory that is recycled after this callback returns, so copy
+                        // it first. Concatenated multi-chunk buffers are already stable.
+                        const stable = buffer === view ? Buffer.from(buffer) : buffer;
+                        httpReq.body = parseMultipartBuffer(stable, contentType, this.multipartLimits);
+                    }
                     else {
                         httpReq.body = buffer.toString('utf-8');
                     }
                     finish(resolve);
                 }
-                catch {
-                    this.logger.error('Failed to parse request body', 'BodyParseError');
-                    httpReq.body = null;
-                    finish(resolve);
+                catch (parseError) {
+                    // A limit error (multipart maxParts/maxFiles/maxFileSize) carries its
+                    // own 413 - preserve it rather than masking it as a generic 400.
+                    if (parseError && typeof parseError.statusCode === 'number') {
+                        finish(() => reject(parseError));
+                        return;
+                    }
+                    // A malformed body is a client error: reject with 400 (parity with
+                    // the engine and Node transports) rather than silently handing the
+                    // handler a null body it may treat as "no input".
+                    const error = new Error(`Invalid request body: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+                    error.statusCode = 400;
+                    finish(() => reject(error));
                 }
             });
             // Chain onto the request-lifetime abort hook (registered in handleRequest
@@ -1250,10 +1613,14 @@ export class UWebSocketsHttpServer {
     setHookManager(hookManager) {
         this.hookManager = hookManager;
     }
-    configurePerformance(_config) {
-        // uWebSockets is already highly optimized
-        // This method exists for API compatibility
-        this.logger.debug('Performance configuration noted (uWebSockets is pre-optimized)', 'Config');
+    /** @internal buffered-response compression settings (read at init). */
+    _compression = resolveCompressionSettings();
+    configurePerformance(config) {
+        // uWS batches the request hot path natively; response compression is the
+        // one thing it doesn't do itself, so wire that here (parity with Node/
+        // engine). Buffered responses only - streaming stays raw.
+        this._compression = resolveCompressionSettings(config);
+        this.logger.debug(`Performance configured (compression ${this._compression.enabled ? 'on' : 'off'})`, 'Config');
     }
     listen(port, hostOrCallback, callback) {
         // Wrap in async to await init
@@ -1280,24 +1647,36 @@ export class UWebSocketsHttpServer {
             // uWebSockets.js automatically enables SO_REUSEPORT when in cluster mode
             // Do NOT pass listenOptions in cluster mode - let uWS handle it automatically
             // In non-cluster mode, we don't need SO_REUSEPORT
-            this.app.listen(port, (token) => {
+            const onListen = (token) => {
                 if (token) {
                     this.listenSocket = token;
                     this.isListening = true;
                     const clusterInfo = isClusterWorker ? ` (worker ${process.pid})` : '';
-                    this.logger.info(`uWebSockets HTTP server listening on 0.0.0.0:${port}${clusterInfo}`, 'Listen');
+                    this.logger.info(`uWebSockets HTTP server listening on ${host}:${port}${clusterInfo}`, 'Listen');
                     if (cb)
                         cb();
                 }
                 else {
                     const clusterInfo = isClusterWorker ? ` (worker ${process.pid})` : '';
-                    this.logger.error(`Failed to listen on port ${port}${clusterInfo}`, 'Listen');
+                    this.logger.error(`Failed to listen on ${host}:${port}${clusterInfo}`, 'Listen');
                     // Don't throw in cluster workers - let them fail gracefully
                     if (!isClusterWorker) {
-                        throw new Error(`Failed to bind to port ${port}`);
+                        throw new Error(`Failed to bind to ${host}:${port}`);
                     }
                 }
-            });
+            };
+            // Honor the requested bind host. For the all-interfaces default (and
+            // cluster mode, where uWS auto-enables SO_REUSEPORT) keep the 2-arg
+            // form so that behavior is unchanged; when a specific host is given
+            // (e.g. 127.0.0.1 for an internal/admin service behind a proxy) use
+            // uWS's (host, port, cb) overload so we don't silently bind 0.0.0.0.
+            const bindAllInterfaces = host === '0.0.0.0' || host === '::';
+            if (bindAllInterfaces) {
+                this.app.listen(port, onListen);
+            }
+            else {
+                this.app.listen(host, port, onListen);
+            }
         })
             .catch(error => {
             this.logger.error('Failed to initialize server before listen', 'Listen', {