connect-ready 1.0.13 → 2.0.0

package/README.md

@@ -1,77 +1,122 @@
 # connect-ready
 
-[![Build Status](https://travis-ci.org/dcolens/connect-ready.svg?branch=master)](https://travis-ci.org/dcolens/connect-ready) [![Coverage Status](https://coveralls.io/repos/github/dcolens/connect-ready/badge.svg?branch=master)](https://coveralls.io/github/dcolens/connect-ready?branch=master)
+Express/Connect readiness route for Kubernetes applications.
 
-express route that indicates whether a service is ready or not. Mostly created to make graceful restart of node express servers in a Kubernetes environment.
+## Requirements
 
+- Node.js 22 or newer
 
-## Graceful restart of a nodejs express server in Kubernetes
+## Installation
 
-I intially thought that catching SIGTERM and waiting for server.close()` to finish would be enough to do a graceful restart of a nodejs service. I was wrong. 
+```shell
+npm install connect-ready
+```
+
+## Readiness route
 
-The reliable way of handling a graceful restart is to use the [readynessProbe](http://kubernetes.io/docs/user-guide/production-pods/#liveness-and-readiness-probes-aka-health-checks) functionality either with a [pre-stop hook](http://kubernetes.io/docs/user-guide/container-environment/#container-hooks) or when catching the SIGTERM signal. The readynessProbes are used by Kubernetes to know if a service is ready and can receive traffic, in its http form Kubernetes checks for the responseCode, anything above 399 is considered not ready. 
+The route returns `503` until the application explicitly becomes ready.
 
-When a service receives a stop signal (SIGTERM), it should respond with a 500 responsecode when probed for readiness, this will ensure Kubernetes does not send load to it anymore. Once that's done, `server.close()` can be called to ensure ongoing connections are terminated gracefully.
+```javascript
+'use strict';
 
-Note that by default Kubernetes will send a SIGKILL 30s after the SIGTERM if the service did not terminate, this timer is configurable in the manifest. 
+const http = require('node:http');
+const express = require('express');
+const ready = require('connect-ready');
+
+const app = express();
+const server = http.createServer(app);
+
+app.get('/ready', ready.route);
 
+server.listen(3000, () => {
+  ready.setStatus(204);
+});
+```
 
-## Example of a graceful node http server for Kubernetes
+Kubernetes considers HTTP responses from 200 through 399 successful. Use a failure status such as `503` whenever the application cannot accept traffic:
 
 ```javascript
-'use strict';
-var http = require('http');
-var express = require('express');
-var ready = require('connect-ready');
+ready.setStatus(503);
+```
 
-var app = express();
-var server = http.createServer(app);
+## Graceful shutdown in Kubernetes
 
+Modern Kubernetes marks a terminating Pod endpoint as not ready. The application must still stop accepting new connections and allow active requests to finish.
 
-app.get('/ready', ready.route);
+`registerShutdownHandlers()` installs a consistent lifecycle for Node HTTP servers:
 
-/**
- * adds a `Connection: close` to all responses stopping.
- */
-app.use(ready.gracefulShutdownKeepaliveConnections);
+- `SIGTERM` and `SIGINT` drain active requests and exit `0`;
+- `uncaughtException` and `unhandledRejection` attempt bounded cleanup and exit `1`;
+- readiness changes to `503` as soon as shutdown starts;
+- `server.close()` immediately stops new connections and drains active requests;
+- the process force-closes HTTP connections and exits `1` if its deadline expires.
 
-server.listen(3000, function () { 
-    ready.setStatus(204);
-  console.log('Example app listening on port 3000!');
+```javascript
+const shutdown = ready.registerShutdownHandlers(server, {
+  // Keep this below the Pod's terminationGracePeriodSeconds.
+  timeoutMs: Number.parseInt(process.env.SHUTDOWN_TIMEOUT_MS ?? '30000', 10),
+
+  // Fatal process errors should not drain for as long as a normal rollout.
+  fatalTimeoutMs: 30_000,
+
+  async cleanup() {
+    await database.close();
+    await log4js.shutdown();
+  },
+
+  onFatal(error, origin) {
+    logger.fatal({ error, origin }, 'Fatal process error');
+  },
+
+  // Optional: server.closeAllConnections() does not close upgraded protocols.
+  forceClose() {
+    webSocketServer.close();
+  },
 });
+```
 
+Node.js 22 `server.close()` stops accepting new connections, closes idle keep-alive connections, and waits for active HTTP requests to complete. Dependencies are cleaned up after those requests drain.
 
-//add graceful shutdown
-process.on('SIGTERM', function () {
-    ready.setStatus(500);
-    console.log('received SIGTERM');
- 
-     /** 
-      * delay the server closure by 2s to give kubernetes time to 
-      * know the service is not ready and direct the traffic somewhere else. 
-      * Instead of listening for SIGTERM, one could also configure a 
-      * pre-stop hook in the kubernetes manifest. 
-      */
-    setTimeout(function() { 
-        server.close(function() {
-            console.log('all connections closed');
-            process.exit(0);
-        });     
-    }, 2000);
-});
+Set `timeoutMs` slightly below the Pod's `terminationGracePeriodSeconds`. The Kubernetes grace period must be long enough for the longest active request plus dependency cleanup and a safety margin. Applications with requests lasting up to 45 minutes should configure both deadlines accordingly.
+
+An uncaught exception can leave application state inconsistent, so `fatalTimeoutMs` defaults to the smaller of 30 seconds and `timeoutMs`. Fatal shutdown still attempts to drain and clean up, but it must exit non-zero within that shorter deadline.
+
+A controller can also initiate shutdown or remove its process listeners explicitly:
+
+```javascript
+shutdown.close();   // Start a normal programmatic shutdown.
+shutdown.dispose(); // Or unregister the handlers if another component takes ownership.
 ```
 
-## toobusy option
+## API
+
+### `setStatus(code)`
+
+Sets the readiness HTTP status. The code must be an integer from 100 through 599.
+
+### `getStatus()`
+
+Returns the current readiness HTTP status.
+
+### `route(req, res)`
+
+Express/Connect route that responds with the current readiness status.
+
+### `registerShutdownHandlers(server, options)`
+
+Registers handlers for normal process signals and fatal process events. Returns a shutdown controller.
 
-Another use of the readinessProbe can be to indicate if the server is too busy, connect-ready can use the [toobusy-js](https://github.com/STRML/node-toobusy) module to indicate whether the server is too busy and deflect load to another pod.
+Options:
 
-**The toobusy-js module should be installed to use this functionality, it is not bundled in connect-ready.**
+- `timeoutMs`: normal shutdown deadline; defaults to 30 seconds.
+- `fatalTimeoutMs`: fatal-error deadline; defaults to at most 30 seconds.
+- `cleanup(context)`: async dependency cleanup after HTTP requests drain.
+- `onFatal(error, origin)`: fatal-error reporting hook.
+- `forceClose(context)`: closes upgraded or custom connections at the deadline.
 
-### Usage
+The controller provides:
 
-   1. npm install toobusy-js
-   2. enable toobusy in connect-ready:
-    ```javascript
-    ready.enableTooBusy(70)
-    ```
-    Where 70 is the lag as defined in [toobusy-js](https://github.com/STRML/node-toobusy)
+- `close()`: starts a normal programmatic shutdown.
+- `shutdown(request)`: starts shutdown with an explicit reason or error.
+- `dispose()`: unregisters the installed process handlers.
+- `isShuttingDown`: indicates whether shutdown has started.

package/index.d.ts

@@ -0,0 +1,54 @@
+interface ShutdownContext {
+  reason: string;
+  error?: Error;
+  origin?: string;
+  fatal: boolean;
+  forced: boolean;
+}
+
+interface ShutdownOptions {
+  timeoutMs?: number;
+  fatalTimeoutMs?: number;
+  cleanup?: (context: ShutdownContext) => void | Promise<void>;
+  forceClose?: (context: ShutdownContext) => void;
+  onFatal?: (error: Error, origin: string) => void;
+  exit?: (code: number) => void;
+}
+
+interface ShutdownRequest {
+  reason?: string;
+  error?: unknown;
+  fatal?: boolean;
+}
+
+interface ClosableServer {
+  close(callback: (error?: Error) => void): unknown;
+  closeAllConnections?(): void;
+}
+
+interface ShutdownController {
+  readonly isShuttingDown: boolean;
+  close(): Promise<number>;
+  dispose(): void;
+  shutdown(request?: ShutdownRequest): Promise<number>;
+}
+
+declare function setStatus(code: number): void;
+declare function getStatus(): number;
+declare function route(req: any, res: any): void;
+declare function registerShutdownHandlers(
+  server: ClosableServer,
+  options?: ShutdownOptions,
+): ShutdownController;
+
+export {
+  ClosableServer,
+  ShutdownContext,
+  ShutdownController,
+  ShutdownOptions,
+  ShutdownRequest,
+  getStatus,
+  registerShutdownHandlers,
+  route,
+  setStatus,
+};

package/index.js

@@ -1,113 +1,252 @@
-"use strict";
-var fs = require("fs");
+'use strict';
 
-var status = 500;
-var toobusy = false;
-var stopping = false;
+let status = 503;
 
+/**
+ * Set the HTTP status returned by the readiness route.
+ *
+ * Kubernetes considers responses from 200 through 399 successful.
+ *
+ * @param {number} code HTTP status code
+ */
 function setStatus(code) {
-	if (!Number.isInteger(code) || code < 1 || code > 999) {
-		var e = new Error("status should be an integer between 1 and 999");
-		e.status = code;
-		throw e;
-	}
-	status = code;
-}
+  if (!Number.isInteger(code) || code < 100 || code > 599) {
+    const error = new Error('status should be an integer between 100 and 599');
+    error.status = code;
+    throw error;
+  }
 
-function getStatus() {
-	return status;
+  status = code;
 }
 
 /**
- * returns 503 if server is toobusy, status (as defined by setStatus) otherwise.
+ * Return the status currently exposed by the readiness route.
+ *
+ * @returns {number} HTTP status code
  */
-function route(req, res) {
-	if (toobusy && toobusy()) {
-		res.sendStatus(503).end();
-	} else {
-		res.sendStatus(status).end();
-	}
+function getStatus() {
+  return status;
 }
 
 /**
- * adds a `Connection: close` to all responses if app.get('stopping') is true.
+ * Express/Connect readiness route.
  */
-function gracefulShutdownKeepaliveConnections(req, res, next) {
-	if (stopping === true) {
-		res.set("Connection", "close");
-	}
-	next();
+function route(_req, res) {
+  res.sendStatus(status);
 }
 
-function enableTooBusy(lag) {
-	if (typeof lag === "undefined") {
-		lag = 70;
-	}
-	if (!Number.isInteger(lag) || lag < 10) {
-		var e = new Error("lag should be an integer greater than 10");
-		e.lag = lag;
-		throw e;
-	}
-	toobusy = require("toobusy-js");
-	toobusy.maxLag(lag);
+function validateTimeout(name, value) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TypeError(`${name} should be a non-negative integer`);
+  }
+}
+
+function validateFunction(name, value) {
+  if (value !== undefined && typeof value !== 'function') {
+    throw new TypeError(`${name} should be a function`);
+  }
+}
+
+function normalizeError(value, message) {
+  if (value instanceof Error) return value;
+  return new Error(message, { cause: value });
 }
 
 /**
- * - logs shutdown to graylog (if log4js logger provided).
- * - sets `stopping` to true.
- * - dumps error in terminationFile if provided.
+ * Register a bounded graceful-shutdown lifecycle for a Node HTTP server.
+ *
+ * Normal process signals drain active HTTP requests and exit successfully.
+ * Fatal process events use a shorter deadline and exit unsuccessfully.
+ *
+ * @param {object} server Node HTTP server
+ * @param {object} [options] lifecycle options
+ * @returns {object} shutdown controller
  */
-function shutdown(signal, error, cb, terminationFile, logger) {
-	status = 503;
-	var reason;
-	if (error) {
-		if (logger && logger.fatal) {
-			let uError = {};
-			const errorKeys = Object.keys(error);
-			for (let index = 0; index < errorKeys.length; index++) {
-				const key = errorKeys[index];
-				uError[`_${key}`] = error[key];
-			}
-			logger.fatal(
-				{ GELF: true, _signal: signal, _stack: error.stack, ...uError },
-				error.message
-			);
-		}
-		reason = `${signal}\n${error.message}\n${error.stack}`;
-	} else {
-		if (logger && logger.info) {
-			logger.info({ GELF: true, _signal: signal }, "shutdown");
-		}
-		reason = "shutdown";
-	}
-	if (stopping === true) {
-		return;
-	}
-	stopping = true;
-
-	function callback() {
-		if (cb) {
-			return cb(signal ? 1 : 0);
-		}
-	}
-
-	if (terminationFile) {
-		fs.writeFile(terminationFile, reason, function (err) {
-			if (err) {
-				console.error(err);
-			}
-			callback();
-		});
-	} else {
-		callback();
-	}
+function registerShutdownHandlers(server, options = {}) {
+  if (!server || typeof server.close !== 'function') {
+    throw new TypeError('server should provide a close(callback) function');
+  }
+
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const fatalTimeoutMs = options.fatalTimeoutMs ?? Math.min(timeoutMs, 30_000);
+  const cleanup = options.cleanup ?? (async () => {});
+  const forceClose = options.forceClose;
+  const onFatal = options.onFatal;
+  const exit = options.exit ?? process.exit.bind(process);
+
+  validateTimeout('timeoutMs', timeoutMs);
+  validateTimeout('fatalTimeoutMs', fatalTimeoutMs);
+  validateFunction('cleanup', cleanup);
+  validateFunction('forceClose', forceClose);
+  validateFunction('onFatal', onFatal);
+  validateFunction('exit', exit);
+
+  let shuttingDown = false;
+  let finished = false;
+  let exitCode = 0;
+  let timer;
+  let timerDeadline = Infinity;
+  let resolveCompletion;
+  let completion;
+  let context;
+
+  function dispose() {
+    process.removeListener('SIGTERM', onSigterm);
+    process.removeListener('SIGINT', onSigint);
+    process.removeListener('uncaughtException', onUncaughtException);
+    process.removeListener('unhandledRejection', onUnhandledRejection);
+  }
+
+  function reportFatal(error, origin) {
+    exitCode = 1;
+    context.error = error;
+    context.origin = origin;
+    context.fatal = true;
+
+    if (onFatal) {
+      try {
+        onFatal(error, origin);
+      } catch (reportingError) {
+        console.error(reportingError);
+      }
+    }
+  }
+
+  function complete(code) {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timer);
+    dispose();
+    resolveCompletion(code);
+    exit(code);
+  }
+
+  function forceShutdown() {
+    if (finished) return;
+
+    const forcedContext = { ...context, forced: true };
+
+    try {
+      forceClose?.(forcedContext);
+    } catch (error) {
+      reportFatal(error, 'forceClose');
+    }
+
+    try {
+      server.closeAllConnections?.();
+    } catch (error) {
+      reportFatal(error, 'server.closeAllConnections');
+    }
+
+    complete(1);
+  }
+
+  function scheduleDeadline(delayMs) {
+    const deadline = Date.now() + delayMs;
+    if (deadline >= timerDeadline) return;
+
+    clearTimeout(timer);
+    timerDeadline = deadline;
+    timer = setTimeout(forceShutdown, delayMs);
+    timer.unref?.();
+  }
+
+  async function finishGracefully(serverError) {
+    if (finished) return;
+
+    if (serverError) {
+      reportFatal(serverError, 'server.close');
+    }
+
+    try {
+      await cleanup({ ...context, forced: false });
+    } catch (error) {
+      reportFatal(error, 'cleanup');
+    }
+
+    complete(exitCode);
+  }
+
+  function shutdown(request = {}) {
+    const reason = request.reason ?? 'manual';
+    const error = request.error;
+    const fatal = request.fatal ?? error !== undefined;
+
+    if (shuttingDown) {
+      if (fatal) {
+        const fatalError = normalizeError(error, `Fatal shutdown requested by ${reason}`);
+        reportFatal(fatalError, reason);
+        scheduleDeadline(fatalTimeoutMs);
+      }
+      return completion;
+    }
+
+    shuttingDown = true;
+    exitCode = fatal ? 1 : 0;
+    context = { reason, error: undefined, origin: undefined, fatal, forced: false };
+    completion = new Promise(resolve => {
+      resolveCompletion = resolve;
+    });
+
+    setStatus(503);
+
+    if (fatal) {
+      const fatalError = normalizeError(error, `Fatal shutdown requested by ${reason}`);
+      reportFatal(fatalError, reason);
+    }
+
+    scheduleDeadline(fatal ? fatalTimeoutMs : timeoutMs);
+
+    try {
+      server.close(serverError => {
+        void finishGracefully(serverError);
+      });
+    } catch (serverError) {
+      void finishGracefully(serverError);
+    }
+
+    return completion;
+  }
+
+  function close() {
+    return shutdown({ reason: 'manual' });
+  }
+
+  function onSigterm() {
+    void shutdown({ reason: 'SIGTERM' });
+  }
+
+  function onSigint() {
+    void shutdown({ reason: 'SIGINT' });
+  }
+
+  function onUncaughtException(error, origin) {
+    void shutdown({ reason: origin ?? 'uncaughtException', error, fatal: true });
+  }
+
+  function onUnhandledRejection(reason) {
+    const error = normalizeError(reason, 'Unhandled promise rejection');
+    void shutdown({ reason: 'unhandledRejection', error, fatal: true });
+  }
+
+  process.once('SIGTERM', onSigterm);
+  process.once('SIGINT', onSigint);
+  process.once('uncaughtException', onUncaughtException);
+  process.once('unhandledRejection', onUnhandledRejection);
+
+  return {
+    close,
+    dispose,
+    shutdown,
+    get isShuttingDown() {
+      return shuttingDown;
+    },
+  };
 }
 
 module.exports = {
-	setStatus: setStatus,
-	getStatus: getStatus,
-	route: route,
-	shutdown: shutdown,
-	enableTooBusy: enableTooBusy,
-	gracefulShutdownKeepaliveConnections: gracefulShutdownKeepaliveConnections,
+  setStatus,
+  getStatus,
+  route,
+  registerShutdownHandlers,
 };

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "connect-ready",
-  "version": "1.0.13",
-  "description": "express route that indicates whether a service is ready or not",
+  "version": "2.0.0",
+  "description": "Kubernetes readiness and graceful shutdown for Node.js HTTP services",
   "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
-    "test": "mocha test",
-    "test:cover": "c8 --reporter=lcov --reporter=text npm test",
-    "lint": "eslint *.js"
+    "test": "node --test",
+    "test:cover": "node --experimental-test-coverage --test",
+    "lint": "node --check index.js && node --check test/index.test.js"
   },
   "repository": {
     "type": "git",
@@ -22,19 +30,5 @@
   "bugs": {
     "url": "https://github.com/dcolens/connect-ready/issues"
   },
-  "homepage": "https://github.com/dcolens/connect-ready#readme",
-  "devDependencies": {
-    "c8": "^7.11.0",
-    "coveralls": "^3.1.1",
-    "eslint": "^8.9.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "mocha": "^9.2.0",
-    "prettier": "^2.5.1",
-    "toobusy-js": "^0.5.1"
-  },
-  "optionalDependencies": {
-    "toobusy-js": "^0.5.1"
-  },
-  "dependencies": {}
+  "homepage": "https://github.com/dcolens/connect-ready#readme"
 }

package/.editorconfig

@@ -1,14 +0,0 @@
-# EditorConfig is awesome: http://EditorConfig.org
-
-root = true
-
-[*.js]
-charset = utf-8
-end_of_line = lf
-indent_size = 1
-indent_style = tab
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false

package/.eslintrc.json

@@ -1,4 +0,0 @@
-{
-  "extends": ["plugin:prettier/recommended"],
-  "parserOptions": { "ecmaVersion": 2018 }
-}

package/.github/workflows/npm-publish.yml

@@ -1,41 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-    
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    
-    strategy:
-      matrix:
-        node-version: [10.x, 12.x, 14.x, 15.x]
-        
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm test
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
-        with:
-          node-version: 14
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
-