@catbee/utils 2.0.3 → 2.0.4

package/server/index.cjs

@@ -305,42 +305,6 @@ var ServerConfigBuilder = class {
     return this.setEnabled("requestLogging", false);
   }
   /**
-  * Configures server metrics collection and endpoints.
-  *
-  * @param opts - Metrics configuration options
-  * @returns The builder instance for chaining
-  * @default - { enable: false, path: '/metrics', withGlobalPrefix: false }
-  *
-  * @example
-  * ```typescript
-  * builder.withMetrics({
-  *   enable: true,
-  *   path: '/metrics'
-  * })
-  * ```
-  */
-  withMetrics(opts) {
-    this.mergeConfig("metrics", opts);
-    return this;
-  }
-  /**
-  * Enables Prometheus metrics collection and endpoint
-  *
-  * @param opts - Optional metrics configuration
-  * @returns The builder instance for chaining
-  */
-  enableMetrics(opts = {}) {
-    return this.setEnabled("metrics", true, opts);
-  }
-  /**
-  * Disables Prometheus metrics
-  *
-  * @returns The builder instance for chaining
-  */
-  disableMetrics() {
-    return this.setEnabled("metrics", false);
-  }
-  /**
   * Configures server health check endpoint.
   *
   * @param opts - Health check configuration options
@@ -360,6 +324,19 @@ var ServerConfigBuilder = class {
     return this;
   }
   /**
+  * Enables health check endpoint with default or custom settings
+  * @param opts - Optional health check configuration
+  * @returns The builder instance for chaining
+  *
+  * @example
+  * ```typescript
+  * builder.disableHealthCheck()
+  * ```
+  */
+  disableHealthCheck() {
+    return this.setEnabled("healthCheck", false);
+  }
+  /**
   * Configures OpenAPI/Swagger documentation for the API.
   *
   * @param opts - OpenAPI configuration options
@@ -370,7 +347,7 @@ var ServerConfigBuilder = class {
   * ```typescript
   * builder.withOpenApi({
   *   enable: true,
-  *   path: '/api-docs',
+  *   mountPath: '/api-docs',
   *   filePath: './openapi.yaml'
   * })
   * ```
@@ -710,15 +687,12 @@ var DependencyErrors = {
   compression: getDependencyErrorMessage("compression"),
   "express-rate-limit": getDependencyErrorMessage("express-rate-limit"),
   "cookie-parser": getDependencyErrorMessage("cookie-parser"),
-  "@scalar/express-api-reference": getDependencyErrorMessage("@scalar/express-api-reference"),
-  "prom-client": getDependencyErrorMessage("prom-client")
+  "@scalar/express-api-reference": getDependencyErrorMessage("@scalar/express-api-reference")
 };
 var ExpressServer = class {
   static {
     __name(this, "ExpressServer");
   }
-  /** Prometheus client registry for metrics collection */
-  register = null;
   /** HTTP server instance (null when not running) */
   server = null;
   /** Merged configuration with defaults applied */
@@ -737,16 +711,13 @@ var ExpressServer = class {
   connections = /* @__PURE__ */ new Set();
   /** Flag indicating if the server is shutting down */
   isShuttingDown = false;
+  /** Flag indicating if graceful shutdown handlers are registered */
+  gracefulShutdownRegistered = false;
   /**
   * Collection of registered health check functions.
   * These are executed when the health check endpoint is accessed.
   */
   healthChecks = [];
-  /** Prometheus metrics for monitoring */
-  requestCounter;
-  routeTimings;
-  requestSizes;
-  clientIPs;
   /** Promise that resolves when initialization (middleware + routes) is complete */
   initPromise;
   /**
@@ -762,7 +733,6 @@ var ExpressServer = class {
   *
   * Default Monitoring:
   * - Request/Response logging
-  * - Prometheus metrics
   * - Health checks
   * - Request tracing
   */
@@ -780,82 +750,6 @@ var ExpressServer = class {
       logger.getLogger().error(msg);
       throw new Error(msg);
     }
-    const safeAppName = (this.config.appName || "express_app").toLowerCase().replace(/[^a-z0-9_]/g, "_");
-    if (this.config.metrics?.enable) {
-      const client = async.optionalRequire("prom-client");
-      if (!client) {
-        this.throwDependancyError("prom-client");
-      }
-      this.register = new client.Registry();
-      this.requestCounter = new client.Counter({
-        name: `${safeAppName}_http_requests_total`,
-        help: "Total HTTP requests",
-        labelNames: [
-          "method",
-          "route",
-          "status"
-        ],
-        registers: [
-          this.register
-        ]
-      });
-      this.routeTimings = new client.Histogram({
-        name: `${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: `${safeAppName}_http_request_size_bytes`,
-        help: "Size of HTTP request bodies",
-        labelNames: [
-          "method",
-          "route"
-        ],
-        buckets: [
-          100,
-          1e3,
-          1e4,
-          1e5,
-          1e6
-        ],
-        registers: [
-          this.register
-        ]
-      });
-      this.clientIPs = new client.Counter({
-        name: `${safeAppName}_http_client_ip_total`,
-        help: "Client IP request counter",
-        labelNames: [
-          "ip",
-          "method"
-        ],
-        registers: [
-          this.register
-        ]
-      });
-      client.collectDefaultMetrics({
-        register: this.register,
-        prefix: `${safeAppName}_`
-      });
-    }
     if (config$1?.healthCheck?.checks) {
       this.healthChecks.push(...config$1.healthCheck.checks);
     }
@@ -928,7 +822,6 @@ var ExpressServer = class {
     this.setupBodyParsingMiddleware();
     this.setupCookieParsingMiddleware();
     await this.setupOpenApiMiddleware();
-    this.setupMetricsMiddleware();
   }
   /**
   * Set up basic middleware (trust proxy, request ID, context).
@@ -951,6 +844,7 @@ var ExpressServer = class {
       if (this.isShuttingDown) {
         res.setHeader("Connection", "close");
         res.status(httpStatusCodes.HttpStatusCodes.SERVICE_UNAVAILABLE).json(new exception.ServiceUnavailableException("Server is shutting down"));
+        return;
       }
       next();
     });
@@ -962,7 +856,7 @@ var ExpressServer = class {
     if (this.config.helmet) {
       const helmet = async.optionalRequire("helmet");
       if (!helmet) {
-        this.throwDependancyError("helmet");
+        this.throwDependencyError("helmet");
       }
       if (typeof this.config.helmet === "object") {
         this.app.use(helmet(this.config.helmet));
@@ -973,7 +867,7 @@ var ExpressServer = class {
     if (this.config.cors) {
       const cors = async.optionalRequire("cors");
       if (!cors) {
-        this.throwDependancyError("cors");
+        this.throwDependencyError("cors");
       }
       this.app.use(cors(this.config.cors === true ? {} : this.config.cors));
     }
@@ -1025,7 +919,7 @@ var ExpressServer = class {
     if (this.config.rateLimit?.enable) {
       const rateLimit = async.optionalRequire("express-rate-limit");
       if (!rateLimit) {
-        this.throwDependancyError("express-rate-limit");
+        this.throwDependencyError("express-rate-limit");
       }
       this.app.use(rateLimit({
         windowMs: this.config.rateLimit.windowMs ?? 15 * 60 * 1e3,
@@ -1074,7 +968,7 @@ var ExpressServer = class {
     if (this.config.compression) {
       const compression = async.optionalRequire("compression");
       if (!compression) {
-        this.throwDependancyError("compression");
+        this.throwDependencyError("compression");
       }
       if (typeof this.config.compression === "object") {
         this.app.use(compression(this.config.compression));
@@ -1130,7 +1024,7 @@ var ExpressServer = class {
     if (this.config.cookieParser) {
       const cookieParser = async.optionalRequire("cookie-parser");
       if (!cookieParser) {
-        this.throwDependancyError("cookie-parser");
+        this.throwDependencyError("cookie-parser");
       }
       if (typeof this.config.cookieParser === "object") {
         this.app.use(cookieParser(void 0, this.config.cookieParser));
@@ -1164,7 +1058,7 @@ var ExpressServer = class {
         }
         const apiReference = async.optionalRequire("@scalar/express-api-reference")?.apiReference;
         if (!apiReference) {
-          this.throwDependancyError("@scalar/express-api-reference", getDependencyErrorMessage("@scalar/express-api-reference", "OpenAPI docs"));
+          this.throwDependencyError("@scalar/express-api-reference", getDependencyErrorMessage("@scalar/express-api-reference", "OpenAPI docs"));
         }
         this.app.use(openApiMountPath, apiReference({
           spec: {
@@ -1185,50 +1079,10 @@ var ExpressServer = class {
     }
   }
   /**
-  * Set up metrics tracking middleware.
-  */
-  setupMetricsMiddleware() {
-    if (this.config.metrics?.enable) {
-      this.app.use((req, res, next) => {
-        const start = process.hrtime();
-        this.clientIPs?.inc({
-          ip: req.ip,
-          method: req.method
-        });
-        const cl = req.headers["content-length"];
-        if (cl) {
-          const size = Number(cl);
-          if (!Number.isNaN(size) && size >= 0) {
-            const route = this.normalizeRouteForMetrics(req, res);
-            this.requestSizes?.observe({
-              method: req.method,
-              route
-            }, size);
-          }
-        }
-        res.once("finish", () => {
-          const [seconds, nanoseconds] = process.hrtime(start);
-          const finalRoute = this.normalizeRouteForMetrics(req, res);
-          this.requestCounter?.inc({
-            method: req.method,
-            route: finalRoute,
-            status: res.statusCode.toString()
-          });
-          this.routeTimings?.observe({
-            method: req.method,
-            route: finalRoute,
-            status: res.statusCode.toString()
-          }, seconds + nanoseconds / 1e9);
-        });
-        next();
-      });
-    }
-  }
-  /**
   * Configure server routes and error handling.
   * Sets up in following order:
   *
-  * 1. Built-in routes (health, metrics)
+  * 1. Built-in routes (health)
   * 2. Application routes
   * 3. 404 handler
   * 4. Error handler
@@ -1238,13 +1092,6 @@ var ExpressServer = class {
     this.app.get(healthCheckPath, async (_req, res) => {
       return this.handleHealthCheckRequest(res);
     });
-    if (this.config.metrics?.enable) {
-      const metricsPath = this.normalizePath(this.config.metrics.path ?? "/metrics", this.config.metrics?.withGlobalPrefix);
-      this.app.get(metricsPath, async (_req, res) => {
-        res.set("Content-Type", this.register.contentType);
-        res.end(await this.register.metrics());
-      });
-    }
     const routerToUse = this.externalRouter || this.rootRouter;
     this.app.use(this.globalPrefix, routerToUse);
     await this.runHook("afterRoutes", this.app);
@@ -1391,6 +1238,10 @@ var ExpressServer = class {
   * @throws Error if server fails to start or port is already in use
   */
   async start() {
+    if (this.server) {
+      logger.getLogger().warn("Server is already running, returning existing instance");
+      return this.server;
+    }
     await this.initPromise;
     await this.runHook("beforeStart", this.app);
     return new Promise((resolve, reject) => {
@@ -1463,12 +1314,9 @@ var ExpressServer = class {
     const host = this.formatHostForUrl(this.config.host || "localhost");
     const url = `${protocol}://${host}:${port}`;
     logger.getLogger().info(`Server running on ${url}`);
-    if (this.config.healthCheck?.path) {
+    if (this.config.healthCheck && this.config.healthCheck?.path) {
       logger.getLogger().info(`Health check available at ${url}${this.normalizePath(this.config.healthCheck.path, this.config.healthCheck.withGlobalPrefix)}`);
     }
-    if (this.config.metrics?.enable && this.config.metrics.path) {
-      logger.getLogger().info(`Metrics available at ${url}${this.normalizePath(this.config.metrics.path, this.config.metrics.withGlobalPrefix)}`);
-    }
     if (this.config.openApi?.enable) {
       logger.getLogger().info(`API docs available at ${url}${this.normalizePath(this.config.openApi.mountPath, this.config.openApi.withGlobalPrefix)}`);
     }
@@ -1495,50 +1343,70 @@ var ExpressServer = class {
       return;
     }
     if (this.isShuttingDown) {
-      logger.getLogger().warn("Stop called while shutdown is already in progress");
+      logger.getLogger().warn("Shutdown already in progress");
       return;
     }
     this.isShuttingDown = true;
     await this.runHook("beforeStop", this.server);
     try {
-      await this.gracefulShutdown();
-    } catch (err) {
-      logger.getLogger().error({
-        err
-      }, "Graceful shutdown timed out");
-      if (force) {
-        logger.getLogger().warn("Forcing connection destroy due to shutdown timeout");
-      }
+      await this.gracefulShutdown(force);
     } finally {
-      await this.destroyConnections();
+      this.isShuttingDown = false;
     }
   }
   /**
   * Perform graceful server shutdown with timeout.
   */
-  async gracefulShutdown() {
+  async gracefulShutdown(force = false) {
     const shutdownTimeout = 1e4;
+    const server = this.server;
+    let timer;
+    let afterStopCalled = false;
+    const runAfterStop = /* @__PURE__ */ __name(async () => {
+      if (afterStopCalled) return;
+      afterStopCalled = true;
+      await this.runHook("afterStop");
+    }, "runAfterStop");
     const serverClosePromise = new Promise((resolve, reject) => {
-      this.server.close(async (err) => {
+      server.close(async (err) => {
+        if (timer) clearTimeout(timer);
         if (err) {
           logger.getLogger().error({
             err
-          }, "Error while closing server");
+          }, "Error during server shutdown");
           reject(err);
           return;
         }
         this.server = null;
-        this.isShuttingDown = false;
         logger.getLogger().info("Server stopped gracefully");
-        await this.runHook("afterStop");
+        await runAfterStop();
         resolve();
       });
     });
-    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Shutdown timeout")), shutdownTimeout));
-    await Promise.race([
-      serverClosePromise,
-      timeoutPromise
-    ]);
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error("Shutdown timeout")), shutdownTimeout);
+    });
+    try {
+      await Promise.race([
+        serverClosePromise,
+        timeoutPromise
+      ]);
+    } catch (err) {
+      if (timer) clearTimeout(timer);
+      logger.getLogger().warn({
+        err
+      }, "Graceful shutdown timed out");
+      if (!force) {
+        throw err;
+      }
+      logger.getLogger().warn("Escalating to forced shutdown");
+      server.closeIdleConnections?.();
+      server.closeAllConnections?.();
+      await this.destroyConnections();
+      this.server = null;
+      logger.getLogger().info("Forced shutdown completed");
+      await runAfterStop();
+    }
   }
   /**
   * Enable graceful shutdown on OS signals for production deployment.
@@ -1555,31 +1423,64 @@ var ExpressServer = class {
     "SIGINT",
     "SIGTERM"
   ]) {
+    if (this.gracefulShutdownRegistered) {
+      logger.getLogger().warn("Graceful shutdown handlers are already registered");
+      return this;
+    }
+    let signalHandled = false;
     signals.forEach((signal) => {
       process.on(signal, async () => {
+        if (signalHandled) {
+          logger.getLogger().warn(`Ignoring duplicate ${signal}`);
+          return;
+        }
+        signalHandled = true;
         logger.getLogger().info(`Received ${signal}, initiating graceful shutdown...`);
         try {
-          await this.stop();
+          await this.stop(true);
           process.exit(0);
         } catch (err) {
-          logger.getLogger().error({
+          logger.getLogger().fatal({
             err
-          }, "Error during graceful shutdown, forcing stop...");
-          try {
-            await this.stop(true);
-            process.exit(1);
-          } catch (forceError) {
-            logger.getLogger().fatal({
-              forceError
-            }, "Forced shutdown failed, exiting hard");
-            process.exit(1);
-          }
+          }, "Shutdown failed");
+          process.exit(1);
         }
       });
     });
+    this.gracefulShutdownRegistered = true;
     return this;
   }
   /**
+  * Destroy all active connections (gracefully if possible).
+  * If a connection does not close cleanly, it will be force-destroyed.
+  */
+  async destroyConnections() {
+    if (!this.connections.size) {
+      return;
+    }
+    const sockets = [
+      ...this.connections
+    ];
+    await Promise.allSettled(sockets.map((socket) => new Promise((resolve) => {
+      socket.end();
+      const timer = setTimeout(() => {
+        socket.destroy();
+        resolve();
+      }, 1e3);
+      socket.once("close", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      socket.once("error", () => {
+        clearTimeout(timer);
+        socket.destroy();
+        resolve();
+      });
+    })));
+    this.connections.clear();
+    logger.getLogger().info(`Closed ${sockets.length} active connection(s)`);
+  }
+  /**
   * Set an externally created base router.
   * This will override the internal rootRouter.
   */
@@ -1607,14 +1508,15 @@ var ExpressServer = class {
   */
   registerRoute(methods, path, ...handlers) {
     const fullPath = this.normalizePath(path, true);
+    const routerToUse = this.externalRouter || this.rootRouter;
     const 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)
+      get: routerToUse.get.bind(routerToUse),
+      post: routerToUse.post.bind(routerToUse),
+      put: routerToUse.put.bind(routerToUse),
+      delete: routerToUse.delete.bind(routerToUse),
+      patch: routerToUse.patch.bind(routerToUse),
+      options: routerToUse.options.bind(routerToUse),
+      head: routerToUse.head.bind(routerToUse)
     };
     methods.forEach((m) => {
       const fn = methodMap[m];
@@ -1640,15 +1542,16 @@ var ExpressServer = class {
   * @returns This instance for method chaining
   */
   registerMiddleware(path, middleware) {
+    const routerToUse = this.externalRouter || this.rootRouter;
     if (typeof path === "string") {
       const normalizedPath = this.normalizePath(path);
       if (normalizedPath) {
-        this.app.use(normalizedPath, middleware);
+        routerToUse.use(normalizedPath, middleware);
       } else {
-        this.app.use(middleware);
+        routerToUse.use(middleware);
       }
     } else {
-      this.app.use(path);
+      routerToUse.use(path);
     }
     return this;
   }
@@ -1662,22 +1565,11 @@ var ExpressServer = class {
   */
   useMiddleware(...middlewares) {
     middlewares.forEach((middleware) => {
-      this.app.use(middleware);
+      (this.externalRouter || this.rootRouter).use(middleware);
     });
     return this;
   }
   /**
-  * Get Prometheus registry (to add custom counters/histograms)
-  *
-  * @return {*}  {client.Registry}
-  */
-  getMetricsRegistry() {
-    if (!this.config.metrics?.enable) {
-      logger.getLogger().warn("Metrics are not enabled in the server configuration \nPlease enable metrics to use this feature.");
-    }
-    return this.register;
-  }
-  /**
   * Get server configuration
   *
   * @return {*}  {CatbeeServerConfig}
@@ -1826,41 +1718,6 @@ var ExpressServer = class {
     }
     return sanitize(prefix + "/" + path);
   }
-  normalizeRouteForMetrics(req, res) {
-    if (req?.route?.path) {
-      return req.route.path;
-    }
-    if (res.statusCode === 404) return "/404";
-    const path = (req.path || "unknown").split("?")[0];
-    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.
-  */
-  async destroyConnections() {
-    const total = this.connections.size;
-    if (total === 0) {
-      logger.getLogger().debug("No active connections to close");
-      return;
-    }
-    const timeoutMs = 5e3;
-    await Promise.race([
-      Promise.all(Array.from(this.connections).map((conn) => new Promise((resolve) => {
-        conn.end(() => {
-          if (!conn.destroyed) conn.destroy();
-          resolve();
-        });
-        conn.on("error", () => {
-          conn.destroy();
-          resolve();
-        });
-      }))),
-      new Promise((resolve) => setTimeout(resolve, timeoutMs))
-    ]);
-    this.connections.clear();
-    logger.getLogger().info(`Closed ${total} active connections`);
-  }
   async validateHttpsFiles() {
     if (!await fs.fileExists(this.config.https.key)) {
       const msg = `HTTPS key file not found: ${this.config.https.key}`;
@@ -1884,7 +1741,7 @@ var ExpressServer = class {
     }
     return false;
   }
-  throwDependancyError(packageName, msg) {
+  throwDependencyError(packageName, msg) {
     logger.getLogger().error({
       command: `npm install ${packageName}`
     }, msg || DependencyErrors[packageName]);