@saasquatch/express-boilerplate 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ReferralSaaSquatch.com, Inc.
+
+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.

package/README.md

@@ -0,0 +1,155 @@
+<h1 align="center">@saasquatch/express-boilerplate</h1>
+
+The SaaSquatch exporess boilerplate package provides a number of middleware and utility
+functions that are useful in Express apps, particularly those running in Kubernetes
+environments.
+
+## Getting Started
+
+Install the package:
+
+```bash
+npm install @saasquatch/express-boilerplate
+```
+
+## Basic usage:
+
+```typescript
+import {
+  healthCheck,
+  installShutdownManager,
+  requestIdAndLogger,
+  shutdownManagerConfigFromEnv,
+} from "@saasquatch/express-boilerplate";
+
+import { httpLogMiddleware, initializeLogger } from "@saasquatch/logger";
+import express from "express";
+
+const app = express();
+const baseLogger = initializeLogger();
+
+app.use(requestIdAndLogger(baseLogger));
+app.use(httpLogMiddleware(baseLogger));
+app.get("/healthz", healthCheck(app, baseLogger));
+
+const server = installShutdownManager(
+  app,
+  baseLogger,
+  shutdownManagerConfigFromEnv(),
+);
+
+server.listen(3000, () => baseLogger.notice("App listening on port 3000"));
+```
+
+## Graceful Shutdown Manager
+
+The `installShutdownManager` function installs the OS signal handlers for `SIGINT` and
+`SIGTERM` to shutdown the server in a graceful way that is compatible with Kubernetes
+best practices. It is also used to configure the TCP Keep-Alive timeouts for the server,
+which may be necessary for certain cloud load balancers.
+
+The `shutdownManagerConfigFromEnv()` function will load the following config options from
+environment variables:
+
+| Environment variable             | Config option             | Meaning                                                                                                                                                                      |
+| -------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SSQT_HTTP_KEEP_ALIVE_SECONDS`   | `keepAliveTimeoutSeconds` | The number of seconds of inactivity a server needs to wait for additional incoming data, after it has finished writing the last response, before a socket will be destroyed. |
+| `SSQT_TERMINATION_DELAY_SECONDS` | `terminationDelaySeconds` | The number of seconds to wait after the shutdown signal is received and before exiting the application process.                                                              |
+
+The options can also be customized directly:
+
+```typescript
+const server = installShutdownManager(app, logger, {
+  keepAliveTimeoutSeconds: 620,
+  terminationDelaySeconds: 20,
+});
+
+server.listen(3000, () => logger.notice("App listening on port 3000"));
+```
+
+The shutdown manager also supports executing hook functions when certain events occur
+during the shutdown process:
+
+```typescript
+const server = installShutdownManager(app, logger, {
+  ...shutdownManagerConfigFromEnv(),
+
+  onSignalReceived: async (signal) =>
+    console.log(`"${signal}" signal received!`),
+
+  beforeShutdown: async () => console.log(`HTTP server is about to shut down`),
+
+  afterShutdown: async () => console.log(`HTTP Server has shut down`),
+});
+
+server.listen(3000, () => logger.notice("App listening on port 3000"));
+```
+
+## RequestId and Logger Middleware
+
+The `requestIdAndLogger` middleware function generates a random request ID using `nanoid`
+and sets the `res.locals.requestId` and `res.locals.logger` variables. These can be used
+in the subsequent request handlers to generate log events with the requestId
+automatically attached.
+
+```typescript
+const baseLogger = initializeLogger();
+app.use(requestIdAndLogger(baseLogger));
+
+app.get("/testing", (req, res) => {
+  const logger = res.locals.logger;
+  const requestId = res.locals.requestId;
+
+  logger.info(`The requestId is: ${requestId}`);
+
+  // produces log event with { "requestId": "XXXXXXXXXXXX" } as a field
+  logger.info("Inside the /testing request handler!");
+});
+```
+
+## Async request handler wrapper
+
+The `asyncHandlerWrapper` function wraps an async request handler to automatically catch
+any rejected promises, log the error, and return an appropriate response. Without this
+function the default behavior is for unhandled promise rejections to crash the
+application, which is obviously unwanted.
+
+This function requires that the `requestIdAndLogger` middleware function is installed.
+
+```typescript
+import {
+  asyncHandlerWrapper,
+  requestIdAndLogger,
+} from "@saasquatch/express-boilerplate";
+
+app.use(requestIdAndLogger(baseLogger));
+
+// BAD -- promise rejection in getSomethingFromTheDatabase will crash
+// the application
+app.get("/testing", async (req, res) => {
+  const dbResults = await getSomethingFromTheDatabase();
+  res.status(200).json(dbResults);
+});
+
+// OK -- promise rejection in getSomethingFromTheDatabase will be handled by
+// the wrapper and return an appropriate 500 response
+app.get(
+  "/testing",
+  asyncHandlerWrapper(async (req, res) => {
+    const dbResults = await getSomethingFromTheDatabase();
+    res.status(200).json(dbResults);
+  }),
+);
+```
+
+## nanoid re-export
+
+The library exports a `nanoid` function, which is just vanilla `nanoid` with a custom
+alphabet of characters that are a bit easier to read. Its default ID length is 32.
+
+```typescript
+import { nanoid } from "@saasquatch/express-boilerplate";
+
+console.log(nanoid());
+console.log(nanoid(12));
+```

package/dist/async-wrapper.d.ts

@@ -0,0 +1,2 @@
+import { Request, Response } from "express";
+export declare function asyncHandlerWrapper<T>(handler: (req: Request, res: Response) => Promise<T>, renderErrorPage?: (status: number, message: string, debugId: string) => Promise<string>): (req: Request, res: Response) => void;

package/dist/async-wrapper.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asyncHandlerWrapper = void 0;
+const error_1 = require("./error");
+const nanoid_1 = require("./nanoid");
+function asyncHandlerWrapper(handler, renderErrorPage) {
+    return (req, res) => {
+        handler(req, res).catch((e) => {
+            var _a;
+            const logger = res.locals.logger;
+            const requestId = res.locals.requestId;
+            const debugId = (0, nanoid_1.nanoid)(8);
+            const error = Object.assign({ debugId,
+                requestId }, (0, error_1.formatGenericError)(e));
+            logger === null || logger === void 0 ? void 0 : logger.error({ message: "Fatal error occurred!!", error });
+            const status = 500;
+            const message = e instanceof Error ? e.message : "An internal error occurred";
+            // cannot send any response if the headers have already been sent
+            if (res.headersSent) {
+                return;
+            }
+            // if the client accepts HTML and the error page render function was
+            // provided, we will render the error page and return the HTML
+            if (((_a = req.header("accept")) !== null && _a !== void 0 ? _a : "").includes("text/html") &&
+                renderErrorPage) {
+                renderErrorPage(status, message, debugId)
+                    .then((html) => {
+                    res.status(status).contentType("text/html;charset=utf8").send(html);
+                })
+                    .catch((e) => {
+                    logger === null || logger === void 0 ? void 0 : logger.error(Object.assign({ message: "Error occurred while rendering error page!" }, (0, error_1.formatGenericError)(e)));
+                    res
+                        .status(status)
+                        .contentType("application/json")
+                        .send(JSON.stringify(Object.assign({ message }, error), null, 2));
+                });
+            }
+            else {
+                res
+                    .status(status)
+                    .contentType("application/json")
+                    .send(JSON.stringify(Object.assign({ message }, error), null, 2));
+            }
+        });
+    };
+}
+exports.asyncHandlerWrapper = asyncHandlerWrapper;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXN5bmMtd3JhcHBlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9hc3luYy13cmFwcGVyLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUVBLG1DQUE2QztBQUM3QyxxQ0FBa0M7QUFFbEMsU0FBZ0IsbUJBQW1CLENBQ2pDLE9BQW9ELEVBQ3BELGVBSW9CO0lBRXBCLE9BQU8sQ0FBQyxHQUFHLEVBQUUsR0FBRyxFQUFFLEVBQUU7UUFDbEIsT0FBTyxDQUFDLEdBQUcsRUFBRSxHQUFHLENBQUMsQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRTs7WUFDNUIsTUFBTSxNQUFNLEdBQUcsR0FBRyxDQUFDLE1BQU0sQ0FBQyxNQUE0QixDQUFDO1lBQ3ZELE1BQU0sU0FBUyxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsU0FBK0IsQ0FBQztZQUU3RCxNQUFNLE9BQU8sR0FBRyxJQUFBLGVBQU0sRUFBQyxDQUFDLENBQUMsQ0FBQztZQUUxQixNQUFNLEtBQUssbUJBQ1QsT0FBTztnQkFDUCxTQUFTLElBQ04sSUFBQSwwQkFBa0IsRUFBQyxDQUFDLENBQUMsQ0FDekIsQ0FBQztZQUVGLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxLQUFLLENBQUMsRUFBRSxPQUFPLEVBQUUsd0JBQXdCLEVBQUUsS0FBSyxFQUFFLENBQUMsQ0FBQztZQUU1RCxNQUFNLE1BQU0sR0FBRyxHQUFHLENBQUM7WUFDbkIsTUFBTSxPQUFPLEdBQ1gsQ0FBQyxZQUFZLEtBQUssQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsNEJBQTRCLENBQUM7WUFFaEUsaUVBQWlFO1lBQ2pFLElBQUksR0FBRyxDQUFDLFdBQVcsRUFBRSxDQUFDO2dCQUNwQixPQUFPO1lBQ1QsQ0FBQztZQUVELG9FQUFvRTtZQUNwRSw4REFBOEQ7WUFDOUQsSUFDRSxDQUFDLE1BQUEsR0FBRyxDQUFDLE1BQU0sQ0FBQyxRQUFRLENBQUMsbUNBQUksRUFBRSxDQUFDLENBQUMsUUFBUSxDQUFDLFdBQVcsQ0FBQztnQkFDbEQsZUFBZSxFQUNmLENBQUM7Z0JBQ0QsZUFBZSxDQUFDLE1BQU0sRUFBRSxPQUFPLEVBQUUsT0FBTyxDQUFDO3FCQUN0QyxJQUFJLENBQUMsQ0FBQyxJQUFJLEVBQUUsRUFBRTtvQkFDYixHQUFHLENBQUMsTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLFdBQVcsQ0FBQyx3QkFBd0IsQ0FBQyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsQ0FBQztnQkFDdEUsQ0FBQyxDQUFDO3FCQUNELEtBQUssQ0FBQyxDQUFDLENBQUMsRUFBRSxFQUFFO29CQUNYLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxLQUFLLGlCQUNYLE9BQU8sRUFBRSw0Q0FBNEMsSUFDbEQsSUFBQSwwQkFBa0IsRUFBQyxDQUFDLENBQUMsRUFDeEIsQ0FBQztvQkFFSCxHQUFHO3lCQUNBLE1BQU0sQ0FBQyxNQUFNLENBQUM7eUJBQ2QsV0FBVyxDQUFDLGtCQUFrQixDQUFDO3lCQUMvQixJQUFJLENBQUMsSUFBSSxDQUFDLFNBQVMsaUJBQUcsT0FBTyxJQUFLLEtBQUssR0FBSSxJQUFJLEVBQUUsQ0FBQyxDQUFDLENBQUMsQ0FBQztnQkFDMUQsQ0FBQyxDQUFDLENBQUM7WUFDUCxDQUFDO2lCQUFNLENBQUM7Z0JBQ04sR0FBRztxQkFDQSxNQUFNLENBQUMsTUFBTSxDQUFDO3FCQUNkLFdBQVcsQ0FBQyxrQkFBa0IsQ0FBQztxQkFDL0IsSUFBSSxDQUFDLElBQUksQ0FBQyxTQUFTLGlCQUFHLE9BQU8sSUFBSyxLQUFLLEdBQUksSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLENBQUM7WUFDMUQsQ0FBQztRQUNILENBQUMsQ0FBQyxDQUFDO0lBQ0wsQ0FBQyxDQUFDO0FBQ0osQ0FBQztBQTdERCxrREE2REMifQ==

package/dist/error.d.ts

@@ -0,0 +1,6 @@
+export type GenericError = {
+    e: unknown;
+    eStr: string;
+    eJson: string;
+};
+export declare function formatGenericError(e: unknown): GenericError;

package/dist/error.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGenericError = void 0;
+function formatGenericError(e) {
+    return {
+        e,
+        // we don't care that the value of e might be weird in the string template, the
+        // whole point is to just convert it to a string no matter the type.
+        // eslint-disable-next-line -- @typescript-eslint/restrict-template-expressions
+        eStr: `${e}`,
+        eJson: JSON.stringify(e),
+    };
+}
+exports.formatGenericError = formatGenericError;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZXJyb3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvZXJyb3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBTUEsU0FBZ0Isa0JBQWtCLENBQUMsQ0FBVTtJQUMzQyxPQUFPO1FBQ0wsQ0FBQztRQUNELCtFQUErRTtRQUMvRSxvRUFBb0U7UUFDcEUsK0VBQStFO1FBQy9FLElBQUksRUFBRSxHQUFHLENBQUMsRUFBRTtRQUNaLEtBQUssRUFBRSxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQztLQUN6QixDQUFDO0FBQ0osQ0FBQztBQVRELGdEQVNDIn0=

package/dist/healthcheck.d.ts

@@ -0,0 +1,16 @@
+import { Application, Request, Response } from "express";
+import { Logger } from "winston";
+export type HealthCheckResult<T, E> = {
+    status: "OK";
+    info?: T;
+} | {
+    status: "ERROR";
+    error?: E;
+};
+/**
+ * Return a request handler that can be used in Express
+ * to respond to health checks in the application. The
+ * health check will return HTTP code 503 if the app
+ * is in a TERMINATING state.
+ */
+export declare function healthCheck<T = undefined, E = undefined>(app: Application, logger: Logger, customCheck?: () => Promise<HealthCheckResult<T, E>>): (req: Request, res: Response) => void;

package/dist/healthcheck.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.healthCheck = void 0;
+const shutdown_1 = require("./shutdown");
+const error_1 = require("./error");
+/**
+ * Return a request handler that can be used in Express
+ * to respond to health checks in the application. The
+ * health check will return HTTP code 503 if the app
+ * is in a TERMINATING state.
+ */
+function healthCheck(app, logger, customCheck) {
+    return (_req, res) => {
+        // eslint-disable-next-line -- @typescript-eslint/no-unsafe-assignment
+        const terminating = app.locals[shutdown_1.TERMINATION_APP_LOCAL_KEY];
+        if (typeof terminating === "boolean" && terminating) {
+            logger.info("App is in TERMINATING state, sending health check failure");
+            return res.status(503).json({ status: "TERMINATING" });
+        }
+        if (customCheck) {
+            customCheck()
+                .then((result) => {
+                const code = result.status === "OK" ? 200 : 503;
+                res.status(code).json(result);
+            })
+                .catch((e) => {
+                const code = 503;
+                const error = (0, error_1.formatGenericError)(e);
+                logger.error(Object.assign({ message: "Custom health check callback failed" }, error));
+                res.status(code).json({ status: "ERROR", error });
+            });
+            return;
+        }
+        else {
+            return res.status(200).json({ status: "OK" });
+        }
+    };
+}
+exports.healthCheck = healthCheck;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGVhbHRoY2hlY2suanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaGVhbHRoY2hlY2sudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBRUEseUNBQXVEO0FBQ3ZELG1DQUE2QztBQVk3Qzs7Ozs7R0FLRztBQUNILFNBQWdCLFdBQVcsQ0FDekIsR0FBZ0IsRUFDaEIsTUFBYyxFQUNkLFdBQW9EO0lBRXBELE9BQU8sQ0FBQyxJQUFJLEVBQUUsR0FBRyxFQUFFLEVBQUU7UUFDbkIsc0VBQXNFO1FBQ3RFLE1BQU0sV0FBVyxHQUFHLEdBQUcsQ0FBQyxNQUFNLENBQUMsb0NBQXlCLENBQUMsQ0FBQztRQUMxRCxJQUFJLE9BQU8sV0FBVyxLQUFLLFNBQVMsSUFBSSxXQUFXLEVBQUUsQ0FBQztZQUNwRCxNQUFNLENBQUMsSUFBSSxDQUFDLDJEQUEyRCxDQUFDLENBQUM7WUFDekUsT0FBTyxHQUFHLENBQUMsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDLElBQUksQ0FBQyxFQUFFLE1BQU0sRUFBRSxhQUFhLEVBQUUsQ0FBQyxDQUFDO1FBQ3pELENBQUM7UUFFRCxJQUFJLFdBQVcsRUFBRSxDQUFDO1lBQ2hCLFdBQVcsRUFBRTtpQkFDVixJQUFJLENBQUMsQ0FBQyxNQUFNLEVBQUUsRUFBRTtnQkFDZixNQUFNLElBQUksR0FBRyxNQUFNLENBQUMsTUFBTSxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUMsQ0FBQyxHQUFHLENBQUM7Z0JBQ2hELEdBQUcsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxDQUFDO1lBQ2hDLENBQUMsQ0FBQztpQkFDRCxLQUFLLENBQUMsQ0FBQyxDQUFDLEVBQUUsRUFBRTtnQkFDWCxNQUFNLElBQUksR0FBRyxHQUFHLENBQUM7Z0JBQ2pCLE1BQU0sS0FBSyxHQUFHLElBQUEsMEJBQWtCLEVBQUMsQ0FBQyxDQUFDLENBQUM7Z0JBRXBDLE1BQU0sQ0FBQyxLQUFLLGlCQUNWLE9BQU8sRUFBRSxxQ0FBcUMsSUFDM0MsS0FBSyxFQUNSLENBQUM7Z0JBRUgsR0FBRyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsQ0FBQyxJQUFJLENBQUMsRUFBRSxNQUFNLEVBQUUsT0FBTyxFQUFFLEtBQUssRUFBRSxDQUFDLENBQUM7WUFDcEQsQ0FBQyxDQUFDLENBQUM7WUFDTCxPQUFPO1FBQ1QsQ0FBQzthQUFNLENBQUM7WUFDTixPQUFPLEdBQUcsQ0FBQyxNQUFNLENBQUMsR0FBRyxDQUFDLENBQUMsSUFBSSxDQUFDLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDaEQsQ0FBQztJQUNILENBQUMsQ0FBQztBQUNKLENBQUM7QUFuQ0Qsa0NBbUNDIn0=

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { asyncHandlerWrapper } from "./async-wrapper";
+import type { GenericError } from "./error";
+import { formatGenericError } from "./error";
+import type { HealthCheckResult } from "./healthcheck";
+import { healthCheck } from "./healthcheck";
+import { requestIdAndLogger } from "./middleware";
+import { nanoid } from "./nanoid";
+import type { ShutdownManagerConfig } from "./shutdown";
+import { installShutdownManager, shutdownManagerConfigFromEnv } from "./shutdown";
+export { asyncHandlerWrapper, formatGenericError, healthCheck, installShutdownManager, nanoid, requestIdAndLogger, shutdownManagerConfigFromEnv, };
+export type { GenericError, HealthCheckResult, ShutdownManagerConfig };

package/dist/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdownManagerConfigFromEnv = exports.requestIdAndLogger = exports.nanoid = exports.installShutdownManager = exports.healthCheck = exports.formatGenericError = exports.asyncHandlerWrapper = void 0;
+const async_wrapper_1 = require("./async-wrapper");
+Object.defineProperty(exports, "asyncHandlerWrapper", { enumerable: true, get: function () { return async_wrapper_1.asyncHandlerWrapper; } });
+const error_1 = require("./error");
+Object.defineProperty(exports, "formatGenericError", { enumerable: true, get: function () { return error_1.formatGenericError; } });
+const healthcheck_1 = require("./healthcheck");
+Object.defineProperty(exports, "healthCheck", { enumerable: true, get: function () { return healthcheck_1.healthCheck; } });
+const middleware_1 = require("./middleware");
+Object.defineProperty(exports, "requestIdAndLogger", { enumerable: true, get: function () { return middleware_1.requestIdAndLogger; } });
+const nanoid_1 = require("./nanoid");
+Object.defineProperty(exports, "nanoid", { enumerable: true, get: function () { return nanoid_1.nanoid; } });
+const shutdown_1 = require("./shutdown");
+Object.defineProperty(exports, "installShutdownManager", { enumerable: true, get: function () { return shutdown_1.installShutdownManager; } });
+Object.defineProperty(exports, "shutdownManagerConfigFromEnv", { enumerable: true, get: function () { return shutdown_1.shutdownManagerConfigFromEnv; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsbURBQXNEO0FBY3BELG9HQWRPLG1DQUFtQixPQWNQO0FBWnJCLG1DQUE2QztBQWEzQyxtR0FiTywwQkFBa0IsT0FhUDtBQVhwQiwrQ0FBNEM7QUFZMUMsNEZBWk8seUJBQVcsT0FZUDtBQVhiLDZDQUFrRDtBQWNoRCxtR0FkTywrQkFBa0IsT0FjUDtBQWJwQixxQ0FBa0M7QUFZaEMsdUZBWk8sZUFBTSxPQVlQO0FBVlIseUNBR29CO0FBTWxCLHVHQVJBLGlDQUFzQixPQVFBO0FBR3RCLDZHQVZBLHVDQUE0QixPQVVBIn0=

package/dist/middleware.d.ts

@@ -0,0 +1,7 @@
+import { NextFunction, Request, Response } from "express";
+import { Logger } from "winston";
+/**
+ * Generate a requestId and derived child logger
+ * for each request
+ */
+export declare function requestIdAndLogger(baseLogger: Logger): (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestIdAndLogger = void 0;
+const nanoid_1 = require("./nanoid");
+/**
+ * Generate a requestId and derived child logger
+ * for each request
+ */
+function requestIdAndLogger(baseLogger) {
+    return (_req, res, next) => {
+        if (typeof res.locals.requestId !== "string") {
+            // the requestId really doesn't need to be longer than 12 characters,
+            // it's only used for debugging
+            const requestId = (0, nanoid_1.nanoid)(12);
+            res.locals.requestId = requestId;
+            res.locals.logger = baseLogger.child({ requestId });
+        }
+        next();
+    };
+}
+exports.requestIdAndLogger = requestIdAndLogger;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWlkZGxld2FyZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9taWRkbGV3YXJlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUVBLHFDQUFrQztBQUVsQzs7O0dBR0c7QUFDSCxTQUFnQixrQkFBa0IsQ0FDaEMsVUFBa0I7SUFFbEIsT0FBTyxDQUFDLElBQUksRUFBRSxHQUFHLEVBQUUsSUFBSSxFQUFFLEVBQUU7UUFDekIsSUFBSSxPQUFPLEdBQUcsQ0FBQyxNQUFNLENBQUMsU0FBUyxLQUFLLFFBQVEsRUFBRSxDQUFDO1lBQzdDLHFFQUFxRTtZQUNyRSwrQkFBK0I7WUFDL0IsTUFBTSxTQUFTLEdBQUcsSUFBQSxlQUFNLEVBQUMsRUFBRSxDQUFDLENBQUM7WUFDN0IsR0FBRyxDQUFDLE1BQU0sQ0FBQyxTQUFTLEdBQUcsU0FBUyxDQUFDO1lBQ2pDLEdBQUcsQ0FBQyxNQUFNLENBQUMsTUFBTSxHQUFHLFVBQVUsQ0FBQyxLQUFLLENBQUMsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDO1FBQ3RELENBQUM7UUFDRCxJQUFJLEVBQUUsQ0FBQztJQUNULENBQUMsQ0FBQztBQUNKLENBQUM7QUFiRCxnREFhQyJ9

package/dist/nanoid.d.ts

@@ -0,0 +1 @@
+export declare const nanoid: (size?: number | undefined) => string;

package/dist/nanoid.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nanoid = void 0;
+const nanoid_1 = require("nanoid");
+const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+// security: nanoid uses cyrpto random bytes by default
+exports.nanoid = (0, nanoid_1.customAlphabet)(alphabet, 32);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibmFub2lkLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL25hbm9pZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSxtQ0FBd0M7QUFDeEMsTUFBTSxRQUFRLEdBQ1osZ0VBQWdFLENBQUM7QUFFbkUsdURBQXVEO0FBQzFDLFFBQUEsTUFBTSxHQUFHLElBQUEsdUJBQWMsRUFBQyxRQUFRLEVBQUUsRUFBRSxDQUFDLENBQUMifQ==

package/dist/shutdown.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="node" />
+import { Application } from "express";
+import { Server } from "http";
+import { Logger } from "winston";
+export declare const TERMINATION_APP_LOCAL_KEY = "__ssqt_terminating";
+export declare const INSTALLATION_APP_LOCAL_KEY = "__ssqt_shutdown_manager_installed";
+export type ShutdownManagerConfig = {
+    keepAliveTimeoutSeconds: number;
+    terminationDelaySeconds: number;
+    onSignalReceived?: (signal: string) => Promise<void>;
+    beforeShutdown?: () => Promise<void>;
+    afterShutdown?: () => Promise<void>;
+};
+export declare function shutdownManagerConfigFromEnv(defaults?: Partial<ShutdownManagerConfig>): ShutdownManagerConfig;
+/**
+ * Install the signal handlers and graceful shutdown logic
+ * into the application.
+ */
+export declare function installShutdownManager(app: Application, logger: Logger, config: ShutdownManagerConfig): Server;

package/dist/shutdown.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installShutdownManager = exports.shutdownManagerConfigFromEnv = exports.INSTALLATION_APP_LOCAL_KEY = exports.TERMINATION_APP_LOCAL_KEY = void 0;
+const http_1 = require("http");
+const error_1 = require("./error");
+const handleHookError = (hook, logger) => (err) => {
+    logger.error(Object.assign({ message: `Error ocurred inside shutdown-manager ${hook} hook` }, (0, error_1.formatGenericError)(err)));
+};
+// these should be kept opaque to consumers of the library. manipulating
+// these variables outside the library can result in unwanted behavior.
+exports.TERMINATION_APP_LOCAL_KEY = "__ssqt_terminating";
+exports.INSTALLATION_APP_LOCAL_KEY = "__ssqt_shutdown_manager_installed";
+function shutdownManagerConfigFromEnv(defaults) {
+    var _a, _b;
+    const optionalInt = (key, defaultVal) => {
+        const env = process.env[key];
+        if (!env) {
+            return defaultVal;
+        }
+        const parsedEnv = parseInt(env, 10);
+        if (Number.isNaN(parsedEnv)) {
+            throw new Error(`Environment variable "${key}" is not an integer`);
+        }
+        return parsedEnv;
+    };
+    const keepAliveTimeoutSeconds = optionalInt("SSQT_HTTP_KEEP_ALIVE_SECONDS", (_a = defaults === null || defaults === void 0 ? void 0 : defaults.keepAliveTimeoutSeconds) !== null && _a !== void 0 ? _a : 60);
+    const terminationDelaySeconds = optionalInt("SSQT_TERMINATION_DELAY_SECONDS", (_b = defaults === null || defaults === void 0 ? void 0 : defaults.terminationDelaySeconds) !== null && _b !== void 0 ? _b : 0);
+    return {
+        keepAliveTimeoutSeconds,
+        terminationDelaySeconds,
+    };
+}
+exports.shutdownManagerConfigFromEnv = shutdownManagerConfigFromEnv;
+/**
+ * Install the signal handlers and graceful shutdown logic
+ * into the application.
+ */
+function installShutdownManager(app, logger, config) {
+    app.disable("x-powered-by");
+    const server = (0, http_1.createServer)(app);
+    // eslint-disable-next-line -- @typescript-eslint/no-unsafe-assignment
+    const shutdownManagerInstalled = app.locals[exports.INSTALLATION_APP_LOCAL_KEY];
+    if (typeof shutdownManagerInstalled === "boolean" &&
+        shutdownManagerInstalled) {
+        throw new Error("Shutdown manager can only be installed once");
+    }
+    app.locals[exports.INSTALLATION_APP_LOCAL_KEY] = true;
+    // https://cloud.google.com/load-balancing/docs/https/https-logging-monitoring#failure-messages
+    // (see the section on backend_connection_closed_before_data_sent_to_client)
+    server.keepAliveTimeout = config.keepAliveTimeoutSeconds * 1000;
+    server.headersTimeout = (config.keepAliveTimeoutSeconds + 1) * 1000;
+    const gracefulShutdown = (signal) => () => {
+        // eslint-disable-next-line -- @typescript-eslint/no-unsafe-assignment
+        const isTerminating = app.locals[exports.TERMINATION_APP_LOCAL_KEY];
+        if (typeof isTerminating === "boolean" && isTerminating) {
+            logger.warn("Server is already in TERMINATING state, not starting shutdown procedure again");
+            return;
+        }
+        app.locals[exports.TERMINATION_APP_LOCAL_KEY] = true;
+        logger.notice(`Received ${signal} signal, starting shutdown procedure`);
+        const shutdown = () => {
+            setTimeout(() => {
+                const closeServer = () => {
+                    server.close(() => {
+                        logger.notice("Server closed");
+                        if (config.afterShutdown) {
+                            logger.debug("afterShutdown hook is present, executing before shutting down");
+                            config
+                                .afterShutdown()
+                                .catch(handleHookError("afterShutdown", logger))
+                                .finally(() => process.exit(0));
+                        }
+                    });
+                };
+                if (config.beforeShutdown) {
+                    config
+                        .beforeShutdown()
+                        .catch(handleHookError("beforeShutdown", logger))
+                        .finally(() => {
+                        closeServer();
+                    });
+                }
+                else {
+                    closeServer();
+                }
+            }, config.terminationDelaySeconds * 1000);
+        };
+        if (config.onSignalReceived) {
+            logger.debug("onSignalReceived hook is present, executing before shutting down");
+            config
+                .onSignalReceived(signal)
+                .catch(handleHookError("onSignalReceived", logger))
+                .finally(() => {
+                shutdown();
+            });
+        }
+        else {
+            shutdown();
+        }
+    };
+    process.on("SIGTERM", gracefulShutdown("SIGTERM"));
+    process.on("SIGINT", gracefulShutdown("SIGINT"));
+    return server;
+}
+exports.installShutdownManager = installShutdownManager;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2h1dGRvd24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvc2h1dGRvd24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQ0EsK0JBQTRDO0FBRTVDLG1DQUE2QztBQUU3QyxNQUFNLGVBQWUsR0FBRyxDQUFDLElBQVksRUFBRSxNQUFjLEVBQUUsRUFBRSxDQUFDLENBQUMsR0FBWSxFQUFFLEVBQUU7SUFDekUsTUFBTSxDQUFDLEtBQUssaUJBQ1YsT0FBTyxFQUFFLHlDQUF5QyxJQUFJLE9BQU8sSUFDMUQsSUFBQSwwQkFBa0IsRUFBQyxHQUFHLENBQUMsRUFDMUIsQ0FBQztBQUNMLENBQUMsQ0FBQztBQUVGLHdFQUF3RTtBQUN4RSx1RUFBdUU7QUFDMUQsUUFBQSx5QkFBeUIsR0FBRyxvQkFBb0IsQ0FBQztBQUNqRCxRQUFBLDBCQUEwQixHQUFHLG1DQUFtQyxDQUFDO0FBVTlFLFNBQWdCLDRCQUE0QixDQUMxQyxRQUF5Qzs7SUFFekMsTUFBTSxXQUFXLEdBQUcsQ0FBQyxHQUFXLEVBQUUsVUFBa0IsRUFBVSxFQUFFO1FBQzlELE1BQU0sR0FBRyxHQUFHLE9BQU8sQ0FBQyxHQUFHLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDN0IsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO1lBQ1QsT0FBTyxVQUFVLENBQUM7UUFDcEIsQ0FBQztRQUVELE1BQU0sU0FBUyxHQUFHLFFBQVEsQ0FBQyxHQUFHLEVBQUUsRUFBRSxDQUFDLENBQUM7UUFDcEMsSUFBSSxNQUFNLENBQUMsS0FBSyxDQUFDLFNBQVMsQ0FBQyxFQUFFLENBQUM7WUFDNUIsTUFBTSxJQUFJLEtBQUssQ0FBQyx5QkFBeUIsR0FBRyxxQkFBcUIsQ0FBQyxDQUFDO1FBQ3JFLENBQUM7UUFDRCxPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDLENBQUM7SUFFRixNQUFNLHVCQUF1QixHQUFHLFdBQVcsQ0FDekMsOEJBQThCLEVBQzlCLE1BQUEsUUFBUSxhQUFSLFFBQVEsdUJBQVIs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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@saasquatch/express-boilerplate",
+  "version": "1.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Boilerplate middleware and functions for building Express apps on Kubernetes",
+  "prettier": {},
+  "author": "ReferralSaaSquatch.com, Inc.",
+  "engines": {
+    "node": "^18 || ^20"
+  },
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saasquatch/program-tools.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/saasquatch/program-tools/issues"
+  },
+  "homepage": "https://github.com/saasquatch/program-tools/packages/express-boilerplate#readme",
+  "main": "dist/index.js",
+  "scripts": {
+    "test": "npm run build && node --enable-source-maps node_modules/jest/bin/jest.js --roots dist/tests --coverage",
+    "build": "tsc -b",
+    "lint": "eslint ./src --report-unused-disable-directives",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@saasquatch/logger": "^1.4.1",
+    "@types/express": "4",
+    "@types/jest": "^29.5.12",
+    "@types/node": "18",
+    "@types/supertest": "^6.0.2",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "supertest": "^6.3.4",
+    "ts-node": "^10.9.2"
+  },
+  "peerDependencies": {
+    "express": "4",
+    "winston": "3"
+  },
+  "dependencies": {
+    "nanoid": "^3.3.7"
+  }
+}