@moreapp/common-nodejs 0.12.7 → 0.13.1

package/dist/observability/TerminationHandler.d.ts

@@ -3,9 +3,11 @@ import ExpressRequestTracker from "./ExpressRequestTracker";
 import ObservabilityServer from "./ObservabilityServer";
 export default class TerminationHandler {
     private readonly server;
-    private readonly hs;
+    private readonly observabilityServer;
     private readonly requestTracker;
+    private readonly onTermination;
     private readonly sockets;
-    constructor(server: Server, hs: ObservabilityServer, requestTracker: ExpressRequestTracker);
+    private isShuttingDown;
+    constructor(server: Server, observabilityServer: ObservabilityServer, requestTracker: ExpressRequestTracker, onTermination?: () => Promise<void>);
     shutdown(): void;
 }

package/dist/observability/TerminationHandler.js

@@ -10,13 +10,16 @@ const TERMINATION_SIGNALS = ["SIGTERM", "SIGHUP", "SIGINT"];
 const SHUTDOWN_TIMEOUT = 30_000;
 class TerminationHandler {
     server;
-    hs;
+    observabilityServer;
     requestTracker;
+    onTermination;
     sockets = new Set();
-    constructor(server, hs, requestTracker) {
+    isShuttingDown = false;
+    constructor(server, observabilityServer, requestTracker, onTermination = () => Promise.resolve()) {
         this.server = server;
-        this.hs = hs;
+        this.observabilityServer = observabilityServer;
         this.requestTracker = requestTracker;
+        this.onTermination = onTermination;
         for (const signal of TERMINATION_SIGNALS) {
             process.on(signal, () => {
                 logger_1.logger.info("Received termination signal", { signal });
@@ -27,21 +30,35 @@ class TerminationHandler {
             this.sockets.add(socket);
             socket.on("close", () => this.sockets.delete(socket));
         });
+        // Handles errors like `EADDRINUSE`
+        server.on("error", (err) => {
+            logger_1.logger.error("Server threw an unrecoverable error, shutting down", err);
+            this.shutdown();
+        });
     }
     shutdown() {
-        this.hs.setReady(false);
+        if (this.isShuttingDown) {
+            return;
+        }
+        this.isShuttingDown = true;
+        this.observabilityServer.setReady(false);
         logger_1.logger.info("Stopping server");
         this.server.close();
         const interval = (0, node_timers_1.setInterval)(() => {
             const activeRequests = this.requestTracker.nrOfActiveRequests();
             if (activeRequests === 0) {
-                (0, node_timers_1.clearInterval)(interval);
-                // Destroy any remaining sockets
-                this.sockets.forEach((socket) => socket.destroy());
-                void Promise.all([this.hs.stop(), tracer_1.default.shutdown()]).finally(() => {
-                    logger_1.logger.info("Server stopped");
-                    process.exit(0);
-                });
+                void (async () => {
+                    (0, node_timers_1.clearInterval)(interval);
+                    // Destroy any remaining sockets
+                    this.sockets.forEach((socket) => socket.destroy());
+                    await this.onTermination().catch((err) => logger_1.logger.error("Error occurred in termination handler", err));
+                    void Promise.all([this.observabilityServer.stop(), tracer_1.default.shutdown()])
+                        .catch((err) => logger_1.logger.error("Error occurred during shutdown", err))
+                        .finally(() => {
+                        logger_1.logger.info("Server stopped");
+                        process.exit(0);
+                    });
+                })();
             }
             else {
                 logger_1.logger.info("Waiting for requests to finish", { activeRequests });

package/dist/observability/__tests__/ObservabilityServer.test.js

@@ -66,6 +66,7 @@ vitest_1.vi.mock("../../logger", () => ({
             nrOfActiveRequests: vitest_1.vi.fn(() => 0),
         };
         const hs = await ObservabilityServer_1.default.create(requestTracker, { port: 0 });
+        // eslint-disable-next-line @typescript-eslint/unbound-method
         (0, vitest_1.expect)(fakeServer.listen).toHaveBeenCalled();
         // /live
         const resLive = createRes();
@@ -97,6 +98,7 @@ vitest_1.vi.mock("../../logger", () => ({
         capturedHandler({ url: "/unknown" }, res404);
         (0, vitest_1.expect)(res404.statusCode).toBe(404);
         await hs.stop();
+        // eslint-disable-next-line @typescript-eslint/unbound-method
         (0, vitest_1.expect)(fakeServer.close).toHaveBeenCalled();
         createServerSpy.mockRestore();
     });

package/dist/observability/__tests__/TerminationHandler.test.js

@@ -40,6 +40,7 @@ const vitest_1 = require("vitest");
 const node_events_1 = require("node:events");
 const timers = __importStar(require("node:timers"));
 const TerminationHandler_1 = __importDefault(require("../TerminationHandler"));
+const logger_1 = require("../../logger");
 vitest_1.vi.mock("../../logger", () => ({
     logger: {
         info: vitest_1.vi.fn(),
@@ -112,15 +113,13 @@ vitest_1.vi.mock("node:timers", () => ({
         const th = new TerminationHandler_1.default(server, hs, requestTracker);
         th.shutdown();
         (0, vitest_1.expect)(hs.setReady).toHaveBeenCalledWith(false);
+        // eslint-disable-next-line @typescript-eslint/unbound-method
         (0, vitest_1.expect)(server.close).toHaveBeenCalled();
         // First interval tick should see 0 active and exit
         intervalCb?.();
-        // ensure hs.stop called
-        (0, vitest_1.expect)(hs.stop).toHaveBeenCalled();
-        // Wait for Promise.all and .finally() to execute
+        // Wait for the async IIFE (await onTermination + Promise.all().finally()) to settle
         await new Promise((resolve) => setImmediate(resolve));
-        // Trigger log flush timeout (index 1, after the 30s timeout at index 0)
-        timeoutCallbacks[1]?.();
+        (0, vitest_1.expect)(hs.stop).toHaveBeenCalled();
         (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(0);
     });
     (0, vitest_1.test)("shutdown polls until requests finish then exits 0", async () => {
@@ -140,11 +139,9 @@ vitest_1.vi.mock("node:timers", () => ({
         (0, vitest_1.expect)(exitSpy).not.toHaveBeenCalled();
         // Second tick: now 0
         intervalCb?.();
-        (0, vitest_1.expect)(hs.stop).toHaveBeenCalled();
-        // Wait for Promise.all and .finally() to execute
+        // Wait for the async IIFE (await onTermination + Promise.all().finally()) to settle
         await new Promise((resolve) => setImmediate(resolve));
-        // Trigger log flush timeout (index 1, after the 30s timeout at index 0)
-        timeoutCallbacks[1]?.();
+        (0, vitest_1.expect)(hs.stop).toHaveBeenCalled();
         (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(0);
     });
     (0, vitest_1.test)("forceful stop after 30s destroys sockets and exits 1", () => {
@@ -162,10 +159,81 @@ vitest_1.vi.mock("node:timers", () => ({
         th.shutdown();
         // Before timeout callback, no exit
         (0, vitest_1.expect)(exitSpy).not.toHaveBeenCalled();
+        // eslint-disable-next-line @typescript-eslint/unbound-method
         (0, vitest_1.expect)(socket.destroy).not.toHaveBeenCalled();
         // Trigger shutdown timeout (index 0 is the 30s timeout)
         timeoutCallbacks[0]?.();
+        // eslint-disable-next-line @typescript-eslint/unbound-method
         (0, vitest_1.expect)(socket.destroy).toHaveBeenCalled();
         (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(1);
     });
+    (0, vitest_1.test)("invokes onTermination during graceful shutdown then exits 0", async () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: vitest_1.vi.fn(),
+            stop: vitest_1.vi.fn(() => Promise.resolve()),
+        };
+        const requestTracker = { nrOfActiveRequests: vitest_1.vi.fn(() => 0) };
+        const onTermination = vitest_1.vi.fn(() => Promise.resolve());
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => undefined);
+        new TerminationHandler_1.default(server, hs, requestTracker, onTermination).shutdown();
+        // First interval tick sees 0 active and runs the graceful path
+        intervalCb?.();
+        // Wait for the async IIFE (await onTermination + Promise.all().finally()) to settle
+        await new Promise((resolve) => setImmediate(resolve));
+        (0, vitest_1.expect)(onTermination).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(0);
+    });
+    (0, vitest_1.test)("catches and logs onTermination rejection but still exits 0", async () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: vitest_1.vi.fn(),
+            stop: vitest_1.vi.fn(() => Promise.resolve()),
+        };
+        const requestTracker = { nrOfActiveRequests: vitest_1.vi.fn(() => 0) };
+        const onTermination = vitest_1.vi.fn(() => Promise.reject(new Error("boom")));
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => undefined);
+        new TerminationHandler_1.default(server, hs, requestTracker, onTermination).shutdown();
+        intervalCb?.();
+        await new Promise((resolve) => setImmediate(resolve));
+        (0, vitest_1.expect)(vitest_1.vi.mocked(logger_1.logger.error)).toHaveBeenCalledWith("Error occurred in termination handler", vitest_1.expect.any(Error));
+        // A failing hook must not divert to the forceful exit-1 path
+        (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(0);
+    });
+    (0, vitest_1.test)("shuts down when the server emits an error", async () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: vitest_1.vi.fn(),
+            stop: vitest_1.vi.fn(() => Promise.resolve()),
+        };
+        const requestTracker = { nrOfActiveRequests: vitest_1.vi.fn(() => 0) };
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation(() => undefined);
+        new TerminationHandler_1.default(server, hs, requestTracker);
+        // e.g. EADDRINUSE surfaces as a server "error" event
+        server.emit("error", new Error("EADDRINUSE"));
+        (0, vitest_1.expect)(vitest_1.vi.mocked(logger_1.logger.error)).toHaveBeenCalledWith("Server threw an unrecoverable error, shutting down", vitest_1.expect.any(Error));
+        (0, vitest_1.expect)(hs.setReady).toHaveBeenCalledWith(false);
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        (0, vitest_1.expect)(server.close).toHaveBeenCalled();
+        intervalCb?.();
+        await new Promise((resolve) => setImmediate(resolve));
+        (0, vitest_1.expect)(exitSpy).toHaveBeenCalledWith(0);
+    });
+    (0, vitest_1.test)("ignores a second shutdown call", () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: vitest_1.vi.fn(),
+            stop: vitest_1.vi.fn(() => Promise.resolve()),
+        };
+        // Never reaches 0 so the poll loop stays active between the two calls
+        const requestTracker = { nrOfActiveRequests: vitest_1.vi.fn(() => 5) };
+        vitest_1.vi.spyOn(process, "exit").mockImplementation(() => undefined);
+        const th = new TerminationHandler_1.default(server, hs, requestTracker);
+        th.shutdown();
+        th.shutdown();
+        (0, vitest_1.expect)(hs.setReady).toHaveBeenCalledTimes(1);
+        // eslint-disable-next-line @typescript-eslint/unbound-method
+        (0, vitest_1.expect)(server.close).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(vitest_1.vi.mocked(timers.setInterval)).toHaveBeenCalledTimes(1);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moreapp/common-nodejs",
-  "version": "0.12.7",
+  "version": "0.13.1",
   "license": "UNLICENSED",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,19 +30,19 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/core": "2.8.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "0.219.0",
-    "@opentelemetry/instrumentation": "0.219.0",
-    "@opentelemetry/instrumentation-dns": "0.62.0",
-    "@opentelemetry/instrumentation-express": "0.67.0",
-    "@opentelemetry/instrumentation-http": "0.219.0",
-    "@opentelemetry/instrumentation-winston": "0.63.0",
-    "@opentelemetry/resources": "2.8.0",
-    "@opentelemetry/sdk-node": "0.219.0",
-    "@opentelemetry/sdk-trace-base": "2.8.0",
-    "@opentelemetry/sdk-trace-node": "2.8.0",
-    "@opentelemetry/semantic-conventions": "1.41.1",
-    "axios": "1.18.1",
+    "@opentelemetry/core": "2.10.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
+    "@opentelemetry/instrumentation": "0.221.0",
+    "@opentelemetry/instrumentation-dns": "0.64.0",
+    "@opentelemetry/instrumentation-express": "0.69.0",
+    "@opentelemetry/instrumentation-http": "0.221.0",
+    "@opentelemetry/instrumentation-winston": "0.65.0",
+    "@opentelemetry/resources": "2.10.0",
+    "@opentelemetry/sdk-node": "0.221.0",
+    "@opentelemetry/sdk-trace-base": "2.10.0",
+    "@opentelemetry/sdk-trace-node": "2.10.0",
+    "@opentelemetry/semantic-conventions": "1.43.0",
+    "axios": "1.19.0",
     "content-disposition-parser": "1.0.2",
     "date-and-time": "4.5.1",
     "express": "5.2.1",
@@ -53,24 +53,24 @@
   },
   "devDependencies": {
     "@types/express": "5.0.6",
-    "@types/lodash": "4.17.24",
-    "@types/node": "24.13.2",
-    "@typescript-eslint/eslint-plugin": "8.61.1",
-    "@typescript-eslint/parser": "8.61.1",
-    "@vitest/coverage-v8": "4.1.9",
-    "@vitest/ui": "4.1.9",
-    "eslint": "9.39.4",
+    "@types/lodash": "4.17.25",
+    "@types/node": "24.13.3",
+    "@typescript-eslint/eslint-plugin": "8.67.0",
+    "@typescript-eslint/parser": "8.67.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "@vitest/ui": "4.1.10",
+    "eslint": "9.39.5",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-prettier": "5.5.6",
     "husky": "9.1.7",
-    "lint-staged": "17.0.8",
-    "nock": "14.0.16",
-    "prettier": "3.8.5",
+    "lint-staged": "17.3.0",
+    "nock": "14.0.17",
+    "prettier": "3.9.6",
     "ts-node": "10.9.2",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.61.1",
-    "vitest": "4.1.9",
-    "vitest-mock-extended": "4.0.0"
+    "typescript-eslint": "8.67.0",
+    "vitest": "4.1.10",
+    "vitest-mock-extended": "5.1.1"
   },
   "prettier": {
     "printWidth": 100,