@catbee/utils 0.0.8-next.0 → 0.0.8-rc.1

package/build/esm/servers/server.js

@@ -0,0 +1,1248 @@
+/*
+ * The MIT License
+ *
+ * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+import express from 'express';
+import https from 'https';
+import { HttpStatusCodes } from '../utils/http-status-codes';
+import { createFinalErrorResponse, SuccessResponse } from '../utils/response.utils';
+import { errorHandler, requestId, responseTime, setupRequestContext, timeout } from '../utils/middleware.utils';
+import { Env } from '../utils/env.utils';
+import { getLogger } from '../utils/logger.utils';
+import { InternalServerErrorException, ServiceUnavailableException } from '../utils/exception.utils';
+import { NotFoundException } from '../utils/exception.utils';
+import fs from 'fs';
+import { defaultServerConfig } from '../config';
+import { deepObjMerge } from '../utils/obj.utils';
+import { fileExists } from '../utils/fs.utils';
+import { BUILD_MARKER } from './server.builder';
+import { isPort } from '../utils/validate.utils';
+/**
+ * Production-ready Express server with enterprise features.
+ *
+ * Core Features:
+ * - Security: Helmet, CORS, rate limiting, timeouts
+ * - Monitoring: Request logs, metrics, health checks
+ * - Performance: Compression, caching, static files
+ * - Reliability: Graceful shutdown, error handling
+ * - Developer UX: OpenAPI docs, debugging tools
+ * - Extensibility: Hooks, middleware, custom routes
+ *
+ * Designed for microservices and production workloads.
+ * Includes K8s readiness probes and zero-downtime support.
+ */
+var ExpressServer = /** @class */ (function () {
+    /**
+     * Initializes server with intelligent defaults and security best practices.
+     * All settings can be customized via config and hooks.
+     *
+     * Default Security:
+     * - Secure headers (Helmet)
+     * - Rate limiting
+     * - Request timeouts
+     * - Body size limits
+     * - CORS protection
+     *
+     * Default Monitoring:
+     * - Request/Response logging
+     * - Prometheus metrics
+     * - Health checks
+     * - Request tracing
+     */
+    function ExpressServer(config, hooks) {
+        var _a;
+        if (hooks === void 0) { hooks = {}; }
+        var _b, _c, _d;
+        /** Prometheus client registry for metrics collection */
+        this.register = null;
+        /** HTTP server instance (null when not running) */
+        this.server = null;
+        /** Set of active WebSocket connections */
+        this.connections = new Set();
+        /** Flag indicating if the server is shutting down */
+        this.isShuttingDown = false;
+        /**
+         * Collection of registered health check functions.
+         * These are executed when the health check endpoint is accessed.
+         */
+        this.healthChecks = [];
+        if (ExpressServer.isBuiltServerConfig(config)) {
+            this.config = config;
+        }
+        else {
+            // Deep merge config with user overrides
+            this.config = deepObjMerge({}, defaultServerConfig, config);
+        }
+        if (!isPort(this.config.port)) {
+            getLogger().error("Port must be a valid number between 1 and 65535, got: ".concat(this.config.port));
+            process.exit(1);
+        }
+        // Sanitize app name for metrics (replace invalid characters with underscore)
+        var safeAppName = (this.config.appName || 'express_app').toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        if ((_b = this.config.metrics) === null || _b === void 0 ? void 0 : _b.enable) {
+            var client = ExpressServer.optionalRequire('prom-client');
+            if (!client) {
+                getLogger().error({ command: 'npm install prom-client' }, 'prom-client is required for metrics but not installed. Please add it to your dependencies');
+                process.exit(1);
+            }
+            this.register = new client.Registry();
+            // Initialize Prometheus metrics with sanitized names
+            this.requestCounter = new client.Counter({
+                name: "".concat(safeAppName, "_http_requests_total"),
+                help: 'Total HTTP requests',
+                labelNames: ['method', 'route', 'status'],
+                registers: [this.register]
+            });
+            this.routeTimings = new client.Histogram({
+                name: "".concat(safeAppName, "_http_request_duration_seconds"),
+                help: 'Duration of HTTP requests by route',
+                labelNames: ['method', 'route', 'status'],
+                buckets: [0.1, 0.3, 0.5, 0.7, 1, 3, 5, 7, 10],
+                registers: [this.register]
+            });
+            this.requestSizes = new client.Histogram({
+                name: "".concat(safeAppName, "_http_request_size_bytes"),
+                help: 'Size of HTTP request bodies',
+                labelNames: ['method', 'route'],
+                buckets: [100, 1000, 10000, 100000, 1000000],
+                registers: [this.register]
+            });
+            this.clientIPs = new client.Counter({
+                name: "".concat(safeAppName, "_http_client_ip_total"),
+                help: 'Client IP request counter',
+                labelNames: ['ip', 'method'],
+                registers: [this.register]
+            });
+            // Default system metrics (CPU, memory, event loop lag, etc.)
+            client.collectDefaultMetrics({
+                register: this.register,
+                prefix: "".concat(safeAppName, "_")
+            });
+        }
+        // Health checks
+        if ((_c = config.healthCheck) === null || _c === void 0 ? void 0 : _c.checks) {
+            (_a = this.healthChecks).push.apply(_a, __spreadArray([], __read(config.healthCheck.checks), false));
+        }
+        // Set global prefix (normalize to empty string or "/prefix" without trailing slash)
+        this.globalPrefix = this.normalizePath((_d = this.config.globalPrefix) !== null && _d !== void 0 ? _d : '', false);
+        this.hooks = hooks;
+        this.app = express();
+        this.rootRouter = express.Router();
+        // Store initialization promise to prevent race conditions with start()
+        this.initPromise = this.initialize();
+    }
+    /**
+     * Execute a lifecycle hook safely with comprehensive error handling.
+     * Prevents hook failures from crashing the server while logging issues.
+     *
+     * @param hook Name of the lifecycle hook to execute
+     * @param args Arguments to pass to the hook function
+     */
+    ExpressServer.prototype.runHook = function (hook) {
+        var args = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            args[_i - 1] = arguments[_i];
+        }
+        return __awaiter(this, void 0, void 0, function () {
+            var fn, err_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 3, , 4]);
+                        fn = this.hooks[hook];
+                        if (!fn) return [3 /*break*/, 2];
+                        return [4 /*yield*/, fn.apply(null, args)];
+                    case 1:
+                        _a.sent();
+                        _a.label = 2;
+                    case 2: return [3 /*break*/, 4];
+                    case 3:
+                        err_1 = _a.sent();
+                        getLogger().error({ err: err_1, hook: hook }, "Error executing ".concat(hook, " hook:"));
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Initialize the Express server with middleware and routes.
+     */
+    ExpressServer.prototype.initialize = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.runHook('beforeInit', this)];
+                    case 1:
+                        _a.sent();
+                        // Set up middleware stack (order is critical)
+                        return [4 /*yield*/, this.setupMiddleware()];
+                    case 2:
+                        // Set up middleware stack (order is critical)
+                        _a.sent();
+                        // Set up default routes and error handling
+                        return [4 /*yield*/, this.setupRoutes()];
+                    case 3:
+                        // Set up default routes and error handling
+                        _a.sent();
+                        return [4 /*yield*/, this.runHook('afterInit', this)];
+                    case 4:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Configure and register all middlewares in the optimal order.
+     *
+     * Middleware Order (CRITICAL - don't change without understanding implications):
+     * 1.  Basic server configuration (trust proxy, x-powered-by)
+     * 2.  Request ID generation (for tracing)
+     * 3.  Request context setup (for logging correlation)
+     * 4.  Timeout protection (prevents hanging requests)
+     * 5.  Response time tracking (for performance monitoring)
+     * 6.  Request logging (after ID/context setup)
+     * 7.  Custom request hooks
+     * 8.  Security middleware (rate limiting, CORS, Helmet)
+     * 9.  Response compression
+     * 10. Static file serving
+     * 11. Request parsing (body parsing, cookies)
+     * 12. API documentation (OpenAPI)
+     * 13. Global headers
+     * 14. Custom response hooks
+     */
+    ExpressServer.prototype.setupMiddleware = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var helmet, cors, rateLimit, compression, cookieParser, openApiMountPath, openApiFilePath, isOpenApiFilePathExists, apiReference, _a, _b, _c, _d, err_2;
+            var _e, _f;
+            var _this = this;
+            var _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x;
+            return __generator(this, function (_y) {
+                switch (_y.label) {
+                    case 0:
+                        if (!this.config.https) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.validateHttpsFiles()];
+                    case 1:
+                        _y.sent();
+                        _y.label = 2;
+                    case 2:
+                        // Basic middleware should be first
+                        this.app.disable('x-powered-by');
+                        if (this.config.trustProxy) {
+                            this.app.set('trust proxy', true);
+                        }
+                        // Request ID generation - must be first for proper tracing
+                        this.app.use(requestId({
+                            headerName: (_g = this.config.requestId) === null || _g === void 0 ? void 0 : _g.headerName,
+                            exposeHeader: (_h = this.config.requestId) === null || _h === void 0 ? void 0 : _h.exposeHeader,
+                            generator: (_j = this.config.requestId) === null || _j === void 0 ? void 0 : _j.generator
+                        }));
+                        // Request context setup for logging correlation
+                        this.app.use(setupRequestContext({
+                            headerName: (_k = this.config.requestId) === null || _k === void 0 ? void 0 : _k.headerName,
+                            autoLog: false
+                        }));
+                        // Early shutdown-awareness middleware (lets load balancers drain connections gracefully)
+                        this.app.use(function (_req, res, next) {
+                            if (_this.isShuttingDown) {
+                                res.setHeader('Connection', 'close');
+                                return res
+                                    .status(HttpStatusCodes.SERVICE_UNAVAILABLE)
+                                    .json(new ServiceUnavailableException('Server is shutting down'));
+                            }
+                            next();
+                            return;
+                        });
+                        // Security middleware should come early
+                        if (this.config.helmet) {
+                            helmet = ExpressServer.optionalRequire('helmet');
+                            if (!helmet) {
+                                getLogger().error({ command: 'npm install helmet' }, 'helmet is required but not installed. Please add it to your dependencies');
+                                process.exit(1);
+                            }
+                            if (typeof this.config.helmet === 'object') {
+                                this.app.use(helmet(this.config.helmet));
+                            }
+                            else {
+                                this.app.use(helmet());
+                            }
+                        }
+                        // CORS middleware should be early
+                        if (this.config.cors) {
+                            cors = ExpressServer.optionalRequire('cors');
+                            if (!cors) {
+                                getLogger().error({ command: 'npm install cors' }, 'cors is required but not installed. Please add it to your dependencies');
+                                process.exit(1);
+                            }
+                            this.app.use(cors(this.config.cors === true ? {} : this.config.cors));
+                        }
+                        // Global headers
+                        this.app.use(function (_req, res, next) {
+                            var _a, _b, _c, _d;
+                            if (_this.config.globalHeaders) {
+                                for (var key in _this.config.globalHeaders) {
+                                    var value = _this.config.globalHeaders[key];
+                                    res.setHeader(key, typeof value === 'function' ? value() : value);
+                                }
+                            }
+                            if (_this.config.isMicroservice) {
+                                res.setHeader('X-Microservice', _this.config.appName || 'express_app');
+                            }
+                            if ((_a = _this.config.serviceVersion) === null || _a === void 0 ? void 0 : _a.enable) {
+                                var version = typeof ((_b = _this.config.serviceVersion) === null || _b === void 0 ? void 0 : _b.version) === 'function'
+                                    ? _this.config.serviceVersion.version()
+                                    : (_c = _this.config.serviceVersion) === null || _c === void 0 ? void 0 : _c.version;
+                                res.setHeader(((_d = _this.config.serviceVersion) === null || _d === void 0 ? void 0 : _d.headerName) || 'x-service-version', version || '0.0.0');
+                            }
+                            next();
+                        });
+                        // Global request timeout protection
+                        if (this.config.requestTimeout) {
+                            this.app.use(timeout(this.config.requestTimeout));
+                        }
+                        // Response time tracking for performance monitoring
+                        if ((_l = this.config.responseTime) === null || _l === void 0 ? void 0 : _l.enable) {
+                            this.app.use(responseTime({
+                                addHeader: this.config.responseTime.addHeader,
+                                logOnComplete: this.config.responseTime.logOnComplete
+                            }));
+                        }
+                        // Rate limiting should be early to prevent unnecessary processing
+                        if ((_m = this.config.rateLimit) === null || _m === void 0 ? void 0 : _m.enable) {
+                            rateLimit = ExpressServer.optionalRequire('express-rate-limit');
+                            if (!rateLimit) {
+                                getLogger().error({ command: 'npm install express-rate-limit' }, 'express-rate-limit is required but not installed. Please add it to your dependencies');
+                                process.exit(1);
+                            }
+                            this.app.use(rateLimit({
+                                windowMs: (_o = this.config.rateLimit.windowMs) !== null && _o !== void 0 ? _o : 15 * 60 * 1000,
+                                max: (_p = this.config.rateLimit.max) !== null && _p !== void 0 ? _p : 100,
+                                handler: function (req, res) {
+                                    var _a;
+                                    var status = HttpStatusCodes.TOO_MANY_REQUESTS;
+                                    var response = createFinalErrorResponse(req, status, ((_a = _this.config.rateLimit) === null || _a === void 0 ? void 0 : _a.message) || 'Too many requests');
+                                    res.status(status).json(response);
+                                },
+                                standardHeaders: (_q = this.config.rateLimit.standardHeaders) !== null && _q !== void 0 ? _q : true,
+                                legacyHeaders: (_r = this.config.rateLimit.legacyHeaders) !== null && _r !== void 0 ? _r : false
+                            }));
+                        }
+                        // Request logging with filtering
+                        if ((_s = this.config.requestLogging) === null || _s === void 0 ? void 0 : _s.enable) {
+                            this.app.use(function (req, res, next) {
+                                var _a, _b, _c, _d, _e, _f;
+                                if (typeof ((_a = _this.config.requestLogging) === null || _a === void 0 ? void 0 : _a.ignorePaths) === 'function') {
+                                    var skip = (_c = (_b = _this.config.requestLogging) === null || _b === void 0 ? void 0 : _b.ignorePaths) === null || _c === void 0 ? void 0 : _c.call(_b, req, res);
+                                    if (skip)
+                                        return next();
+                                }
+                                else if (Array.isArray((_d = _this.config.requestLogging) === null || _d === void 0 ? void 0 : _d.ignorePaths)) {
+                                    var skip = (_f = (_e = _this.config.requestLogging) === null || _e === void 0 ? void 0 : _e.ignorePaths) === null || _f === void 0 ? void 0 : _f.includes(req.path);
+                                    if (skip)
+                                        return next();
+                                }
+                                var logger = getLogger();
+                                var incomingRequestMetaData = {
+                                    requestId: req.id,
+                                    method: req.method,
+                                    url: req.originalUrl || req.url,
+                                    ip: req.ip
+                                };
+                                logger.info(incomingRequestMetaData, 'Incoming Request');
+                                next();
+                            });
+                        }
+                        // Custom request preprocessing hook
+                        if (this.hooks.onRequest) {
+                            this.app.use(this.hooks.onRequest);
+                        }
+                        // Response compression for better performance
+                        if (this.config.compression) {
+                            compression = ExpressServer.optionalRequire('compression');
+                            if (!compression) {
+                                getLogger().error({ command: 'npm install compression' }, 'compression is required but not installed. Please add it to your dependencies');
+                                process.exit(1);
+                            }
+                            if (typeof this.config.compression === 'object') {
+                                this.app.use(compression(this.config.compression));
+                            }
+                            else {
+                                this.app.use(compression());
+                            }
+                        }
+                        // Static file serving (do NOT normalize filesystem path; only normalize route)
+                        if (this.config.staticFolders) {
+                            this.config.staticFolders.forEach(function (folder) {
+                                var _a;
+                                _this.app.use(_this.normalizePath((_a = folder.path) !== null && _a !== void 0 ? _a : '/'), express.static(folder.directory, {
+                                    maxAge: folder.maxAge || 0,
+                                    etag: folder.etag !== false,
+                                    immutable: folder.immutable === true,
+                                    lastModified: folder.lastModified !== false,
+                                    cacheControl: folder.cacheControl !== false
+                                }));
+                                getLogger().info("Serving static folder: ".concat(folder.directory, " at path ").concat(folder.path || '/'));
+                            });
+                        }
+                        // Request body parsing with size limits
+                        if (this.config.bodyParser) {
+                            if (this.config.bodyParser.json) {
+                                this.app.use(express.json(this.config.bodyParser.json));
+                            }
+                            if (this.config.bodyParser.urlencoded) {
+                                this.app.use(express.urlencoded(this.config.bodyParser.urlencoded));
+                            }
+                        }
+                        // Cookie parser middleware
+                        if (this.config.cookieParser) {
+                            cookieParser = ExpressServer.optionalRequire('cookie-parser');
+                            if (!cookieParser) {
+                                getLogger().error({ command: 'npm install cookie-parser' }, 'cookie-parser is required but not installed. Please add it to your dependencies');
+                                process.exit(1);
+                            }
+                            if (typeof this.config.cookieParser === 'object') {
+                                this.app.use(cookieParser(undefined, this.config.cookieParser));
+                            }
+                            else {
+                                this.app.use(cookieParser());
+                            }
+                        }
+                        if (!((_t = this.config.openApi) === null || _t === void 0 ? void 0 : _t.enable)) return [3 /*break*/, 7];
+                        _y.label = 3;
+                    case 3:
+                        _y.trys.push([3, 6, , 7]);
+                        openApiMountPath = this.normalizePath((_u = this.config.openApi.mountPath) !== null && _u !== void 0 ? _u : '/docs', this.config.openApi.withGlobalPrefix);
+                        openApiFilePath = this.config.openApi.filePath;
+                        if (!openApiFilePath) {
+                            getLogger().error('OpenAPI file path is required');
+                            process.exit(1);
+                        }
+                        return [4 /*yield*/, fileExists(openApiFilePath)];
+                    case 4:
+                        isOpenApiFilePathExists = _y.sent();
+                        if (!isOpenApiFilePathExists) {
+                            getLogger().error("OpenAPI spec file not found at ".concat(openApiFilePath));
+                            process.exit(1);
+                        }
+                        if ((_v = this.config.openApi) === null || _v === void 0 ? void 0 : _v.verbose) {
+                            getLogger().info("Mounting OpenAPI docs at ".concat(openApiMountPath));
+                            getLogger().info("Using OpenAPI spec file at ".concat(openApiFilePath));
+                        }
+                        apiReference = ExpressServer.optionalRequire('@scalar/express-api-reference').apiReference;
+                        if (!apiReference) {
+                            getLogger().error({ command: 'npm install @scalar/express-api-reference' }, '@scalar/express-api-reference is required for OpenAPI docs but not installed. Please add it to your dependencies');
+                            process.exit(1);
+                        }
+                        _b = (_a = this.app).use;
+                        _c = [openApiMountPath];
+                        _d = apiReference;
+                        _e = {};
+                        _f = {};
+                        return [4 /*yield*/, fs.promises.readFile(openApiFilePath, 'utf8')];
+                    case 5:
+                        _b.apply(_a, _c.concat([_d.apply(void 0, [(_e.spec = (_f.content = _y.sent(),
+                                    _f),
+                                    _e)])]));
+                        if ((_w = this.config.openApi) === null || _w === void 0 ? void 0 : _w.verbose) {
+                            getLogger().info("Mounted OpenAPI docs at ".concat(openApiMountPath));
+                        }
+                        return [3 /*break*/, 7];
+                    case 6:
+                        err_2 = _y.sent();
+                        getLogger().error({ err: err_2 }, 'Failed to mount OpenAPI docs');
+                        return [3 /*break*/, 7];
+                    case 7:
+                        // Custom response preprocessing hook (apply global prefix if set)
+                        if (this.hooks.onResponse) {
+                            this.app.use(this.globalPrefix, this.hooks.onResponse);
+                        }
+                        if ((_x = this.config.metrics) === null || _x === void 0 ? void 0 : _x.enable) {
+                            // Add metrics tracking middleware
+                            this.app.use(function (req, res, next) {
+                                var _a, _b;
+                                var start = process.hrtime();
+                                // Track client IPs
+                                (_a = _this.clientIPs) === null || _a === void 0 ? void 0 : _a.inc({ ip: req.ip, method: req.method });
+                                // Track request sizes (parse safely)
+                                var cl = req.headers['content-length'];
+                                if (cl) {
+                                    var size = Number(cl);
+                                    if (!Number.isNaN(size) && size >= 0) {
+                                        var route = _this.normalizeRouteForMetrics(req, res);
+                                        (_b = _this.requestSizes) === null || _b === void 0 ? void 0 : _b.observe({ method: req.method, route: route }, size);
+                                    }
+                                }
+                                res.once('finish', function () {
+                                    var _a, _b;
+                                    var _c = __read(process.hrtime(start), 2), seconds = _c[0], nanoseconds = _c[1];
+                                    var finalRoute = _this.normalizeRouteForMetrics(req, res);
+                                    (_a = _this.requestCounter) === null || _a === void 0 ? void 0 : _a.inc({
+                                        method: req.method,
+                                        route: finalRoute,
+                                        status: res.statusCode.toString()
+                                    });
+                                    (_b = _this.routeTimings) === null || _b === void 0 ? void 0 : _b.observe({
+                                        method: req.method,
+                                        route: finalRoute,
+                                        status: res.statusCode.toString()
+                                    }, seconds + nanoseconds / 1e9);
+                                });
+                                next();
+                            });
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Configure server routes and error handling.
+     * Sets up in following order:
+     *
+     * 1. Built-in routes (health, metrics)
+     * 2. Application routes
+     * 3. 404 handler
+     * 4. Error handler
+     */
+    ExpressServer.prototype.setupRoutes = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var healthCheckPath, metricsPath, routerToUse;
+            var _this = this;
+            var _a, _b, _c, _d, _e;
+            return __generator(this, function (_f) {
+                healthCheckPath = this.normalizePath(((_a = this.config.healthCheck) === null || _a === void 0 ? void 0 : _a.path) || '/healthz', (_b = this.config.healthCheck) === null || _b === void 0 ? void 0 : _b.withGlobalPrefix);
+                this.app.get(healthCheckPath, function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+                    var checkResults, results, allOk, status_1, response, _a;
+                    var _this = this;
+                    var _b;
+                    return __generator(this, function (_c) {
+                        switch (_c.label) {
+                            case 0:
+                                _c.trys.push([0, 2, , 3]);
+                                if (!this.healthChecks.length) {
+                                    return [2 /*return*/, res.status(HttpStatusCodes.OK).json(new SuccessResponse('OK'))];
+                                }
+                                return [4 /*yield*/, Promise.allSettled(this.healthChecks.map(function (_a) { return __awaiter(_this, [_a], void 0, function (_b) {
+                                        var status_2, error_1;
+                                        var name = _b.name, check = _b.check;
+                                        return __generator(this, function (_c) {
+                                            switch (_c.label) {
+                                                case 0:
+                                                    _c.trys.push([0, 2, , 3]);
+                                                    return [4 /*yield*/, Promise.resolve(check())];
+                                                case 1:
+                                                    status_2 = _c.sent();
+                                                    return [2 /*return*/, { name: name, status: status_2, error: null }];
+                                                case 2:
+                                                    error_1 = _c.sent();
+                                                    return [2 /*return*/, { name: name, status: false, error: error_1.message }];
+                                                case 3: return [2 /*return*/];
+                                            }
+                                        });
+                                    }); }))];
+                            case 1:
+                                checkResults = _c.sent();
+                                results = checkResults.map(function (result) {
+                                    if (result.status === 'fulfilled')
+                                        return result.value;
+                                    return { name: 'unknown', status: false, error: result.reason };
+                                });
+                                allOk = results.every(function (r) { return r.status; });
+                                status_1 = allOk ? HttpStatusCodes.OK : HttpStatusCodes.SERVICE_UNAVAILABLE;
+                                response = new SuccessResponse(allOk ? 'OK' : 'Service unavailable');
+                                if (!allOk)
+                                    response.error = true;
+                                if ((_b = this.config.healthCheck) === null || _b === void 0 ? void 0 : _b.detailed)
+                                    response.data = { checks: results };
+                                return [2 /*return*/, res.status(status_1).json(response)];
+                            case 2:
+                                _a = _c.sent();
+                                return [2 /*return*/, res
+                                        .status(HttpStatusCodes.INTERNAL_SERVER_ERROR)
+                                        .json(new InternalServerErrorException('Health check failed'))];
+                            case 3: return [2 /*return*/];
+                        }
+                    });
+                }); });
+                // Metrics endpoint
+                if ((_c = this.config.metrics) === null || _c === void 0 ? void 0 : _c.enable) {
+                    metricsPath = this.normalizePath((_d = this.config.metrics.path) !== null && _d !== void 0 ? _d : '/metrics', (_e = this.config.metrics) === null || _e === void 0 ? void 0 : _e.withGlobalPrefix);
+                    this.app.get(metricsPath, function (_req, res) { return __awaiter(_this, void 0, void 0, function () {
+                        var _a, _b;
+                        return __generator(this, function (_c) {
+                            switch (_c.label) {
+                                case 0:
+                                    res.set('Content-Type', this.register.contentType);
+                                    _b = (_a = res).end;
+                                    return [4 /*yield*/, this.register.metrics()];
+                                case 1:
+                                    _b.apply(_a, [_c.sent()]);
+                                    return [2 /*return*/];
+                            }
+                        });
+                    }); });
+                }
+                routerToUse = this.externalRouter || this.rootRouter;
+                this.app.use(this.globalPrefix, routerToUse);
+                // 404 handler (must be after all other routes)
+                this.app.use(function (req, res) {
+                    var status = HttpStatusCodes.NOT_FOUND;
+                    var response = createFinalErrorResponse(req, status, "Route ".concat(req.method.toUpperCase(), " ").concat(req.path, " not found"));
+                    res.status(status).json(response);
+                });
+                // Global error handler (must be the last middleware)
+                this.app.use(function (err, req, res, next) {
+                    var _a;
+                    // Check if this is a 404 error that should be handled with special logging rules
+                    var isNotFoundError = err instanceof NotFoundException;
+                    var shouldSkipLogging = !_this.hooks.onError &&
+                        isNotFoundError &&
+                        ((_a = _this.config.requestLogging) === null || _a === void 0 ? void 0 : _a.enable) &&
+                        _this.config.requestLogging.skipNotFoundRoutes === true;
+                    if (_this.hooks.onError) {
+                        // Use custom error handler if provided
+                        _this.hooks.onError(err, req, res, next);
+                    }
+                    else {
+                        // Default error handler with logging
+                        var errorHandlerMiddleware = errorHandler({
+                            logErrors: !shouldSkipLogging,
+                            includeDetails: Env.isDev() // Only show stack traces in development
+                        });
+                        errorHandlerMiddleware(err, req, res, next);
+                    }
+                });
+                return [2 /*return*/];
+            });
+        });
+    };
+    /**
+     * Register a new health check function for monitoring service dependencies.
+     *
+     * Health checks are executed when the health endpoint is accessed and
+     * help determine if the service is ready to handle requests.
+     *
+     * Examples:
+     * - Database connectivity
+     * - External service availability
+     * - File system access
+     * - Memory/CPU usage checks
+     *
+     * @param name Unique identifier for the check (used in detailed responses)
+     * @param check Function returning boolean or Promise<boolean> indicating health
+     * @returns This instance for method chaining
+     */
+    ExpressServer.prototype.registerHealthCheck = function (name, check) {
+        this.healthChecks.push({ name: name, check: check });
+        return this;
+    };
+    /**
+     * Get the underlying Express application instance.
+     * Use this for advanced Express features not exposed by this wrapper.
+     *
+     * @returns The raw Express app instance
+     */
+    ExpressServer.prototype.getApp = function () {
+        return this.app;
+    };
+    /**
+     * Get the active HTTP/HTTPS server instance.
+     * Returns null if the server is not currently running.
+     *
+     * @returns The HTTP/HTTPS server instance or null
+     */
+    ExpressServer.prototype.getServer = function () {
+        return this.server;
+    };
+    /**
+     * Start the HTTP server and begin listening for requests.
+     *
+     * This method:
+     * - Executes beforeStart hooks
+     * - Binds to the configured host/port
+     * - Sets up error handling for startup failures
+     * - Executes afterStart hooks on success
+     * - Logs startup information
+     *
+     * @returns Promise resolving to the running HTTP server instance
+     * @throws Error if server fails to start or port is already in use
+     */
+    ExpressServer.prototype.start = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _this = this;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: 
+                    // Ensure initialization (middleware + routes) completed before starting
+                    return [4 /*yield*/, this.initPromise];
+                    case 1:
+                        // Ensure initialization (middleware + routes) completed before starting
+                        _a.sent();
+                        return [4 /*yield*/, this.runHook('beforeStart', this.app)];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/, new Promise(function (resolve, reject) {
+                                var _a, _b;
+                                try {
+                                    // Prepare listen arguments with optional host parameter
+                                    var listenArgs = [
+                                        _this.config.port,
+                                        _this.config.host,
+                                        function () { return __awaiter(_this, void 0, void 0, function () {
+                                            var protocol, url;
+                                            var _a, _b, _c;
+                                            return __generator(this, function (_d) {
+                                                switch (_d.label) {
+                                                    case 0:
+                                                        protocol = this.config.https ? 'https' : 'http';
+                                                        url = "".concat(protocol, "://").concat(this.config.host, ":").concat(this.config.port);
+                                                        getLogger().info("Server running on ".concat(url));
+                                                        if ((_a = this.config.healthCheck) === null || _a === void 0 ? void 0 : _a.path) {
+                                                            getLogger().info("Health check available at ".concat(url).concat(this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)));
+                                                        }
+                                                        if (((_b = this.config.metrics) === null || _b === void 0 ? void 0 : _b.enable) && this.config.metrics.path) {
+                                                            getLogger().info("Metrics available at ".concat(url).concat(this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)));
+                                                        }
+                                                        if ((_c = this.config.openApi) === null || _c === void 0 ? void 0 : _c.enable) {
+                                                            getLogger().info("API docs available at ".concat(url).concat(this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)));
+                                                        }
+                                                        if (!this.server) return [3 /*break*/, 2];
+                                                        return [4 /*yield*/, this.runHook('afterStart', this.server)];
+                                                    case 1:
+                                                        _d.sent();
+                                                        _d.label = 2;
+                                                    case 2:
+                                                        resolve(this.server);
+                                                        return [2 /*return*/];
+                                                }
+                                            });
+                                        }); }
+                                    ];
+                                    if (_this.config.https) {
+                                        var httpsOptions = __assign(__assign({}, _this.config.https), { key: fs.readFileSync(_this.config.https.key), cert: fs.readFileSync(_this.config.https.cert) });
+                                        if (_this.config.https.ca) {
+                                            httpsOptions.ca = fs.readFileSync(_this.config.https.ca);
+                                        }
+                                        if (_this.config.https.passphrase) {
+                                            httpsOptions.passphrase = _this.config.https.passphrase;
+                                        }
+                                        _this.server = (_a = https.createServer(httpsOptions, _this.app)).listen.apply(_a, __spreadArray([], __read(listenArgs), false));
+                                    }
+                                    else {
+                                        // Start the HTTP server
+                                        _this.server = (_b = _this.app).listen.apply(_b, __spreadArray([], __read(listenArgs), false));
+                                    }
+                                    // Track connections
+                                    _this.server.on('connection', function (conn) {
+                                        _this.connections.add(conn);
+                                        conn.on('close', function () { return _this.connections.delete(conn); });
+                                    });
+                                    // Handle server startup errors (port in use, permission denied, etc.)
+                                    _this.server.on('error', function (err) {
+                                        getLogger().error({ err: err }, 'Server failed to start');
+                                        reject(err);
+                                    });
+                                }
+                                catch (error) {
+                                    reject(error);
+                                }
+                            })];
+                }
+            });
+        });
+    };
+    /**
+     * Stop the HTTP server gracefully.
+     *
+     * This method:
+     * - Executes beforeStop hooks
+     * - Stops accepting new connections
+     * - Waits for existing connections to finish
+     * - Closes the server
+     * - Executes afterStop hooks
+     * - Logs shutdown information
+     *
+     * Graceful shutdown ensures:
+     * - No requests are dropped
+     * - Resources are properly cleaned up
+     * - Monitoring systems are notified
+     */
+    ExpressServer.prototype.stop = function () {
+        return __awaiter(this, arguments, void 0, function (force) {
+            var shutdownTimeout, serverClosePromise, timeoutPromise, err_3;
+            var _this = this;
+            if (force === void 0) { force = false; }
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        if (!this.server) {
+                            getLogger().warn('Stop called but server is not running');
+                            return [2 /*return*/];
+                        }
+                        if (this.isShuttingDown) {
+                            getLogger().warn('Stop called while shutdown is already in progress');
+                            return [2 /*return*/];
+                        }
+                        this.isShuttingDown = true;
+                        return [4 /*yield*/, this.runHook('beforeStop', this.server)];
+                    case 1:
+                        _a.sent();
+                        shutdownTimeout = 10000;
+                        serverClosePromise = new Promise(function (resolve, reject) {
+                            _this.server.close(function (err) { return __awaiter(_this, void 0, void 0, function () {
+                                return __generator(this, function (_a) {
+                                    switch (_a.label) {
+                                        case 0:
+                                            if (err) {
+                                                getLogger().error({ err: err }, 'Error while closing server');
+                                                reject(err);
+                                                return [2 /*return*/];
+                                            }
+                                            this.server = null;
+                                            this.isShuttingDown = false;
+                                            getLogger().info('Server stopped gracefully');
+                                            return [4 /*yield*/, this.runHook('afterStop')];
+                                        case 1:
+                                            _a.sent();
+                                            resolve();
+                                            return [2 /*return*/];
+                                    }
+                                });
+                            }); });
+                        });
+                        timeoutPromise = new Promise(function (_, reject) {
+                            return setTimeout(function () { return reject(new Error('Shutdown timeout')); }, shutdownTimeout);
+                        });
+                        _a.label = 2;
+                    case 2:
+                        _a.trys.push([2, 4, 5, 7]);
+                        return [4 /*yield*/, Promise.race([serverClosePromise, timeoutPromise])];
+                    case 3:
+                        _a.sent();
+                        return [3 /*break*/, 7];
+                    case 4:
+                        err_3 = _a.sent();
+                        getLogger().error({ err: err_3 }, 'Graceful shutdown timed out');
+                        if (force) {
+                            getLogger().warn('Forcing connection destroy due to shutdown timeout');
+                        }
+                        return [3 /*break*/, 7];
+                    case 5: 
+                    // Always clean up connections
+                    return [4 /*yield*/, this.destroyConnections()];
+                    case 6:
+                        // Always clean up connections
+                        _a.sent();
+                        return [7 /*endfinally*/];
+                    case 7: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    /**
+     * Enable graceful shutdown on OS signals for production deployment.
+     *
+     * This is essential for:
+     * - Container orchestration (Docker, Kubernetes)
+     * - Process managers (PM2, systemd)
+     * - Load balancer health checks
+     * - Zero-downtime deployments
+     *
+     * @param signals Array of process signals to listen for (default: SIGINT, SIGTERM)
+     */
+    ExpressServer.prototype.enableGracefulShutdown = function (signals) {
+        var _this = this;
+        if (signals === void 0) { signals = ['SIGINT', 'SIGTERM']; }
+        signals.forEach(function (signal) {
+            process.on(signal, function () { return __awaiter(_this, void 0, void 0, function () {
+                var err_4, forceError_1;
+                return __generator(this, function (_a) {
+                    switch (_a.label) {
+                        case 0:
+                            getLogger().info("Received ".concat(signal, ", initiating graceful shutdown..."));
+                            _a.label = 1;
+                        case 1:
+                            _a.trys.push([1, 3, , 8]);
+                            return [4 /*yield*/, this.stop()];
+                        case 2:
+                            _a.sent();
+                            process.exit(0);
+                            return [3 /*break*/, 8];
+                        case 3:
+                            err_4 = _a.sent();
+                            getLogger().error({ err: err_4 }, 'Error during graceful shutdown, forcing stop...');
+                            _a.label = 4;
+                        case 4:
+                            _a.trys.push([4, 6, , 7]);
+                            return [4 /*yield*/, this.stop(true)];
+                        case 5:
+                            _a.sent(); // fallback to forced shutdown
+                            process.exit(1);
+                            return [3 /*break*/, 7];
+                        case 6:
+                            forceError_1 = _a.sent();
+                            getLogger().fatal({ forceError: forceError_1 }, 'Forced shutdown failed, exiting hard');
+                            process.exit(1);
+                            return [3 /*break*/, 7];
+                        case 7: return [3 /*break*/, 8];
+                        case 8: return [2 /*return*/];
+                    }
+                });
+            }); });
+        });
+        return this;
+    };
+    /**
+     * Set an externally created base router.
+     * This will override the internal rootRouter.
+     */
+    ExpressServer.prototype.setBaseRouter = function (router) {
+        this.externalRouter = router;
+        return this;
+    };
+    /**
+     * Create and register a new router (only used if not injecting one externally - use `setBaseRouter` instead).
+     */
+    ExpressServer.prototype.createRouter = function (prefix) {
+        if (prefix === void 0) { prefix = ''; }
+        var router = express.Router();
+        var path = this.normalizePath(prefix, true);
+        this.rootRouter.use(path, router);
+        return router;
+    };
+    /**
+     * Register a new route handler with support for multiple HTTP methods.
+     * The route is automatically registered under the globalPrefix if set.
+     *
+     * @param methods Array of HTTP methods (get, post, put, delete, etc.)
+     * @param path Route path with Express path patterns support
+     * @param handlers One or more Express request handlers (middleware + final handler)
+     * @returns This instance for method chaining
+     */
+    ExpressServer.prototype.registerRoute = function (methods, path) {
+        var handlers = [];
+        for (var _i = 2; _i < arguments.length; _i++) {
+            handlers[_i - 2] = arguments[_i];
+        }
+        var fullPath = this.normalizePath(path, true);
+        var methodMap = {
+            get: this.app.get.bind(this.app),
+            post: this.app.post.bind(this.app),
+            put: this.app.put.bind(this.app),
+            delete: this.app.delete.bind(this.app),
+            patch: this.app.patch.bind(this.app),
+            options: this.app.options.bind(this.app),
+            head: this.app.head.bind(this.app)
+        };
+        methods.forEach(function (m) {
+            var fn = methodMap[m];
+            if (fn) {
+                fn.apply(void 0, __spreadArray([fullPath], __read(handlers), false));
+            }
+            else {
+                throw new Error("Unsupported HTTP method: ".concat(m));
+            }
+        });
+        return this;
+    };
+    /**
+     * Register custom middleware with optional path restriction.
+     *
+     * Use this for:
+     * - Adding authentication to specific routes
+     * - Custom logging or validation
+     * - Request transformation
+     * - Third-party middleware integration
+     *
+     * @param path Optional path prefix or middleware function if no path
+     * @param middleware Middleware handler (required if path is provided)
+     * @returns This instance for method chaining
+     */
+    ExpressServer.prototype.registerMiddleware = function (path, middleware) {
+        if (typeof path === 'string') {
+            var normalizedPath = this.normalizePath(path);
+            if (normalizedPath) {
+                this.app.use(normalizedPath, middleware);
+            }
+            else {
+                this.app.use(middleware);
+            }
+        }
+        else {
+            this.app.use(path);
+        }
+        return this;
+    };
+    /**
+     * Register one or more middleware functions to be applied globally.
+     * This is a simpler alternative to registerMiddleware when you just want
+     * to add middleware without path restrictions.
+     *
+     * @param middlewares One or more Express middleware functions
+     * @returns This instance for method chaining
+     */
+    ExpressServer.prototype.useMiddleware = function () {
+        var _this = this;
+        var middlewares = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            middlewares[_i] = arguments[_i];
+        }
+        middlewares.forEach(function (middleware) {
+            _this.app.use(middleware);
+        });
+        return this;
+    };
+    /**
+     * Get Prometheus registry (to add custom counters/histograms)
+     *
+     * @return {*}  {client.Registry}
+     */
+    ExpressServer.prototype.getMetricsRegistry = function () {
+        var _a;
+        if (!((_a = this.config.metrics) === null || _a === void 0 ? void 0 : _a.enable)) {
+            throw new Error('Metrics are not enabled in the server configuration');
+        }
+        return this.register;
+    };
+    /**
+     * Get server configuration
+     *
+     * @return {*}  {ServerConfig}
+     */
+    ExpressServer.prototype.getConfig = function () {
+        return this.config;
+    };
+    /**
+     * Wait until server initialization (middleware + routes) has completed.
+     * Useful for integration tests that inspect app before starting.
+     */
+    ExpressServer.prototype.waitUntilReady = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.initPromise];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    ExpressServer.prototype.normalizePath = function (path, withGlobalPrefix) {
+        if (withGlobalPrefix === void 0) { withGlobalPrefix = false; }
+        var sanitize = function (p) {
+            return ('/' +
+                p
+                    .trim()
+                    .replace(/^\/+/, '') // remove leading slashes
+                    .replace(/\/{2,}/g, '/') // collapse multiple slashes
+                    .replace(/\/+$/, '')); // remove trailing slash
+        };
+        // Resolve global prefix if enabled
+        var prefix = withGlobalPrefix && this.globalPrefix ? sanitize(this.globalPrefix) : '';
+        // If path is invalid, default to prefix or root
+        if (typeof path !== 'string' || !path.trim()) {
+            return prefix || '/';
+        }
+        return sanitize(prefix + '/' + path);
+    };
+    ExpressServer.prototype.normalizeRouteForMetrics = function (req, res) {
+        var _a;
+        // Prevent high cardinality metrics by normalizing routes
+        if ((_a = req === null || req === void 0 ? void 0 : req.route) === null || _a === void 0 ? void 0 : _a.path) {
+            // Use Express route pattern instead of actual URL
+            return req.route.path;
+        }
+        // Group common patterns
+        if (res.statusCode === 404)
+            return '/404';
+        var path = (req.path || 'unknown').split('?')[0];
+        // Replace IDs and UUIDs with placeholders
+        return path
+            .replace(/\/[0-9]+/g, '/:id')
+            .replace(/\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, '/:uuid');
+    };
+    /**
+     * Destroy all active connections (gracefully if possible).
+     * If a connection does not close cleanly, it will be force-destroyed.
+     */
+    ExpressServer.prototype.destroyConnections = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var total, timeoutMs;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        total = this.connections.size;
+                        if (total === 0) {
+                            getLogger().debug('No active connections to close');
+                            return [2 /*return*/];
+                        }
+                        timeoutMs = 5000;
+                        return [4 /*yield*/, Promise.race([
+                                Promise.all(Array.from(this.connections).map(function (conn) {
+                                    return new Promise(function (resolve) {
+                                        conn.end(function () {
+                                            if (!conn.destroyed)
+                                                conn.destroy();
+                                            resolve();
+                                        });
+                                        conn.on('error', function () {
+                                            conn.destroy();
+                                            resolve();
+                                        });
+                                    });
+                                })),
+                                new Promise(function (resolve) { return setTimeout(resolve, timeoutMs); })
+                            ])];
+                    case 1:
+                        _a.sent();
+                        this.connections.clear();
+                        getLogger().info("Closed ".concat(total, " active connections"));
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    ExpressServer.prototype.validateHttpsFiles = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0: return [4 /*yield*/, fileExists(this.config.https.key)];
+                    case 1:
+                        if (!(_b.sent())) {
+                            getLogger().error("HTTPS key file not found: ".concat(this.config.https.key));
+                            process.exit(1);
+                        }
+                        return [4 /*yield*/, fileExists(this.config.https.cert)];
+                    case 2:
+                        if (!(_b.sent())) {
+                            getLogger().error("HTTPS cert file not found: ".concat(this.config.https.cert));
+                            process.exit(1);
+                        }
+                        _a = this.config.https.ca;
+                        if (!_a) return [3 /*break*/, 4];
+                        return [4 /*yield*/, fileExists(this.config.https.ca)];
+                    case 3:
+                        _a = !(_b.sent());
+                        _b.label = 4;
+                    case 4:
+                        if (_a) {
+                            getLogger().error("HTTPS CA file not found: ".concat(this.config.https.ca));
+                            process.exit(1);
+                        }
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    ExpressServer.isBuiltServerConfig = function (config) {
+        if (config[BUILD_MARKER]) {
+            return true;
+        }
+        return false;
+    };
+    ExpressServer.optionalRequire = function (name) {
+        try {
+            return require(name);
+        }
+        catch (_a) {
+            return null;
+        }
+    };
+    return ExpressServer;
+}());
+export { ExpressServer };
+//# sourceMappingURL=server.js.map