@morojs/moro 1.7.27 → 1.7.29

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

@@ -1,25 +1,889 @@
 // src/core/http-server.ts
-import { createServer } from 'http';
+import { IncomingMessage, ServerResponse, createServer } from 'http';
 import * as zlib from 'zlib';
 import { promisify } from 'util';
+import { randomUUID } from 'crypto';
 import { createFrameworkLogger } from '../logger/index.js';
 import { PathMatcher } from '../routing/path-matcher.js';
 import { ObjectPoolManager } from '../pooling/object-pool-manager.js';
 const gzip = promisify(zlib.gzip);
 const deflate = promisify(zlib.deflate);
+const JSON_CONTENT_TYPE = 'application/json; charset=utf-8';
+const STATUS_MESSAGES = {
+    200: 'OK',
+    201: 'Created',
+    202: 'Accepted',
+    204: 'No Content',
+    301: 'Moved Permanently',
+    302: 'Found',
+    304: 'Not Modified',
+    400: 'Bad Request',
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    409: 'Conflict',
+    410: 'Gone',
+    422: 'Unprocessable Entity',
+    429: 'Too Many Requests',
+    500: 'Internal Server Error',
+    502: 'Bad Gateway',
+    503: 'Service Unavailable',
+};
+const TYPE_SHORTHANDS = {
+    json: 'application/json; charset=utf-8',
+    html: 'text/html; charset=utf-8',
+    text: 'text/plain; charset=utf-8',
+    txt: 'text/plain; charset=utf-8',
+    xml: 'application/xml',
+    js: 'application/javascript',
+    css: 'text/css; charset=utf-8',
+    form: 'application/x-www-form-urlencoded',
+};
+function parseQueryString(queryString) {
+    const result = {};
+    if (!queryString)
+        return result;
+    const pairs = queryString.split('&');
+    const pairsLen = pairs.length;
+    for (let i = 0; i < pairsLen; i++) {
+        const pair = pairs[i];
+        const equalIndex = pair.indexOf('=');
+        if (equalIndex === -1) {
+            result[decodeURIComponent(pair)] = '';
+        }
+        else {
+            const key = decodeURIComponent(pair.substring(0, equalIndex));
+            const value = decodeURIComponent(pair.substring(equalIndex + 1));
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function parseCookieHeader(cookieHeader) {
+    const cookies = {};
+    if (!cookieHeader)
+        return cookies;
+    const cookieParts = cookieHeader.split(';');
+    const cookiePartsLen = cookieParts.length;
+    for (let i = 0; i < cookiePartsLen; i++) {
+        const cookie = cookieParts[i];
+        const equalIndex = cookie.indexOf('=');
+        if (equalIndex > 0) {
+            const name = cookie.substring(0, equalIndex).trim();
+            const value = cookie.substring(equalIndex + 1);
+            if (name && value) {
+                try {
+                    cookies[name] = decodeURIComponent(value);
+                }
+                catch {
+                    // Malformed percent-encoding: keep the raw value rather than throwing a 500
+                    cookies[name] = value;
+                }
+            }
+        }
+    }
+    return cookies;
+}
+// ---------------------------------------------------------------------------
+// Prototype-based request/response enhancement.
+//
+// All helper methods live on shared prototypes (defined once per process)
+// instead of being re-created as ~40 closures on every request, and derived
+// request fields (query, cookies, hostname, ips, ...) are lazy memoized
+// getters so a request only pays for what its handler actually reads.
+// Each MoroHttpServer binds per-instance subclasses whose prototype carries
+// the `_server` back-reference, so methods can reach server config (logger,
+// compression settings) without any per-request allocation.
+// ---------------------------------------------------------------------------
+export class MoroIncomingMessage extends IncomingMessage {
+    // Hot per-request fields (assigned in handleRequest; declared here for stable shape)
+    params = {};
+    body = null;
+    path = '';
+    // Lazy backing fields - single hidden-class shape, created at construction
+    _queryString = null;
+    _query = undefined;
+    _cookies = undefined;
+    _context = undefined;
+    _requestId = undefined;
+    _ip = undefined;
+    _originalUrl = undefined;
+    _hostname = undefined;
+    _protocol = undefined;
+    _secure = undefined;
+    _xhr = undefined;
+    _ips = undefined;
+    _subdomains = undefined;
+    get query() {
+        let q = this._query;
+        if (q === undefined) {
+            const qs = this._queryString;
+            q = qs ? parseQueryString(qs) : {};
+            this._query = q;
+        }
+        return q;
+    }
+    set query(value) {
+        this._query = value;
+    }
+    get cookies() {
+        let c = this._cookies;
+        if (c === undefined) {
+            const header = this.headers.cookie;
+            c = header ? parseCookieHeader(header) : {};
+            this._cookies = c;
+        }
+        return c;
+    }
+    set cookies(value) {
+        this._cookies = value;
+    }
+    get context() {
+        let ctx = this._context;
+        if (ctx === undefined) {
+            ctx = {};
+            this._context = ctx;
+        }
+        return ctx;
+    }
+    set context(value) {
+        this._context = value;
+    }
+    get requestId() {
+        let id = this._requestId;
+        if (id === undefined) {
+            const server = this._server;
+            id = server && server.requestTrackingEnabled ? randomUUID() : '';
+            this._requestId = id;
+        }
+        return id;
+    }
+    set requestId(value) {
+        this._requestId = value;
+    }
+    get ip() {
+        let v = this._ip;
+        if (v === undefined) {
+            v = (this.socket && this.socket.remoteAddress) || '';
+            this._ip = v;
+        }
+        return v;
+    }
+    set ip(value) {
+        this._ip = value;
+    }
+    get originalUrl() {
+        const v = this._originalUrl;
+        return v !== undefined ? v : this.url || '';
+    }
+    set originalUrl(value) {
+        this._originalUrl = value;
+    }
+    get hostname() {
+        let v = this._hostname;
+        if (v === undefined) {
+            const host = (this.headers.host || '');
+            v = host ? host.split(':')[0] : '';
+            this._hostname = v;
+        }
+        return v;
+    }
+    set hostname(value) {
+        this._hostname = value;
+    }
+    get protocol() {
+        let v = this._protocol;
+        if (v === undefined) {
+            const forwardedProto = this.headers['x-forwarded-proto'];
+            v = forwardedProto
+                ? forwardedProto.split(',')[0].trim()
+                : this.socket?.encrypted
+                    ? 'https'
+                    : 'http';
+            this._protocol = v;
+        }
+        return v;
+    }
+    set protocol(value) {
+        this._protocol = value;
+    }
+    get secure() {
+        const v = this._secure;
+        return v !== undefined ? v : this.protocol === 'https';
+    }
+    set secure(value) {
+        this._secure = value;
+    }
+    get xhr() {
+        let v = this._xhr;
+        if (v === undefined) {
+            const xrw = this.headers['x-requested-with'];
+            v = !!xrw && xrw.toLowerCase() === 'xmlhttprequest';
+            this._xhr = v;
+        }
+        return v;
+    }
+    set xhr(value) {
+        this._xhr = value;
+    }
+    get ips() {
+        let v = this._ips;
+        if (v === undefined) {
+            const forwardedFor = this.headers['x-forwarded-for'];
+            v = forwardedFor
+                ? forwardedFor
+                    .split(',')
+                    .map(s => s.trim())
+                    .filter(Boolean)
+                : [];
+            this._ips = v;
+        }
+        return v;
+    }
+    set ips(value) {
+        this._ips = value;
+    }
+    get subdomains() {
+        let v = this._subdomains;
+        if (v === undefined) {
+            const hostnameParts = this.hostname.split('.');
+            // Matches Express: subdomains are parts before the last two (domain + tld),
+            // reversed (closest subdomain first).
+            v = hostnameParts.length > 2 ? hostnameParts.slice(0, -2).reverse() : [];
+            this._subdomains = v;
+        }
+        return v;
+    }
+    set subdomains(value) {
+        this._subdomains = value;
+    }
+    // Express-compatible request helpers (shared prototype methods, not closures)
+    get(name) {
+        const lower = name.toLowerCase();
+        if (lower === 'referer' || lower === 'referrer') {
+            return (this.headers.referer || this.headers.referrer);
+        }
+        const v = this.headers[lower];
+        return Array.isArray(v) ? v[0] : v;
+    }
+    header(name) {
+        return this.get(name);
+    }
+    is(type) {
+        const ct = (this.headers['content-type'] || '');
+        if (!ct)
+            return false;
+        const mime = ct.split(';')[0].trim().toLowerCase();
+        const t = type.toLowerCase();
+        if (t.indexOf('/') === -1) {
+            // e.g. 'json' → match */json or +json suffix
+            return mime.endsWith(`/${t}`) || mime.endsWith(`+${t}`);
+        }
+        if (t.endsWith('/*')) {
+            return mime.startsWith(t.slice(0, -1));
+        }
+        return mime === t;
+    }
+    accepts(types) {
+        const accept = (this.headers.accept || '*/*');
+        if (!types)
+            return accept;
+        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());
+        for (const w of wanted) {
+            const wl = w.toLowerCase();
+            const wMime = wl.indexOf('/') === -1 ? `application/${wl}` : wl;
+            for (const at of acceptTypes) {
+                if (at === '*/*')
+                    return w;
+                if (at === wMime)
+                    return w;
+                if (at.endsWith('/*') && wMime.startsWith(at.slice(0, -1)))
+                    return w;
+            }
+        }
+        return false;
+    }
+    acceptsLanguages(langs) {
+        const acceptLang = (this.headers['accept-language'] || '');
+        if (!langs)
+            return acceptLang || false;
+        const wanted = Array.isArray(langs) ? langs : [langs];
+        if (!acceptLang)
+            return wanted[0] || false;
+        // Parse with q values; sort by q desc to match Express's "best match wins"
+        const accepted = acceptLang
+            .split(',')
+            .map(s => {
+            const parts = s.trim().split(';');
+            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 };
+        })
+            .filter(a => a.q > 0)
+            .sort((a, b) => b.q - a.q);
+        for (const { tag } of accepted) {
+            for (const w of wanted) {
+                const wl = w.toLowerCase();
+                if (tag === '*' || tag === wl || tag.split('-')[0] === wl.split('-')[0])
+                    return w;
+            }
+        }
+        return false;
+    }
+}
+export class MoroServerResponse extends ServerResponse {
+    _locals = undefined;
+    get locals() {
+        let l = this._locals;
+        if (l === undefined) {
+            l = {};
+            this._locals = l;
+        }
+        return l;
+    }
+    set locals(value) {
+        this._locals = value;
+    }
+    status(code) {
+        this.statusCode = code;
+        return this;
+    }
+    json(data) {
+        if (this.headersSent)
+            return;
+        const jsonString = JSON.stringify(data);
+        const server = this._server;
+        // Compression - EARLY EXIT if disabled or below threshold
+        if (server && server.compressionEnabled && jsonString.length > server.compressionThreshold) {
+            const acceptEncoding = this.req?.headers['accept-encoding'];
+            if (acceptEncoding && acceptEncoding.includes('gzip')) {
+                const buffer = Buffer.from(jsonString, 'utf8');
+                gzip(buffer)
+                    .then(compressed => {
+                    if (this.headersSent)
+                        return;
+                    this.writeHead(this.statusCode || 200, {
+                        'Content-Type': JSON_CONTENT_TYPE,
+                        'Content-Encoding': 'gzip',
+                        Vary: 'Accept-Encoding',
+                        'Content-Length': compressed.length,
+                    });
+                    this.end(compressed);
+                })
+                    .catch(err => {
+                    server.logger.error('Response compression failed', 'HttpServer', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    if (!this.headersSent) {
+                        this.writeHead(this.statusCode || 200, {
+                            'Content-Type': JSON_CONTENT_TYPE,
+                            'Content-Length': Buffer.byteLength(jsonString),
+                        });
+                        this.end(jsonString);
+                    }
+                    else {
+                        this.end();
+                    }
+                });
+                return;
+            }
+            else if (acceptEncoding && acceptEncoding.includes('deflate')) {
+                const buffer = Buffer.from(jsonString, 'utf8');
+                deflate(buffer)
+                    .then(compressed => {
+                    if (this.headersSent)
+                        return;
+                    this.writeHead(this.statusCode || 200, {
+                        'Content-Type': JSON_CONTENT_TYPE,
+                        'Content-Encoding': 'deflate',
+                        Vary: 'Accept-Encoding',
+                        'Content-Length': compressed.length,
+                    });
+                    this.end(compressed);
+                })
+                    .catch(err => {
+                    server.logger.error('Response compression failed', 'HttpServer', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                    if (!this.headersSent) {
+                        this.writeHead(this.statusCode || 200, {
+                            'Content-Type': JSON_CONTENT_TYPE,
+                            'Content-Length': Buffer.byteLength(jsonString),
+                        });
+                        this.end(jsonString);
+                    }
+                    else {
+                        this.end();
+                    }
+                });
+                return;
+            }
+        }
+        // SYNC PATH - no compression: single serialize, single write, no Buffer copy
+        this.writeHead(this.statusCode || 200, {
+            'Content-Type': JSON_CONTENT_TYPE,
+            'Content-Length': Buffer.byteLength(jsonString),
+        });
+        this.end(jsonString);
+    }
+    send(data) {
+        if (this.headersSent)
+            return;
+        // Auto-detect content type if not already set
+        if (!this.getHeader('Content-Type')) {
+            if (typeof data === 'string') {
+                // Cheap JSON sniff: first non-whitespace char is '{', '[' or '"'
+                // (replaces a full JSON.parse of the body just to pick a content type)
+                let i = 0;
+                const len = data.length;
+                while (i < len) {
+                    const c = data.charCodeAt(i);
+                    if (c !== 32 && c !== 9 && c !== 10 && c !== 13)
+                        break;
+                    i++;
+                }
+                const first = i < len ? data.charCodeAt(i) : 0;
+                if (first === 123 /* { */ || first === 91 /* [ */ || first === 34 /* " */) {
+                    this.setHeader('Content-Type', JSON_CONTENT_TYPE);
+                }
+                else {
+                    this.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                }
+            }
+            else {
+                this.setHeader('Content-Type', 'application/octet-stream');
+            }
+        }
+        this.end(data);
+    }
+    cookie(name, value, options = {}) {
+        if (this.headersSent) {
+            const isCritical = options.critical ||
+                name.includes('session') ||
+                name.includes('auth') ||
+                name.includes('csrf');
+            const message = `Cookie '${name}' could not be set - headers already sent`;
+            if (isCritical || options.throwOnLateSet) {
+                throw new Error(`${message}. This may cause authentication or security issues.`);
+            }
+            else {
+                this._server?.logger.warn(message, 'CookieWarning', {
+                    cookieName: name,
+                    critical: isCritical,
+                    stackTrace: new Error().stack,
+                });
+            }
+            return this;
+        }
+        const cookieValue = encodeURIComponent(value);
+        let cookieString = `${name}=${cookieValue}`;
+        if (options.maxAge)
+            cookieString += `; Max-Age=${options.maxAge}`;
+        if (options.expires)
+            cookieString += `; Expires=${options.expires.toUTCString()}`;
+        if (options.httpOnly)
+            cookieString += '; HttpOnly';
+        if (options.secure)
+            cookieString += '; Secure';
+        if (options.sameSite)
+            cookieString += `; SameSite=${options.sameSite}`;
+        if (options.domain)
+            cookieString += `; Domain=${options.domain}`;
+        if (options.path)
+            cookieString += `; Path=${options.path}`;
+        const existingCookies = this.getHeader('Set-Cookie') || [];
+        // Avoid spread operator - direct array manipulation
+        const cookies = Array.isArray(existingCookies) ? existingCookies : [existingCookies];
+        cookies.push(cookieString);
+        this.setHeader('Set-Cookie', cookies);
+        return this;
+    }
+    clearCookie(name, options = {}) {
+        // Avoid spread operator - manually set properties
+        const clearOptions = {
+            expires: new Date(0),
+            maxAge: 0,
+        };
+        // Copy other options manually
+        if (options.path !== undefined)
+            clearOptions.path = options.path;
+        if (options.domain !== undefined)
+            clearOptions.domain = options.domain;
+        if (options.httpOnly !== undefined)
+            clearOptions.httpOnly = options.httpOnly;
+        if (options.secure !== undefined)
+            clearOptions.secure = options.secure;
+        if (options.sameSite !== undefined)
+            clearOptions.sameSite = options.sameSite;
+        return this.cookie(name, '', clearOptions);
+    }
+    redirect(url, status = 302) {
+        if (this.headersSent)
+            return;
+        this.statusCode = status;
+        const safeUrl = url.replace(/[\r\n]/g, '');
+        this.setHeader('Location', safeUrl);
+        this.end();
+    }
+    async sendFile(filePath) {
+        if (this.headersSent)
+            return;
+        try {
+            const fs = await import('fs/promises');
+            const path = await import('path');
+            const extension = path.extname(filePath);
+            const mime = await this._server.getMimeType(extension);
+            const stats = await fs.stat(filePath);
+            const data = await fs.readFile(filePath);
+            // Add charset for text-based files
+            const contentType = this._server.addCharsetIfNeeded(mime);
+            this.setHeader('Content-Type', contentType);
+            this.setHeader('Content-Length', stats.size);
+            // Add security headers for file downloads
+            this.setHeader('X-Content-Type-Options', 'nosniff');
+            // Add caching headers
+            this.setHeader('Last-Modified', stats.mtime.toUTCString());
+            this.setHeader('Cache-Control', 'public, max-age=31536000'); // 1 year for static files
+            this.end(data);
+        }
+        catch {
+            this.status(404).json({ success: false, error: 'File not found' });
+        }
+    }
+    // Standardized response helpers
+    success(data, message) {
+        const response = {
+            success: true,
+            data,
+        };
+        if (message !== undefined) {
+            response.message = message;
+        }
+        this.json(response);
+    }
+    error(error, code, message) {
+        const response = {
+            success: false,
+            error,
+        };
+        if (code !== undefined) {
+            response.code = code;
+        }
+        if (message !== undefined) {
+            response.message = message;
+        }
+        this.json(response);
+    }
+    // Common HTTP error helpers (automatically set status code)
+    unauthorized(message = 'Authentication required') {
+        this.statusCode = 401;
+        this.json({
+            success: false,
+            error: 'Unauthorized',
+            code: 'UNAUTHORIZED',
+            message,
+        });
+    }
+    forbidden(message = 'Insufficient permissions') {
+        this.statusCode = 403;
+        this.json({
+            success: false,
+            error: 'Forbidden',
+            code: 'FORBIDDEN',
+            message,
+        });
+    }
+    notFound(resource = 'Resource') {
+        this.statusCode = 404;
+        this.json({
+            success: false,
+            error: 'Not Found',
+            code: 'NOT_FOUND',
+            message: `${resource} not found`,
+        });
+    }
+    badRequest(message = 'Invalid request') {
+        this.statusCode = 400;
+        this.json({
+            success: false,
+            error: 'Bad Request',
+            code: 'BAD_REQUEST',
+            message,
+        });
+    }
+    conflict(message) {
+        this.statusCode = 409;
+        this.json({
+            success: false,
+            error: 'Conflict',
+            code: 'CONFLICT',
+            message,
+        });
+    }
+    internalError(message = 'Internal server error') {
+        this.statusCode = 500;
+        this.json({
+            success: false,
+            error: 'Internal Server Error',
+            code: 'INTERNAL_ERROR',
+            message,
+        });
+    }
+    validationError(errors) {
+        this.statusCode = 422;
+        this.json({
+            success: false,
+            error: 'Validation Failed',
+            code: 'VALIDATION_ERROR',
+            errors,
+        });
+    }
+    rateLimited(retryAfter) {
+        this.statusCode = 429;
+        if (retryAfter) {
+            this.setHeader('Retry-After', retryAfter.toString());
+        }
+        this.json({
+            success: false,
+            error: 'Rate Limit Exceeded',
+            code: 'RATE_LIMITED',
+            message: retryAfter
+                ? `Too many requests. Retry after ${retryAfter} seconds.`
+                : 'Too many requests',
+            retryAfter,
+        });
+    }
+    // Common success patterns
+    created(data, location) {
+        this.statusCode = 201;
+        if (location) {
+            this.setHeader('Location', location);
+        }
+        this.json({
+            success: true,
+            data,
+        });
+    }
+    noContent() {
+        this.statusCode = 204;
+        this.end();
+    }
+    paginated(data, pagination) {
+        const totalPages = Math.ceil(pagination.total / pagination.limit);
+        this.json({
+            success: true,
+            data,
+            pagination: {
+                page: pagination.page,
+                limit: pagination.limit,
+                total: pagination.total,
+                totalPages,
+                hasNext: pagination.page < totalPages,
+                hasPrev: pagination.page > 1,
+            },
+        });
+    }
+    // Header management utilities
+    hasHeader(name) {
+        return this.getHeader(name) !== undefined;
+    }
+    setBulkHeaders(headers) {
+        if (this.headersSent) {
+            // Only enumerate keys for warning if headers were already sent
+            const attemptedHeaderKeys = [];
+            for (const key in headers) {
+                attemptedHeaderKeys.push(key);
+            }
+            this._server?.logger.warn('Cannot set headers - headers already sent', 'HeaderWarning', {
+                attemptedHeaders: attemptedHeaderKeys,
+            });
+            return this;
+        }
+        for (const key in headers) {
+            this.setHeader(key, headers[key]);
+        }
+        return this;
+    }
+    appendHeader(name, value) {
+        if (this.headersSent) {
+            this._server?.logger.warn(`Cannot append to header '${name}' - headers already sent`, 'HeaderWarning');
+            return this;
+        }
+        const existing = this.getHeader(name);
+        if (existing) {
+            const values = Array.isArray(existing) ? existing : [existing.toString()];
+            const newValues = Array.isArray(value) ? value : [value];
+            this.setHeader(name, [...values, ...newValues]);
+        }
+        else {
+            this.setHeader(name, value);
+        }
+        return this;
+    }
+    // Express-compatible response helpers
+    set(field, value) {
+        if (this.headersSent)
+            return this;
+        if (typeof field === 'string') {
+            if (value !== undefined) {
+                this.setHeader(field, value);
+            }
+        }
+        else {
+            for (const key in field) {
+                this.setHeader(key, field[key]);
+            }
+        }
+        return this;
+    }
+    get(field) {
+        return this.getHeader(field);
+    }
+    append(field, value) {
+        return this.appendHeader(field, value);
+    }
+    type(contentType) {
+        if (this.headersSent)
+            return this;
+        // If no "/" treat as shorthand (e.g. "json" → "application/json")
+        let ct = contentType;
+        if (ct.indexOf('/') === -1) {
+            ct = TYPE_SHORTHANDS[ct.toLowerCase()] || `application/${ct}`;
+        }
+        this.setHeader('Content-Type', ct);
+        return this;
+    }
+    sendStatus(code) {
+        if (this.headersSent)
+            return;
+        this.statusCode = code;
+        const body = STATUS_MESSAGES[code] || String(code);
+        this.setHeader('Content-Type', 'text/plain; charset=utf-8');
+        this.end(body);
+    }
+    location(url) {
+        if (this.headersSent)
+            return this;
+        const safe = url.replace(/[\r\n]/g, '');
+        this.setHeader('Location', safe);
+        return this;
+    }
+    vary(field) {
+        if (this.headersSent)
+            return this;
+        const existing = this.getHeader('Vary');
+        const existingList = existing
+            ? String(existing)
+                .split(',')
+                .map(s => s.trim())
+                .filter(Boolean)
+            : [];
+        const incoming = Array.isArray(field) ? field : [field];
+        for (const f of incoming) {
+            if (!existingList.some(e => e.toLowerCase() === f.toLowerCase())) {
+                existingList.push(f);
+            }
+        }
+        this.setHeader('Vary', existingList.join(', '));
+        return this;
+    }
+    attachment(filename) {
+        if (this.headersSent)
+            return this;
+        if (filename) {
+            const safeName = filename.replace(/[\r\n"]/g, '');
+            this.setHeader('Content-Disposition', `attachment; filename="${safeName}"`);
+            // Set Content-Type from extension if not already set
+            if (!this.getHeader('Content-Type')) {
+                // fire-and-forget mime lookup; not awaited to keep signature chainable
+                this._server.getMimeType(filename.substring(filename.lastIndexOf('.'))).then(mime => {
+                    if (!this.getHeader('Content-Type') && !this.headersSent) {
+                        this.setHeader('Content-Type', mime);
+                    }
+                });
+            }
+        }
+        else {
+            this.setHeader('Content-Disposition', 'attachment');
+        }
+        return this;
+    }
+    async download(filePath, filename) {
+        this.attachment(filename || filePath.split('/').pop());
+        return this.sendFile(filePath);
+    }
+    format(handlers) {
+        const types = Object.keys(handlers).filter(k => k !== 'default');
+        const matched = this.req.accepts(types);
+        const chosen = matched ? handlers[matched] : handlers.default;
+        if (!chosen) {
+            this.statusCode = 406;
+            this.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            this.end('Not Acceptable');
+            return;
+        }
+        this.vary('Accept');
+        if (matched && typeof matched === 'string') {
+            this.type(matched);
+        }
+        chosen();
+    }
+    links(links) {
+        if (this.headersSent)
+            return this;
+        const parts = [];
+        for (const rel in links) {
+            parts.push(`<${links[rel]}>; rel="${rel}"`);
+        }
+        if (parts.length > 0) {
+            const existing = this.getHeader('Link');
+            const combined = existing ? `${existing}, ${parts.join(', ')}` : parts.join(', ');
+            this.setHeader('Link', combined);
+        }
+        return this;
+    }
+    // Response state utilities
+    canSetHeaders() {
+        return !this.headersSent;
+    }
+    getResponseState() {
+        return {
+            headersSent: this.headersSent,
+            statusCode: this.statusCode,
+            headers: this.getHeaders ? this.getHeaders() : {},
+            finished: this.finished || false,
+            writable: this.writable,
+        };
+    }
+}
 export class MoroHttpServer {
     server;
     routes = [];
     globalMiddleware = [];
+    /** @internal read by MoroServerResponse prototype methods */
     compressionEnabled = true;
+    /** @internal read by MoroServerResponse prototype methods */
     compressionThreshold = 1024;
+    /** @internal read by MoroIncomingMessage prototype methods */
     requestTrackingEnabled = true; // Generate request IDs
+    /** @internal read by MoroServerResponse prototype methods */
     logger = createFrameworkLogger('HttpServer');
     hookManager;
     requestCounter = 0;
     errorHandler;
     requestDecorations = {};
     responseDecorations = {};
+    // Per-server request/response subclasses; their prototype carries the
+    // `_server` back-reference plus user decorations (applied once, not per request)
+    RequestClass;
+    ResponseClass;
+    // Direct router dispatch slot - runs after global middleware without the
+    // per-middleware promise machinery (set from Moro.listen via setRouterHandler)
+    routerHandler;
     // Body size limits - defaults overridden by config in constructor
     maxBodySize = 10 * 1024 * 1024; // Default 10MB (overridden by server.bodySizeLimit config)
     maxUploadSize = 100 * 1024 * 1024; // Default 100MB for file uploads (future: configurable)
@@ -43,7 +907,19 @@ export class MoroHttpServer {
         rateLimited: Buffer.from('{"success":false,"error":"Rate limit exceeded"}'),
     };
     constructor(options) {
-        this.server = createServer(this.handleRequest.bind(this));
+        // Per-instance subclasses so prototype methods can reach this server's
+        // config (logger, compression) with zero per-request allocation.
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const boundServer = this;
+        class BoundRequest extends MoroIncomingMessage {
+        }
+        class BoundResponse extends MoroServerResponse {
+        }
+        BoundRequest.prototype._server = boundServer;
+        BoundResponse.prototype._server = boundServer;
+        this.RequestClass = BoundRequest;
+        this.ResponseClass = BoundResponse;
+        this.server = createServer({ IncomingMessage: BoundRequest, ServerResponse: BoundResponse }, this.handleRequest.bind(this));
         // Configure body size limits from options
         if (options?.maxBodySize) {
             this.maxBodySize = options.maxBodySize;
@@ -56,6 +932,11 @@ export class MoroHttpServer {
         this.server.headersTimeout = 6000; // 6 seconds
         this.server.timeout = 30000; // 30 seconds request timeout
     }
+    // Direct router dispatch - called after global middleware, before the legacy
+    // route table. Returning true (or a promise of true) means the request was handled.
+    setRouterHandler(fn) {
+        this.routerHandler = fn;
+    }
     // Configure server for maximum performance (can disable all overhead)
     configurePerformance(config = {}) {
         if (config.compression !== undefined) {
@@ -78,12 +959,30 @@ export class MoroHttpServer {
     setErrorHandler(fn) {
         this.errorHandler = fn;
     }
-    // Apply per-request/response decoration maps (called from Moro.decorateRequest/Reply)
+    // Apply request/response decoration maps (called from Moro.decorateRequest/Reply).
+    // Decorations are installed on the per-server prototypes once, so requests pay
+    // nothing for them; per-request writes to the same key simply shadow the prototype.
     setRequestDecorations(decorations) {
         this.requestDecorations = decorations;
+        for (const key in decorations) {
+            Object.defineProperty(this.RequestClass.prototype, key, {
+                value: decorations[key],
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
     }
     setResponseDecorations(decorations) {
         this.responseDecorations = decorations;
+        for (const key in decorations) {
+            Object.defineProperty(this.ResponseClass.prototype, key, {
+                value: decorations[key],
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+        }
     }
     // Middleware management
     use(middleware) {
@@ -158,48 +1057,90 @@ export class MoroHttpServer {
         };
     }
     async handleRequest(req, res) {
-        const httpReq = this.enhanceRequest(req);
-        const httpRes = this.enhanceResponse(res, httpReq);
-        // Store original params for efficient cleanup
-        const originalParams = httpReq.params;
+        // req/res arrive as the per-server subclasses (MoroIncomingMessage /
+        // MoroServerResponse) - all helpers are already on their prototypes.
+        const httpReq = req;
+        const httpRes = res;
         try {
-            // Optimized URL and query parsing with object pooling
+            // URL split - query string parsing is lazy (MoroIncomingMessage#query getter)
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             const urlString = req.url;
             const queryIndex = urlString.indexOf('?');
             if (queryIndex === -1) {
-                // No query string
                 httpReq.path = urlString;
-                httpReq.query = {};
             }
             else {
-                // Has query string - parse efficiently with pooled object
                 httpReq.path = urlString.substring(0, queryIndex);
-                httpReq.query = this.parseQueryStringPooled(urlString.substring(queryIndex + 1));
+                httpReq._queryString = urlString.substring(queryIndex + 1);
             }
-            // Method checking - use reference equality for interned strings (50-100% faster)
+            // Intern method string for fast reference equality comparison (50-100% faster)
+            switch (req.method) {
+                case 'POST':
+                    httpReq.method = MoroHttpServer.METHOD_POST;
+                    break;
+                case 'PUT':
+                    httpReq.method = MoroHttpServer.METHOD_PUT;
+                    break;
+                case 'PATCH':
+                    httpReq.method = MoroHttpServer.METHOD_PATCH;
+                    break;
+                case 'GET':
+                    httpReq.method = MoroHttpServer.METHOD_GET;
+                    break;
+                case 'DELETE':
+                    httpReq.method = MoroHttpServer.METHOD_DELETE;
+                    break;
+                case 'HEAD':
+                    httpReq.method = MoroHttpServer.METHOD_HEAD;
+                    break;
+                case 'OPTIONS':
+                    httpReq.method = MoroHttpServer.METHOD_OPTIONS;
+                    break;
+            }
+            // Method checking - use reference equality for interned strings
             if (httpReq.method === MoroHttpServer.METHOD_POST ||
                 httpReq.method === MoroHttpServer.METHOD_PUT ||
                 httpReq.method === MoroHttpServer.METHOD_PATCH) {
                 httpReq.body = await this.parseBody(req);
             }
-            // Execute hooks before request processing - NOOP if no hookManager
-            if (this.hookManager) {
-                await this.hookManager.execute('request', {
+            // Execute hooks before request processing - skipped entirely (no context
+            // object, no promise) when no 'request' hooks are registered
+            const hookManager = this.hookManager;
+            if (hookManager && (hookManager.hasHooks === undefined || hookManager.hasHooks('request'))) {
+                await hookManager.execute('request', {
                     request: httpReq,
                     response: httpRes,
                 });
             }
-            // Execute global middleware first - EARLY EXIT if none registered
-            const middlewareLen = this.globalMiddleware.length;
-            if (middlewareLen > 0) {
-                await this.executeMiddleware(this.globalMiddleware, httpReq, httpRes);
+            // Execute global middleware first - EARLY EXIT if none registered.
+            // executeMiddleware returns undefined when the whole chain completed
+            // synchronously, so a sync chain costs zero promise allocations.
+            if (this.globalMiddleware.length > 0) {
+                const mwResult = this.executeMiddleware(this.globalMiddleware, httpReq, httpRes);
+                if (mwResult)
+                    await mwResult;
             }
             // If middleware handled the request, don't continue
             if (httpRes.headersSent) {
                 return;
             }
-            // Find matching route
+            // Unified router direct dispatch - no middleware-chain promise wrapper
+            const routerHandler = this.routerHandler;
+            if (routerHandler) {
+                const handled = routerHandler(httpReq, httpRes);
+                if (handled) {
+                    if (typeof handled.then === 'function') {
+                        if (await handled)
+                            return;
+                    }
+                    else {
+                        return;
+                    }
+                }
+                if (httpRes.headersSent)
+                    return;
+            }
+            // Find matching route (legacy direct-route table)
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             const route = this.findRoute(req.method, httpReq.path);
             if (!route) {
@@ -210,21 +1151,22 @@ export class MoroHttpServer {
                 httpRes.end(MoroHttpServer.RESPONSE_TEMPLATES.notFound);
                 return;
             }
-            // Extract path parameters - optimized with object pooling
+            // Extract path parameters
             const matches = httpReq.path.match(route.pattern);
             if (matches) {
-                // Use pooled object for parameters
-                httpReq.params = this.acquireParamObject();
+                const params = {};
                 const paramNames = route.paramNames;
                 const paramNamesLen = paramNames.length;
                 for (let i = 0; i < paramNamesLen; i++) {
-                    httpReq.params[paramNames[i]] = matches[i + 1];
+                    params[paramNames[i]] = matches[i + 1];
                 }
+                httpReq.params = params;
             }
             // Execute middleware chain - EARLY EXIT if no route middleware
-            const routeMiddlewareLen = route.middleware.length;
-            if (routeMiddlewareLen > 0) {
-                await this.executeMiddleware(route.middleware, httpReq, httpRes);
+            if (route.middleware.length > 0) {
+                const mwResult = this.executeMiddleware(route.middleware, httpReq, httpRes);
+                if (mwResult)
+                    await mwResult;
             }
             // Execute handler - Don't await sync handlers
             const handlerResult = route.handler(httpReq, httpRes);
@@ -241,6 +1183,16 @@ export class MoroHttpServer {
                 requestPath: req.url,
                 requestMethod: req.method,
             });
+            // Payload-too-large from parseBody: respond 413 (matches the old bodySize
+            // middleware semantics, now enforced in-server)
+            if (error?.statusCode === 413 && !httpRes.headersSent) {
+                httpRes.statusCode = 413;
+                httpRes.json({
+                    success: false,
+                    error: 'Request entity too large',
+                });
+                return;
+            }
             this.logger.error('Request error', 'RequestHandler', {
                 error: error instanceof Error ? error.message : String(error),
                 requestId: httpReq.requestId,
@@ -298,66 +1250,6 @@ export class MoroHttpServer {
                 }
             }
         }
-        finally {
-            // Always release pooled objects back to the pool
-            // This prevents memory leaks and ensures consistent performance
-            // Check if object is empty without Object.keys()
-            if (originalParams) {
-                let isEmpty = true;
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                for (const _key in originalParams) {
-                    isEmpty = false;
-                    break;
-                }
-                if (isEmpty) {
-                    this.releaseParamObject(originalParams);
-                }
-            }
-            if (httpReq.params && httpReq.params !== originalParams) {
-                let isEmpty = true;
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                for (const _key in httpReq.params) {
-                    isEmpty = false;
-                    break;
-                }
-                if (isEmpty) {
-                    this.releaseParamObject(httpReq.params);
-                }
-            }
-        }
-        // Additional cleanup on response completion to ensure objects are returned to pool
-        res.once('finish', () => {
-            // Check if object is empty without Object.keys()
-            if (originalParams) {
-                let isEmpty = true;
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                for (const _key in originalParams) {
-                    isEmpty = false;
-                    break;
-                }
-                if (isEmpty) {
-                    this.releaseParamObject(originalParams);
-                }
-            }
-            if (httpReq.params && httpReq.params !== originalParams) {
-                let isEmpty = true;
-                // eslint-disable-next-line @typescript-eslint/no-unused-vars
-                for (const _key in httpReq.params) {
-                    isEmpty = false;
-                    break;
-                }
-                if (isEmpty) {
-                    this.releaseParamObject(httpReq.params);
-                }
-            }
-        });
-    }
-    // Use shared object pool for parameter objects
-    acquireParamObject() {
-        return this.poolManager.acquireParams();
-    }
-    releaseParamObject(params) {
-        this.poolManager.releaseParams(params);
     }
     // Force cleanup of all pooled objects
     forceCleanupPools() {
@@ -429,697 +1321,7 @@ export class MoroHttpServer {
         }
         return normalized;
     }
-    enhanceRequest(req) {
-        const httpReq = req;
-        httpReq.params = this.acquireParamObject();
-        httpReq.query = {};
-        httpReq.body = null;
-        httpReq.path = '';
-        httpReq.ip = req.socket.remoteAddress || '';
-        // Request ID generation using pool manager (if enabled)
-        httpReq.requestId = this.requestTrackingEnabled ? this.poolManager.generateRequestId() : '';
-        httpReq.headers = req.headers;
-        // Intern method string for fast reference equality comparison (50-100% faster)
-        const method = req.method;
-        switch (method) {
-            case 'POST':
-                httpReq.method = MoroHttpServer.METHOD_POST;
-                break;
-            case 'PUT':
-                httpReq.method = MoroHttpServer.METHOD_PUT;
-                break;
-            case 'PATCH':
-                httpReq.method = MoroHttpServer.METHOD_PATCH;
-                break;
-            case 'GET':
-                httpReq.method = MoroHttpServer.METHOD_GET;
-                break;
-            case 'DELETE':
-                httpReq.method = MoroHttpServer.METHOD_DELETE;
-                break;
-            case 'HEAD':
-                httpReq.method = MoroHttpServer.METHOD_HEAD;
-                break;
-            case 'OPTIONS':
-                httpReq.method = MoroHttpServer.METHOD_OPTIONS;
-                break;
-            default:
-                httpReq.method = method;
-        }
-        // Parse cookies - EARLY EXIT if no cookie header
-        const cookieHeader = req.headers.cookie;
-        if (cookieHeader) {
-            httpReq.cookies = this.parseCookies(cookieHeader);
-        }
-        else {
-            httpReq.cookies = {};
-        }
-        // Per-request typed context bag
-        httpReq.context = {};
-        // Apply user-registered request decorations
-        for (const key in this.requestDecorations) {
-            httpReq[key] = this.requestDecorations[key];
-        }
-        // Express-compatible request helpers
-        httpReq.get = httpReq.header = (name) => {
-            const lower = name.toLowerCase();
-            if (lower === 'referer' || lower === 'referrer') {
-                return (httpReq.headers.referer || httpReq.headers.referrer);
-            }
-            const v = httpReq.headers[lower];
-            return Array.isArray(v) ? v[0] : v;
-        };
-        httpReq.is = (type) => {
-            const ct = (httpReq.headers['content-type'] || '');
-            if (!ct)
-                return false;
-            const mime = ct.split(';')[0].trim().toLowerCase();
-            const t = type.toLowerCase();
-            if (t.indexOf('/') === -1) {
-                // e.g. 'json' → match */json or +json suffix
-                return mime.endsWith(`/${t}`) || mime.endsWith(`+${t}`);
-            }
-            if (t.endsWith('/*')) {
-                return mime.startsWith(t.slice(0, -1));
-            }
-            return mime === t;
-        };
-        httpReq.accepts = (types) => {
-            const accept = (httpReq.headers.accept || '*/*');
-            if (!types)
-                return accept;
-            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());
-            for (const w of wanted) {
-                const wl = w.toLowerCase();
-                const wMime = wl.indexOf('/') === -1 ? `application/${wl}` : wl;
-                for (const at of acceptTypes) {
-                    if (at === '*/*')
-                        return w;
-                    if (at === wMime)
-                        return w;
-                    if (at.endsWith('/*') && wMime.startsWith(at.slice(0, -1)))
-                        return w;
-                }
-            }
-            return false;
-        };
-        httpReq.acceptsLanguages = (langs) => {
-            const acceptLang = (httpReq.headers['accept-language'] || '');
-            if (!langs)
-                return acceptLang || false;
-            const wanted = Array.isArray(langs) ? langs : [langs];
-            if (!acceptLang)
-                return wanted[0] || false;
-            // Parse with q values; sort by q desc to match Express's "best match wins"
-            const accepted = acceptLang
-                .split(',')
-                .map(s => {
-                const parts = s.trim().split(';');
-                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 };
-            })
-                .filter(a => a.q > 0)
-                .sort((a, b) => b.q - a.q);
-            for (const { tag } of accepted) {
-                for (const w of wanted) {
-                    const wl = w.toLowerCase();
-                    if (tag === '*' || tag === wl || tag.split('-')[0] === wl.split('-')[0])
-                        return w;
-                }
-            }
-            return false;
-        };
-        const host = (httpReq.headers.host || '');
-        httpReq.hostname = host ? host.split(':')[0] : '';
-        const forwardedProto = httpReq.headers['x-forwarded-proto'];
-        httpReq.protocol = forwardedProto
-            ? forwardedProto.split(',')[0].trim()
-            : req.socket.encrypted
-                ? 'https'
-                : 'http';
-        httpReq.secure = httpReq.protocol === 'https';
-        const xrw = httpReq.headers['x-requested-with'];
-        httpReq.xhr = !!xrw && xrw.toLowerCase() === 'xmlhttprequest';
-        httpReq.originalUrl = req.url || '';
-        const forwardedFor = httpReq.headers['x-forwarded-for'];
-        httpReq.ips = forwardedFor
-            ? forwardedFor
-                .split(',')
-                .map(s => s.trim())
-                .filter(Boolean)
-            : [];
-        const hostnameParts = httpReq.hostname.split('.');
-        // Matches Express: subdomains are parts before the last two (domain + tld),
-        // reversed (closest subdomain first).
-        httpReq.subdomains = hostnameParts.length > 2 ? hostnameParts.slice(0, -2).reverse() : [];
-        return httpReq;
-    }
-    parseCookies(cookieHeader) {
-        const cookies = {};
-        // EARLY EXIT if no cookie header
-        if (!cookieHeader)
-            return cookies;
-        const cookieParts = cookieHeader.split(';');
-        const cookiePartsLen = cookieParts.length;
-        for (let i = 0; i < cookiePartsLen; i++) {
-            const cookie = cookieParts[i];
-            const equalIndex = cookie.indexOf('=');
-            if (equalIndex > 0) {
-                const name = cookie.substring(0, equalIndex).trim();
-                const value = cookie.substring(equalIndex + 1);
-                if (name && value) {
-                    cookies[name] = decodeURIComponent(value);
-                }
-            }
-        }
-        return cookies;
-    }
-    enhanceResponse(res, req) {
-        const httpRes = res;
-        // Store request reference for access to headers (needed for compression, logging, etc.)
-        httpRes.req = req;
-        // BULLETPROOF status method - always works
-        httpRes.status = (code) => {
-            httpRes.statusCode = code;
-            return httpRes;
-        };
-        httpRes.json = async (data) => {
-            if (httpRes.headersSent)
-                return;
-            // Simple, optimized JSON serialization - let V8 handle the optimization
-            const jsonString = JSON.stringify(data);
-            // Large response check - stream if needed
-            if (jsonString.length > 32768) {
-                // Large response - stream it
-                return this.streamLargeResponse(httpRes, data);
-            }
-            // Use efficient buffer allocation - let Node.js handle optimization
-            const finalBuffer = Buffer.from(jsonString, 'utf8');
-            // Optimized header setting - set multiple headers at once when possible
-            const headers = {
-                'Content-Type': 'application/json; charset=utf-8',
-            };
-            // Compression with buffer pool - EARLY EXIT if disabled or below threshold
-            // Only make this async if compression is actually happening
-            if (this.compressionEnabled && finalBuffer.length > this.compressionThreshold) {
-                const acceptEncoding = httpRes.req.headers['accept-encoding'];
-                if (acceptEncoding && acceptEncoding.includes('gzip')) {
-                    // ASYNC PATH - compression needed
-                    gzip(finalBuffer).then(compressed => {
-                        headers['Content-Encoding'] = 'gzip';
-                        headers['Content-Length'] = compressed.length;
-                        // Batch write all headers at once (50-100% faster)
-                        httpRes.writeHead(httpRes.statusCode || 200, headers);
-                        httpRes.end(compressed);
-                    });
-                    return;
-                }
-                else if (acceptEncoding && acceptEncoding.includes('deflate')) {
-                    // ASYNC PATH - compression needed
-                    deflate(finalBuffer).then(compressed => {
-                        headers['Content-Encoding'] = 'deflate';
-                        headers['Content-Length'] = compressed.length;
-                        // Batch write all headers at once
-                        httpRes.writeHead(httpRes.statusCode || 200, headers);
-                        httpRes.end(compressed);
-                    });
-                    return;
-                }
-            }
-            // SYNC PATH - no compression, fast path
-            headers['Content-Length'] = finalBuffer.length;
-            // Batch write all headers at once
-            httpRes.writeHead(httpRes.statusCode || 200, headers);
-            httpRes.end(finalBuffer);
-        };
-        httpRes.send = (data) => {
-            if (httpRes.headersSent)
-                return;
-            // Auto-detect content type if not already set
-            if (!httpRes.getHeader('Content-Type')) {
-                if (typeof data === 'string') {
-                    // Check if it's JSON
-                    try {
-                        JSON.parse(data);
-                        httpRes.setHeader('Content-Type', 'application/json; charset=utf-8');
-                    }
-                    catch {
-                        // Default to plain text
-                        httpRes.setHeader('Content-Type', 'text/plain; charset=utf-8');
-                    }
-                }
-                else {
-                    // Buffer data - default to octet-stream
-                    httpRes.setHeader('Content-Type', 'application/octet-stream');
-                }
-            }
-            httpRes.end(data);
-        };
-        httpRes.cookie = (name, value, options = {}) => {
-            if (httpRes.headersSent) {
-                const isCritical = options.critical ||
-                    name.includes('session') ||
-                    name.includes('auth') ||
-                    name.includes('csrf');
-                const message = `Cookie '${name}' could not be set - headers already sent`;
-                if (isCritical || options.throwOnLateSet) {
-                    throw new Error(`${message}. This may cause authentication or security issues.`);
-                }
-                else {
-                    this.logger.warn(message, 'CookieWarning', {
-                        cookieName: name,
-                        critical: isCritical,
-                        stackTrace: new Error().stack,
-                    });
-                }
-                return httpRes;
-            }
-            const cookieValue = encodeURIComponent(value);
-            let cookieString = `${name}=${cookieValue}`;
-            if (options.maxAge)
-                cookieString += `; Max-Age=${options.maxAge}`;
-            if (options.expires)
-                cookieString += `; Expires=${options.expires.toUTCString()}`;
-            if (options.httpOnly)
-                cookieString += '; HttpOnly';
-            if (options.secure)
-                cookieString += '; Secure';
-            if (options.sameSite)
-                cookieString += `; SameSite=${options.sameSite}`;
-            if (options.domain)
-                cookieString += `; Domain=${options.domain}`;
-            if (options.path)
-                cookieString += `; Path=${options.path}`;
-            const existingCookies = httpRes.getHeader('Set-Cookie') || [];
-            // Avoid spread operator - direct array manipulation
-            const cookies = Array.isArray(existingCookies)
-                ? existingCookies
-                : [existingCookies];
-            cookies.push(cookieString);
-            httpRes.setHeader('Set-Cookie', cookies);
-            return httpRes;
-        };
-        httpRes.clearCookie = (name, options = {}) => {
-            // Avoid spread operator - manually set properties
-            const clearOptions = {
-                expires: new Date(0),
-                maxAge: 0,
-            };
-            // Copy other options manually
-            if (options.path !== undefined)
-                clearOptions.path = options.path;
-            if (options.domain !== undefined)
-                clearOptions.domain = options.domain;
-            if (options.httpOnly !== undefined)
-                clearOptions.httpOnly = options.httpOnly;
-            if (options.secure !== undefined)
-                clearOptions.secure = options.secure;
-            if (options.sameSite !== undefined)
-                clearOptions.sameSite = options.sameSite;
-            return httpRes.cookie(name, '', clearOptions);
-        };
-        httpRes.redirect = (url, status = 302) => {
-            if (httpRes.headersSent)
-                return;
-            httpRes.statusCode = status;
-            const safeUrl = url.replace(/[\r\n]/g, '');
-            httpRes.setHeader('Location', safeUrl);
-            httpRes.end();
-        };
-        httpRes.sendFile = async (filePath) => {
-            if (httpRes.headersSent)
-                return;
-            try {
-                const fs = await import('fs/promises');
-                const path = await import('path');
-                const extension = path.extname(filePath);
-                const mime = await this.getMimeType(extension);
-                const stats = await fs.stat(filePath);
-                const data = await fs.readFile(filePath);
-                // Add charset for text-based files
-                const contentType = this.addCharsetIfNeeded(mime);
-                httpRes.setHeader('Content-Type', contentType);
-                httpRes.setHeader('Content-Length', stats.size);
-                // Add security headers for file downloads
-                httpRes.setHeader('X-Content-Type-Options', 'nosniff');
-                // Add caching headers
-                httpRes.setHeader('Last-Modified', stats.mtime.toUTCString());
-                httpRes.setHeader('Cache-Control', 'public, max-age=31536000'); // 1 year for static files
-                httpRes.end(data);
-            }
-            catch {
-                httpRes.status(404).json({ success: false, error: 'File not found' });
-            }
-        };
-        // Standardized response helpers
-        httpRes.success = (data, message) => {
-            const response = {
-                success: true,
-                data,
-            };
-            if (message !== undefined) {
-                response.message = message;
-            }
-            httpRes.json(response);
-        };
-        httpRes.error = (error, code, message) => {
-            const response = {
-                success: false,
-                error,
-            };
-            if (code !== undefined) {
-                response.code = code;
-            }
-            if (message !== undefined) {
-                response.message = message;
-            }
-            httpRes.json(response);
-        };
-        // Common HTTP error helpers (automatically set status code)
-        httpRes.unauthorized = (message = 'Authentication required') => {
-            httpRes.statusCode = 401;
-            httpRes.json({
-                success: false,
-                error: 'Unauthorized',
-                code: 'UNAUTHORIZED',
-                message,
-            });
-        };
-        httpRes.forbidden = (message = 'Insufficient permissions') => {
-            httpRes.statusCode = 403;
-            httpRes.json({
-                success: false,
-                error: 'Forbidden',
-                code: 'FORBIDDEN',
-                message,
-            });
-        };
-        httpRes.notFound = (resource = 'Resource') => {
-            httpRes.statusCode = 404;
-            httpRes.json({
-                success: false,
-                error: 'Not Found',
-                code: 'NOT_FOUND',
-                message: `${resource} not found`,
-            });
-        };
-        httpRes.badRequest = (message = 'Invalid request') => {
-            httpRes.statusCode = 400;
-            httpRes.json({
-                success: false,
-                error: 'Bad Request',
-                code: 'BAD_REQUEST',
-                message,
-            });
-        };
-        httpRes.conflict = (message) => {
-            httpRes.statusCode = 409;
-            httpRes.json({
-                success: false,
-                error: 'Conflict',
-                code: 'CONFLICT',
-                message,
-            });
-        };
-        httpRes.internalError = (message = 'Internal server error') => {
-            httpRes.statusCode = 500;
-            httpRes.json({
-                success: false,
-                error: 'Internal Server Error',
-                code: 'INTERNAL_ERROR',
-                message,
-            });
-        };
-        httpRes.validationError = (errors) => {
-            httpRes.statusCode = 422;
-            httpRes.json({
-                success: false,
-                error: 'Validation Failed',
-                code: 'VALIDATION_ERROR',
-                errors,
-            });
-        };
-        httpRes.rateLimited = (retryAfter) => {
-            httpRes.statusCode = 429;
-            if (retryAfter) {
-                httpRes.setHeader('Retry-After', retryAfter.toString());
-            }
-            httpRes.json({
-                success: false,
-                error: 'Rate Limit Exceeded',
-                code: 'RATE_LIMITED',
-                message: retryAfter
-                    ? `Too many requests. Retry after ${retryAfter} seconds.`
-                    : 'Too many requests',
-                retryAfter,
-            });
-        };
-        // Common success patterns
-        httpRes.created = (data, location) => {
-            httpRes.statusCode = 201;
-            if (location) {
-                httpRes.setHeader('Location', location);
-            }
-            httpRes.json({
-                success: true,
-                data,
-            });
-        };
-        httpRes.noContent = () => {
-            httpRes.statusCode = 204;
-            httpRes.end();
-        };
-        httpRes.paginated = (data, pagination) => {
-            const totalPages = Math.ceil(pagination.total / pagination.limit);
-            httpRes.json({
-                success: true,
-                data,
-                pagination: {
-                    page: pagination.page,
-                    limit: pagination.limit,
-                    total: pagination.total,
-                    totalPages,
-                    hasNext: pagination.page < totalPages,
-                    hasPrev: pagination.page > 1,
-                },
-            });
-        };
-        // Header management utilities
-        httpRes.hasHeader = (name) => {
-            return httpRes.getHeader(name) !== undefined;
-        };
-        // Note: removeHeader is inherited from ServerResponse, we don't override it
-        httpRes.setBulkHeaders = (headers) => {
-            if (httpRes.headersSent) {
-                // Only enumerate keys for warning if headers were already sent
-                const attemptedHeaderKeys = [];
-                for (const key in headers) {
-                    attemptedHeaderKeys.push(key);
-                }
-                this.logger.warn('Cannot set headers - headers already sent', 'HeaderWarning', {
-                    attemptedHeaders: attemptedHeaderKeys,
-                });
-                return httpRes;
-            }
-            for (const key in headers) {
-                httpRes.setHeader(key, headers[key]);
-            }
-            return httpRes;
-        };
-        httpRes.appendHeader = (name, value) => {
-            if (httpRes.headersSent) {
-                this.logger.warn(`Cannot append to header '${name}' - headers already sent`, 'HeaderWarning');
-                return httpRes;
-            }
-            const existing = httpRes.getHeader(name);
-            if (existing) {
-                const values = Array.isArray(existing) ? existing : [existing.toString()];
-                const newValues = Array.isArray(value) ? value : [value];
-                httpRes.setHeader(name, [...values, ...newValues]);
-            }
-            else {
-                httpRes.setHeader(name, value);
-            }
-            return httpRes;
-        };
-        // Per-response typed state bag (Express-compatible)
-        httpRes.locals = {};
-        // Apply user-registered response decorations
-        for (const key in this.responseDecorations) {
-            httpRes[key] = this.responseDecorations[key];
-        }
-        // Express-compatible response helpers
-        httpRes.set = (field, value) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            if (typeof field === 'string') {
-                if (value !== undefined) {
-                    httpRes.setHeader(field, value);
-                }
-            }
-            else {
-                for (const key in field) {
-                    httpRes.setHeader(key, field[key]);
-                }
-            }
-            return httpRes;
-        };
-        httpRes.get = (field) => {
-            return httpRes.getHeader(field);
-        };
-        httpRes.append = (field, value) => {
-            return httpRes.appendHeader(field, value);
-        };
-        httpRes.type = (contentType) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            // If no "/" treat as shorthand (e.g. "json" → "application/json")
-            let ct = contentType;
-            if (ct.indexOf('/') === -1) {
-                const shorthands = {
-                    json: 'application/json; charset=utf-8',
-                    html: 'text/html; charset=utf-8',
-                    text: 'text/plain; charset=utf-8',
-                    txt: 'text/plain; charset=utf-8',
-                    xml: 'application/xml',
-                    js: 'application/javascript',
-                    css: 'text/css; charset=utf-8',
-                    form: 'application/x-www-form-urlencoded',
-                };
-                ct = shorthands[ct.toLowerCase()] || `application/${ct}`;
-            }
-            httpRes.setHeader('Content-Type', ct);
-            return httpRes;
-        };
-        httpRes.sendStatus = (code) => {
-            if (httpRes.headersSent)
-                return;
-            httpRes.statusCode = code;
-            const messages = {
-                200: 'OK',
-                201: 'Created',
-                202: 'Accepted',
-                204: 'No Content',
-                301: 'Moved Permanently',
-                302: 'Found',
-                304: 'Not Modified',
-                400: 'Bad Request',
-                401: 'Unauthorized',
-                403: 'Forbidden',
-                404: 'Not Found',
-                409: 'Conflict',
-                410: 'Gone',
-                422: 'Unprocessable Entity',
-                429: 'Too Many Requests',
-                500: 'Internal Server Error',
-                502: 'Bad Gateway',
-                503: 'Service Unavailable',
-            };
-            const body = messages[code] || String(code);
-            httpRes.setHeader('Content-Type', 'text/plain; charset=utf-8');
-            httpRes.end(body);
-        };
-        httpRes.location = (url) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            const safe = url.replace(/[\r\n]/g, '');
-            httpRes.setHeader('Location', safe);
-            return httpRes;
-        };
-        httpRes.vary = (field) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            const existing = httpRes.getHeader('Vary');
-            const existingList = existing
-                ? String(existing)
-                    .split(',')
-                    .map(s => s.trim())
-                    .filter(Boolean)
-                : [];
-            const incoming = Array.isArray(field) ? field : [field];
-            for (const f of incoming) {
-                if (!existingList.some(e => e.toLowerCase() === f.toLowerCase())) {
-                    existingList.push(f);
-                }
-            }
-            httpRes.setHeader('Vary', existingList.join(', '));
-            return httpRes;
-        };
-        httpRes.attachment = (filename) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            if (filename) {
-                const safeName = filename.replace(/[\r\n"]/g, '');
-                httpRes.setHeader('Content-Disposition', `attachment; filename="${safeName}"`);
-                // Set Content-Type from extension if not already set
-                if (!httpRes.getHeader('Content-Type')) {
-                    // fire-and-forget mime lookup; not awaited to keep signature chainable
-                    this.getMimeType(filename.substring(filename.lastIndexOf('.'))).then(mime => {
-                        if (!httpRes.getHeader('Content-Type') && !httpRes.headersSent) {
-                            httpRes.setHeader('Content-Type', mime);
-                        }
-                    });
-                }
-            }
-            else {
-                httpRes.setHeader('Content-Disposition', 'attachment');
-            }
-            return httpRes;
-        };
-        httpRes.download = async (filePath, filename) => {
-            httpRes.attachment(filename || filePath.split('/').pop());
-            return httpRes.sendFile(filePath);
-        };
-        httpRes.format = (handlers) => {
-            const types = Object.keys(handlers).filter(k => k !== 'default');
-            const matched = req.accepts(types);
-            const chosen = matched ? handlers[matched] : handlers.default;
-            if (!chosen) {
-                httpRes.statusCode = 406;
-                httpRes.setHeader('Content-Type', 'text/plain; charset=utf-8');
-                httpRes.end('Not Acceptable');
-                return;
-            }
-            httpRes.vary('Accept');
-            if (matched && typeof matched === 'string') {
-                httpRes.type(matched);
-            }
-            chosen();
-        };
-        httpRes.links = (links) => {
-            if (httpRes.headersSent)
-                return httpRes;
-            const parts = [];
-            for (const rel in links) {
-                parts.push(`<${links[rel]}>; rel="${rel}"`);
-            }
-            if (parts.length > 0) {
-                const existing = httpRes.getHeader('Link');
-                const combined = existing ? `${existing}, ${parts.join(', ')}` : parts.join(', ');
-                httpRes.setHeader('Link', combined);
-            }
-            return httpRes;
-        };
-        // Response state utilities
-        httpRes.canSetHeaders = () => {
-            return !httpRes.headersSent;
-        };
-        httpRes.getResponseState = () => {
-            return {
-                headersSent: httpRes.headersSent,
-                statusCode: httpRes.statusCode,
-                headers: httpRes.getHeaders ? httpRes.getHeaders() : {},
-                finished: httpRes.finished || false,
-                writable: httpRes.writable,
-            };
-        };
-        return httpRes;
-    }
+    /** @internal called by MoroServerResponse prototype methods */
     async getMimeType(ext) {
         const mimeTypes = {
             '.html': 'text/html',
@@ -1138,6 +1340,7 @@ export class MoroHttpServer {
         };
         return mimeTypes[ext.toLowerCase()] || 'application/octet-stream';
     }
+    /** @internal called by MoroServerResponse prototype methods */
     addCharsetIfNeeded(mimeType) {
         // Add charset for text-based content types - optimized with early exit
         // Check most common cases first
@@ -1161,6 +1364,14 @@ export class MoroHttpServer {
         const maxSize = isMultipart
             ? this.maxUploadSize // Configurable file upload limit (default 100MB)
             : this.maxBodySize; // Configurable body size limit (default 10MB, from server.bodySizeLimit config)
+        // Early rejection from the declared Content-Length - nothing is read off the wire
+        if (contentLength > maxSize) {
+            const error = new Error('Request entity too large');
+            error.statusCode = 413;
+            error.limit = maxSize;
+            error.received = contentLength;
+            return Promise.reject(error);
+        }
         // For very large payloads, return a streaming interface instead of buffering
         if (contentLength > maxSize / 2) {
             // Stream for payloads > 50MB (uploads) or > 5MB (JSON/form)
@@ -1176,14 +1387,19 @@ export class MoroHttpServer {
                     const errorMessage = isMultipart
                         ? `File upload too large. Maximum ${Math.floor(maxSize / (1024 * 1024))}MB allowed.`
                         : 'Request body too large';
-                    reject(new Error(errorMessage));
+                    const error = new Error(errorMessage);
+                    error.statusCode = 413;
+                    error.limit = maxSize;
+                    reject(error);
                     return;
                 }
                 chunks.push(chunk);
             });
             req.on('end', () => {
                 try {
-                    const body = Buffer.concat(chunks);
+                    // Single-chunk fast path (most JSON bodies arrive in one chunk);
+                    // otherwise concat with the known total length to avoid a re-scan
+                    const body = chunks.length === 1 ? chunks[0] : Buffer.concat(chunks, totalLength);
                     if (contentType.includes('application/json')) {
                         resolve(JSON.parse(body.toString()));
                     }
@@ -1410,30 +1626,14 @@ export class MoroHttpServer {
         }
         return result;
     }
-    // Legacy method for backward compatibility
+    // Legacy methods for backward compatibility - the hot path now parses query
+    // strings lazily via the MoroIncomingMessage#query getter (no pooling: a fresh
+    // object literal is cheaper than pool bookkeeping)
     parseQueryString(queryString) {
-        return this.parseQueryStringPooled(queryString);
+        return parseQueryString(queryString);
     }
-    // Optimized query string parser with object pooling
     parseQueryStringPooled(queryString) {
-        if (!queryString)
-            return {};
-        const result = this.poolManager.acquireQuery();
-        const pairs = queryString.split('&');
-        const pairsLen = pairs.length;
-        for (let i = 0; i < pairsLen; i++) {
-            const pair = pairs[i];
-            const equalIndex = pair.indexOf('=');
-            if (equalIndex === -1) {
-                result[decodeURIComponent(pair)] = '';
-            }
-            else {
-                const key = decodeURIComponent(pair.substring(0, equalIndex));
-                const value = decodeURIComponent(pair.substring(equalIndex + 1));
-                result[key] = value;
-            }
-        }
-        return result;
+        return parseQueryString(queryString);
     }
     // Advanced route optimization: cache + static routes + segment grouping
     routeCache = new Map();
@@ -1498,13 +1698,23 @@ export class MoroHttpServer {
     // Middleware execution with Express-compatible error propagation.
     // Supports: 3-arg (req, res, next), 4-arg (err, req, res, next) error middlewares,
     // and next(err) to skip forward to the next error middleware.
-    async executeMiddleware(middleware, req, res) {
+    //
+    // Sync-aware dispatch: middleware that calls next() synchronously (or throws
+    // synchronously) advances the chain in a plain loop with ZERO promise
+    // allocations. A promise is only created when a middleware actually completes
+    // asynchronously. Returns undefined when the whole chain ran synchronously.
+    executeMiddleware(middleware, req, res) {
+        return this.dispatchMiddleware(middleware, req, res, 0, undefined);
+    }
+    dispatchMiddleware(middleware, req, res, startIndex, initialError) {
         const len = middleware.length;
-        let activeError = undefined;
-        for (let i = 0; i < len; i++) {
+        let activeError = initialError;
+        let i = startIndex;
+        while (i < len) {
             if (res.headersSent)
                 return;
             const mw = middleware[i];
+            i++;
             const isErrorHandler = mw.length >= 4;
             // Non-error middleware is skipped while an error is active; error middleware
             // is skipped while no error is active. Matches Express semantics.
@@ -1512,36 +1722,60 @@ export class MoroHttpServer {
                 continue;
             if (activeError === undefined && isErrorHandler)
                 continue;
-            activeError = await new Promise(resolve => {
-                let resolved = false;
-                const next = (err) => {
-                    if (resolved)
-                        return;
-                    resolved = true;
-                    resolve(err);
-                };
-                try {
-                    const result = isErrorHandler ? mw(activeError, req, res, next) : mw(req, res, next);
-                    if (result && typeof result.then === 'function') {
-                        result
-                            .then(() => {
-                            if (!resolved)
-                                next();
-                        })
-                            .catch((err) => {
-                            if (!resolved)
-                                next(err);
-                        });
-                    }
-                    else if (!resolved) {
-                        next();
-                    }
+            let settled = false;
+            let settledError = undefined;
+            let asyncResolve;
+            const next = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                settledError = err;
+                if (asyncResolve)
+                    asyncResolve(err);
+            };
+            let result;
+            try {
+                result = isErrorHandler ? mw(activeError, req, res, next) : mw(req, res, next);
+            }
+            catch (err) {
+                if (!settled) {
+                    settled = true;
+                    settledError = err;
                 }
-                catch (err) {
-                    if (!resolved)
-                        next(err);
+            }
+            const isThenable = result && typeof result.then === 'function';
+            if (settled) {
+                // Completed synchronously (next() called sync, or threw sync).
+                // Matches the old behavior: a still-pending returned promise no longer
+                // gates the chain once next() has been called; swallow late rejections.
+                if (isThenable) {
+                    result.then(undefined, () => { });
                 }
-            });
+                activeError = settledError;
+                continue;
+            }
+            if (!isThenable) {
+                // Sync-looking middleware that neither called next() nor returned a
+                // promise: it will call next() later (e.g. from an event callback).
+                // Fall back to a promise for the remainder of the chain.
+                const resumeIndex = i;
+                return new Promise(resolve => {
+                    asyncResolve = resolve;
+                }).then(err => this.dispatchMiddleware(middleware, req, res, resumeIndex, err));
+            }
+            // Async middleware: completion is next() OR promise settle, whichever
+            // happens first (same semantics as the previous implementation).
+            const resumeIndex = i;
+            return new Promise(resolve => {
+                asyncResolve = resolve;
+                result.then(() => {
+                    if (!settled)
+                        next();
+                }, (err) => {
+                    if (!settled)
+                        next(err);
+                });
+            }).then(err => this.dispatchMiddleware(middleware, req, res, resumeIndex, err));
         }
         // If an error is still unhandled after the chain, re-throw so the top-level
         // catch in handleRequest can invoke the registered errorHandler / default 500.