@moreapp/common-nodejs 0.8.1 → 0.9.1

package/README.md

@@ -8,27 +8,7 @@ Run `yarn prepare` once to install Git hooks, doing lints and prettier formattin
 
 ## Project usage
 
-Most code can be used as is, except for tracing, see below.
-
-### Tracing
-
-Tracing code should always be loaded (`import`/`require`) first, before any other libraries. This is because the
-OpenTelemetry instrumentations monkey patch libraries to add tracing. Patching has to happen first, because already
-loaded libraries will be cached by the module system.
-
-The recommended way to do this, is to create a file `instrumentation.ts` with the following content (the extra
-instrumentation is there as an example):
-
-```
-import { tracer } from "@moreapp/common-nodejs";
-import { MongoDBInstrumentation } from "@opentelemetry/instrumentation-mongodb";
-
-tracer("<SERVICE_NAME>", {
-  extraInstrumentations: [new MongoDBInstrumentation()],
-});
-```
-
-And then use the `--require` [Node.js CLI option](https://nodejs.org/api/cli.html#-r---require-module) to load this file.
+Most code can be used as is. See [service configuration](./docs/service-configuration.md) for code that needs more setup.
 
 ## Creating a new release
 

package/dist/dateUtil.js

@@ -22,9 +22,9 @@ function formatDate(dateString, format) {
 exports.formatDate = formatDate;
 function formatDateTime(dateTime, format) {
     const date = typeof dateTime === "string"
-        ? date_and_time_1.default.parse(dateTime, "YYYY-MM-DD HH:mm", true)
+        ? date_and_time_1.default.parse(dateTime, "YYYY-MM-DD HH:mm", { timeZone: "UTC" })
         : new Date(dateTime);
-    return date_and_time_1.default.format(date, formatDateFormat(format) + " HH:mm", true);
+    return date_and_time_1.default.format(date, formatDateFormat(format) + " HH:mm", { timeZone: "UTC" });
 }
 exports.formatDateTime = formatDateTime;
 function formatDateFormat(format) {

package/dist/index.d.ts

@@ -5,5 +5,6 @@ export * from "./tracer";
 export * from "./logger";
 export * from "./dateUtil";
 export * from "./utils";
+export * from "./k8s";
 export { BinaryFile } from "./MoreAppClient";
 export { MoreAppClient };

package/dist/index.js

@@ -26,3 +26,4 @@ __exportStar(require("./tracer"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./dateUtil"), exports);
 __exportStar(require("./utils"), exports);
+__exportStar(require("./k8s"), exports);

package/dist/k8s/ExpressRequestTracker.d.ts

@@ -0,0 +1,6 @@
+import { NextFunction, Request, Response } from "express";
+export default class ExpressRequestTracker {
+    private activeRequests;
+    track(): (_req: Request, res: Response, next: NextFunction) => void;
+    nrOfActiveRequests(): number;
+}

package/dist/k8s/ExpressRequestTracker.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class ExpressRequestTracker {
+    activeRequests = 0;
+    track() {
+        return (_req, res, next) => {
+            this.activeRequests++;
+            res.on("finish", () => {
+                this.activeRequests--;
+            });
+            next();
+        };
+    }
+    nrOfActiveRequests() {
+        return this.activeRequests;
+    }
+}
+exports.default = ExpressRequestTracker;

package/dist/k8s/ExpressRequestTracker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/k8s/ExpressRequestTracker.test.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ExpressRequestTracker_1 = __importDefault(require("./ExpressRequestTracker"));
+const node_events_1 = require("node:events");
+// Create a minimal Response mock that can emit the 'finish' event
+const createMockResponse = () => {
+    const emitter = new node_events_1.EventEmitter();
+    return Object.assign(emitter, {
+        emitFinish: () => emitter.emit("finish"),
+    });
+};
+describe("ExpressRequestTracker", () => {
+    test("increments active requests on middleware entry and calls next", () => {
+        const tracker = new ExpressRequestTracker_1.default();
+        const middleware = tracker.track();
+        const res = createMockResponse();
+        const next = jest.fn();
+        expect(tracker.nrOfActiveRequests()).toBe(0);
+        middleware({}, res, next);
+        expect(tracker.nrOfActiveRequests()).toBe(1);
+        expect(next).toHaveBeenCalledTimes(1);
+        // Finish should decrement
+        res.emitFinish();
+        expect(tracker.nrOfActiveRequests()).toBe(0);
+    });
+    test("decrements active requests when response finishes", () => {
+        const tracker = new ExpressRequestTracker_1.default();
+        const middleware = tracker.track();
+        const res = createMockResponse();
+        middleware({}, res, (() => { }));
+        expect(tracker.nrOfActiveRequests()).toBe(1);
+        res.emitFinish();
+        expect(tracker.nrOfActiveRequests()).toBe(0);
+    });
+    test("tracks multiple concurrent requests and decrements in order", () => {
+        const tracker = new ExpressRequestTracker_1.default();
+        const middleware = tracker.track();
+        const res1 = createMockResponse();
+        const res2 = createMockResponse();
+        middleware({}, res1, (() => { }));
+        middleware({}, res2, (() => { }));
+        expect(tracker.nrOfActiveRequests()).toBe(2);
+        // Finish the first request
+        res1.emitFinish();
+        expect(tracker.nrOfActiveRequests()).toBe(1);
+        // Finish the second request
+        res2.emitFinish();
+        expect(tracker.nrOfActiveRequests()).toBe(0);
+    });
+});

package/dist/k8s/HealthServer.d.ts

@@ -0,0 +1,17 @@
+import ExpressRequestTracker from "./ExpressRequestTracker";
+type HealthServerOptions = {
+    port: number;
+};
+export default class HealthServer {
+    private readonly requestTracker;
+    private readonly options;
+    private readonly server;
+    private status;
+    private isReady;
+    private constructor();
+    static create(requestTracker: ExpressRequestTracker, options: HealthServerOptions): Promise<HealthServer>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    setReady(value: boolean): void;
+}
+export {};

package/dist/k8s/HealthServer.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_http_1 = __importDefault(require("node:http"));
+const logger_1 = require("../logger");
+class HealthServer {
+    requestTracker;
+    options;
+    server;
+    status = "stopped";
+    isReady = false;
+    constructor(requestTracker, options) {
+        this.requestTracker = requestTracker;
+        this.options = options;
+        this.server = node_http_1.default.createServer((req, res) => {
+            if (req.url === "/live") {
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ status: "ok" }));
+            }
+            else if (req.url === "/ready") {
+                res.writeHead(this.isReady ? 200 : 503, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({
+                    status: this.isReady ? "ok" : "not ready",
+                    activeRequests: this.requestTracker.nrOfActiveRequests(),
+                }));
+            }
+            else {
+                res.statusCode = 404;
+                return res.end();
+            }
+        });
+    }
+    static async create(requestTracker, options) {
+        const hs = new HealthServer(requestTracker, options);
+        await hs.start();
+        return hs;
+    }
+    start() {
+        if (this.status !== "stopped") {
+            logger_1.logger.info("Cannot start Health server, due to invalid status", { status: this.status });
+            return Promise.resolve();
+        }
+        this.status = "starting";
+        return new Promise((resolve) => {
+            this.server.listen(this.options.port, () => {
+                this.status = "started";
+                logger_1.logger.info("Started Health server");
+                resolve();
+            });
+        });
+    }
+    stop() {
+        if (this.status !== "started") {
+            logger_1.logger.warn("Cannot stop Health server, due to invalid status", { status: this.status });
+            return Promise.reject(new Error("Health server not started"));
+        }
+        this.status = "stopping";
+        this.isReady = false;
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+    setReady(value) {
+        this.isReady = value;
+    }
+}
+exports.default = HealthServer;

package/dist/k8s/HealthServer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/k8s/HealthServer.test.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const testUtils_1 = require("../testUtils");
+(0, testUtils_1.silenceLogger)();
+const node_http_1 = __importDefault(require("node:http"));
+const node_events_1 = require("node:events");
+const HealthServer_1 = __importDefault(require("./HealthServer"));
+describe("HealthServer", () => {
+    const createFakeServer = () => {
+        const emitter = new node_events_1.EventEmitter();
+        const server = {
+            listen: jest.fn((...args) => {
+                const cb = args.find((a) => typeof a === "function");
+                if (cb)
+                    cb();
+                return server;
+            }),
+            close: jest.fn((cb) => {
+                if (cb)
+                    cb();
+                return server;
+            }),
+            on: jest.fn((event, listener) => {
+                emitter.on(event, listener);
+                return server;
+            }),
+            emit: emitter.emit.bind(emitter),
+        };
+        return server;
+    };
+    const createRes = () => {
+        const res = {
+            statusCode: 200,
+            headers: {},
+            writeHead: function (code, headers) {
+                this.statusCode = code;
+                this.headers = headers;
+            },
+            end: function (body) {
+                this.body = body;
+            },
+        };
+        return res;
+    };
+    test("handles /live and /ready endpoints and start/stop lifecycle", async () => {
+        const fakeServer = createFakeServer();
+        // Capture handler passed to createServer
+        let capturedHandler;
+        const createServerSpy = jest
+            .spyOn(node_http_1.default, "createServer")
+            // @ts-expect-error simplify handler typing for test
+            .mockImplementation((handler) => {
+            capturedHandler = handler;
+            return fakeServer;
+        });
+        const requestTracker = { nrOfActiveRequests: jest.fn(() => 0) };
+        const hs = await HealthServer_1.default.create(requestTracker, { port: 0 });
+        expect(fakeServer.listen).toHaveBeenCalled();
+        // /live
+        const resLive = createRes();
+        capturedHandler({ url: "/live" }, resLive);
+        expect(resLive.statusCode).toBe(200);
+        expect(resLive.headers).toEqual({ "Content-Type": "application/json" });
+        expect(JSON.parse(resLive.body)).toEqual({ status: "ok" });
+        // /ready when not ready
+        const resReady1 = createRes();
+        capturedHandler({ url: "/ready" }, resReady1);
+        expect(resReady1.statusCode).toBe(503);
+        expect(JSON.parse(resReady1.body)).toEqual({
+            status: "not ready",
+            activeRequests: 0,
+        });
+        // Now mark ready and simulate active requests
+        requestTracker.nrOfActiveRequests.mockReturnValue(3);
+        hs.setReady(true);
+        const resReady2 = createRes();
+        capturedHandler({ url: "/ready" }, resReady2);
+        expect(resReady2.statusCode).toBe(200);
+        expect(JSON.parse(resReady2.body)).toEqual({
+            status: "ok",
+            activeRequests: 3,
+        });
+        // unknown route
+        const res404 = createRes();
+        capturedHandler({ url: "/unknown" }, res404);
+        expect(res404.statusCode).toBe(404);
+        await hs.stop();
+        expect(fakeServer.close).toHaveBeenCalled();
+        createServerSpy.mockRestore();
+    });
+});

package/dist/k8s/TerminationHandler.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="node" />
+import ExpressRequestTracker from "./ExpressRequestTracker";
+import HealthServer from "./HealthServer";
+import { Server } from "node:http";
+export default class TerminationHandler {
+    private readonly server;
+    private readonly hs;
+    private readonly requestTracker;
+    private readonly sockets;
+    constructor(server: Server, hs: HealthServer, requestTracker: ExpressRequestTracker);
+    shutdown(): void;
+}

package/dist/k8s/TerminationHandler.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const logger_1 = require("../logger");
+const node_timers_1 = require("node:timers");
+const TERMINATION_SIGNALS = ["SIGTERM", "SIGHUP", "SIGINT"];
+const SHUTDOWN_TIMEOUT = 30_000;
+class TerminationHandler {
+    server;
+    hs;
+    requestTracker;
+    sockets = new Set();
+    constructor(server, hs, requestTracker) {
+        this.server = server;
+        this.hs = hs;
+        this.requestTracker = requestTracker;
+        for (const signal of TERMINATION_SIGNALS) {
+            process.on(signal, () => {
+                logger_1.logger.info("Received termination signal", { signal });
+                this.shutdown();
+            });
+        }
+        server.on("connection", (socket) => {
+            this.sockets.add(socket);
+            socket.on("close", () => this.sockets.delete(socket));
+        });
+    }
+    shutdown() {
+        this.hs.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());
+                this.hs.stop().finally(() => {
+                    logger_1.logger.info("Server stopped");
+                    process.exit(0);
+                });
+            }
+            else {
+                logger_1.logger.info("Waiting for requests to finish", { activeRequests });
+            }
+        }, 1_000);
+        setTimeout(() => {
+            logger_1.logger.info("Server forcefully stopped due to timeout");
+            this.sockets.forEach((socket) => socket.destroy());
+            process.exit(1);
+        }, SHUTDOWN_TIMEOUT);
+    }
+}
+exports.default = TerminationHandler;

package/dist/k8s/TerminationHandler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/k8s/TerminationHandler.test.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const testUtils_1 = require("../testUtils");
+(0, testUtils_1.silenceLogger)();
+const node_events_1 = require("node:events");
+// Mock node:timers so we can control callbacks (TerminationHandler imports from node:timers)
+jest.mock("node:timers", () => ({
+    setInterval: jest.fn(),
+    clearInterval: jest.fn(),
+    setTimeout: jest.fn(),
+}));
+const timers = __importStar(require("node:timers"));
+const TerminationHandler_1 = __importDefault(require("./TerminationHandler"));
+describe("TerminationHandler", () => {
+    let intervalCb;
+    let timeoutCb;
+    beforeEach(() => {
+        intervalCb = undefined;
+        timeoutCb = undefined;
+        timers.setInterval.mockImplementation((cb) => {
+            intervalCb = cb;
+            return 1;
+        });
+        timers.clearInterval.mockImplementation(() => { });
+        jest
+            .spyOn(globalThis, "setTimeout")
+            // @ts-ignore simplify types for test
+            .mockImplementation((cb) => {
+            timeoutCb = cb;
+            return 2;
+        });
+    });
+    afterEach(() => {
+        jest.resetAllMocks();
+    });
+    const createFakeServer = () => {
+        const emitter = new node_events_1.EventEmitter();
+        const server = {
+            close: jest.fn((cb) => {
+                if (cb)
+                    cb();
+                return server;
+            }),
+            on: jest.fn((event, listener) => {
+                emitter.on(event, listener);
+                return server;
+            }),
+            emit: emitter.emit.bind(emitter),
+        };
+        return server;
+    };
+    const createSocket = () => {
+        const emitter = new node_events_1.EventEmitter();
+        const socket = emitter;
+        socket.destroy = jest.fn();
+        return socket;
+    };
+    test("shutdown waits for active requests to reach 0 then stops and exits 0", async () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: jest.fn(),
+            stop: jest.fn(() => ({
+                finally: (cb) => {
+                    cb();
+                    return Promise.resolve();
+                },
+            })),
+        };
+        const requestTracker = { nrOfActiveRequests: jest.fn(() => 0) };
+        const exitSpy = jest
+            .spyOn(process, "exit")
+            // never return to process
+            .mockImplementation(((..._args) => undefined));
+        const th = new TerminationHandler_1.default(server, hs, requestTracker);
+        th.shutdown();
+        expect(hs.setReady).toHaveBeenCalledWith(false);
+        expect(server.close).toHaveBeenCalled();
+        // First interval tick should see 0 active and exit
+        intervalCb?.();
+        // ensure hs.stop called and exit called with 0
+        expect(hs.stop).toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+    test("shutdown polls until requests finish then exits 0", async () => {
+        const server = createFakeServer();
+        const hs = {
+            setReady: jest.fn(),
+            stop: jest.fn(() => ({
+                finally: (cb) => {
+                    cb();
+                    return Promise.resolve();
+                },
+            })),
+        };
+        const requestTracker = { nrOfActiveRequests: jest.fn() };
+        // Return >0 first, then 0
+        requestTracker.nrOfActiveRequests.mockReturnValueOnce(2).mockReturnValueOnce(0);
+        const exitSpy = jest
+            .spyOn(process, "exit")
+            .mockImplementation(((..._args) => undefined));
+        const th = new TerminationHandler_1.default(server, hs, requestTracker);
+        th.shutdown();
+        // First tick: still waiting
+        intervalCb?.();
+        expect(exitSpy).not.toHaveBeenCalled();
+        // Second tick: now 0
+        intervalCb?.();
+        expect(hs.stop).toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(0);
+    });
+    test("forceful stop after 30s destroys sockets and exits 1", () => {
+        const server = createFakeServer();
+        const hs = { setReady: jest.fn(), stop: jest.fn(() => Promise.resolve()) };
+        const requestTracker = { nrOfActiveRequests: jest.fn(() => 5) }; // never reaches 0
+        const exitSpy = jest
+            .spyOn(process, "exit")
+            .mockImplementation(((..._args) => undefined));
+        const th = new TerminationHandler_1.default(server, hs, requestTracker);
+        // Register a socket via the server's connection event
+        const socket = createSocket();
+        server.emit("connection", socket);
+        th.shutdown();
+        // Before timeout callback, no exit
+        expect(exitSpy).not.toHaveBeenCalled();
+        expect(socket.destroy).not.toHaveBeenCalled();
+        // Trigger timeout
+        timeoutCb?.();
+        expect(socket.destroy).toHaveBeenCalled();
+        expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+});

package/dist/k8s/index.d.ts

@@ -0,0 +1,4 @@
+import ExpressRequestTracker from "./ExpressRequestTracker";
+import HealthServer from "./HealthServer";
+import TerminationHandler from "./TerminationHandler";
+export { ExpressRequestTracker, HealthServer, TerminationHandler };

package/dist/k8s/index.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TerminationHandler = exports.HealthServer = exports.ExpressRequestTracker = void 0;
+const ExpressRequestTracker_1 = __importDefault(require("./ExpressRequestTracker"));
+exports.ExpressRequestTracker = ExpressRequestTracker_1.default;
+const HealthServer_1 = __importDefault(require("./HealthServer"));
+exports.HealthServer = HealthServer_1.default;
+const TerminationHandler_1 = __importDefault(require("./TerminationHandler"));
+exports.TerminationHandler = TerminationHandler_1.default;

package/dist/testUtils.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="jest" />
+export declare const silenceLogger: () => typeof jest;

package/dist/testUtils.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.silenceLogger = void 0;
+// Utility to silence logger output in tests, must be at the top of the test file
+const silenceLogger = () => jest.mock("./logger", () => ({
+    logger: {
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+        debug: jest.fn(),
+    },
+}));
+exports.silenceLogger = silenceLogger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moreapp/common-nodejs",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "license": "UNLICENSED",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     "format:fix": "yarn prettier --write",
     "lint:check": "eslint . --ext ts",
     "lint:fix": "yarn lint:check --fix",
-    "prepare": "husky install"
+    "prepare": "husky"
   },
   "files": [
     "dist/**/*"
@@ -35,27 +35,29 @@
     "@opentelemetry/semantic-conventions": "1.22.0",
     "axios": "1.13.2",
     "content-disposition-parser": "1.0.2",
-    "date-and-time": "3.1.1",
+    "date-and-time": "4.1.0",
+    "express": "5.2.1",
     "lodash": "4.17.21",
     "winston": "3.13.0",
     "zod": "3.25.76"
   },
   "devDependencies": {
+    "@types/express": "5.0.6",
     "@types/jest": "29.5.11",
     "@types/lodash": "4.17.0",
-    "@types/node": "22.16.2",
+    "@types/node": "24.10.1",
     "@typescript-eslint/eslint-plugin": "6.21.0",
     "@typescript-eslint/parser": "6.21.0",
     "eslint": "8.57.0",
-    "eslint-config-airbnb-typescript": "17.1.0",
+    "eslint-config-airbnb-typescript": "18.0.0",
     "eslint-config-prettier": "9.1.0",
     "eslint-plugin-import": "2.29.1",
     "eslint-plugin-prettier": "5.1.3",
     "husky": "9.0.7",
     "jest": "29.7.0",
-    "jest-mock-extended": "3.0.5",
+    "jest-mock-extended": "4.0.0",
     "lint-staged": "16.2.6",
-    "nock": "13.5.4",
+    "nock": "14.0.10",
     "prettier": "3.2.4",
     "ts-jest": "29.1.2",
     "ts-node": "10.9.2",