@remit/logger-lambda 0.0.11 → 0.0.12

package/README.md

@@ -92,5 +92,5 @@ one adds to the bindings of the one it runs inside.
 | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | `LOG_LEVEL`          | `info`  | `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `silent`. An unrecognised value logs one warning and falls back to the default. |
 | `REMIT_SERVICE_NAME` | `remit` | The `service` field on every line. Stamped into each service bundle at build time by `npm-scripts/docker-bundle.mjs`.                 |
-| `METRICS_PORT`       | `9464`  | Port `startMetricsServer` binds. |
+| `METRICS_PORT`       | `9464`  | Port `startMetricsServer` binds. Empty is unset and takes the default; anything that is not a port number in 0–65535 logs one error and serves no metrics, rather than falling back. A service that cannot be scraped is a smaller failure than one that reports on the wrong port. |
 | `METRICS_HOST`       | `0.0.0.0` | Interface `startMetricsServer` binds. Set `127.0.0.1` when the service runs as a host process rather than a container. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/logger-lambda",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/metrics.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import {
@@ -402,4 +403,80 @@ describe("the /metrics endpoint", () => {
 		delete process.env.METRICS_PORT;
 		assert.ok((server.address() as AddressInfo).port > 0);
 	});
+
+	const startWithMetricsPort = (value: string, reported: Error[]) => {
+		process.env.METRICS_PORT = value;
+		try {
+			return startMetricsServer({
+				host: "127.0.0.1",
+				onError: (error) => reported.push(error),
+			});
+		} finally {
+			delete process.env.METRICS_PORT;
+		}
+	};
+
+	for (const value of ["nine-thousand", "99999", "-1", "9464.5"]) {
+		it(`refuses to bind METRICS_PORT=${value} instead of taking the worker down`, () => {
+			const reported: Error[] = [];
+			const server = startWithMetricsPort(value, reported);
+			assert.equal(server.listening, false);
+			assert.equal(reported.length, 1);
+			assert.match(reported[0].message, /METRICS_PORT/);
+			assert.ok(reported[0].message.includes(value));
+		});
+	}
+
+	it("treats a blank METRICS_PORT as unconfigured", async () => {
+		const reported: Error[] = [];
+		const server = startWithMetricsPort("  ", reported);
+		servers.push(server);
+		const bound = await new Promise<boolean>((resolve) => {
+			server.once("listening", () => resolve(true));
+			server.once("error", () => resolve(false));
+		});
+		if (!bound) {
+			// 9464 is already taken on this host, which is itself proof the
+			// fallback resolved to it: an ephemeral port is never in use.
+			assert.match(String(reported[0]), /EADDRINUSE/);
+			return;
+		}
+		assert.deepEqual(reported, []);
+		assert.equal((server.address() as AddressInfo).port, DEFAULT_METRICS_PORT);
+	});
+
+	it("refuses an out-of-range port passed by a caller", () => {
+		const reported: Error[] = [];
+		const server = startMetricsServer({
+			port: 70000,
+			host: "127.0.0.1",
+			onError: (error) => reported.push(error),
+		});
+		assert.equal(server.listening, false);
+		assert.equal(reported.length, 1);
+		assert.match(reported[0].message, /70000/);
+	});
+
+	it("reports a malformed port as one JSON line on stderr by default", () => {
+		const written: string[] = [];
+		const restore = process.stderr.write.bind(process.stderr);
+		process.env.METRICS_PORT = "not-a-port";
+		process.stderr.write = ((chunk: string) => {
+			written.push(String(chunk));
+			return true;
+		}) as typeof process.stderr.write;
+		let server: Server;
+		try {
+			server = startMetricsServer({ host: "127.0.0.1" });
+		} finally {
+			process.stderr.write = restore;
+			delete process.env.METRICS_PORT;
+		}
+
+		assert.equal(server.listening, false);
+		assert.equal(written.length, 1);
+		const line = JSON.parse(written[0]) as { level: string; error: string };
+		assert.equal(line.level, "error");
+		assert.match(line.error, /not-a-port/);
+	});
 });

package/src/metrics.ts

@@ -230,6 +230,31 @@ const reportToStderr = (error: Error): void => {
 	);
 };
 
+const MAX_PORT = 65535;
+
+const isBindablePort = (port: number): boolean =>
+	Number.isInteger(port) && port >= 0 && port <= MAX_PORT;
+
+// `listen` rejects anything outside 0..65535 by throwing ERR_SOCKET_BAD_PORT
+// synchronously, which the `'error'` handler never sees. A blank value is a
+// variable someone left empty rather than a request for port 0, so it reads as
+// unset; anything else that does not parse is a typo worth naming.
+const configuredPort = (override: number | undefined): number | Error => {
+	if (override !== undefined) {
+		return isBindablePort(override)
+			? override
+			: new Error(`not a port number: ${override}`);
+	}
+	const configured = (process.env.METRICS_PORT ?? "").trim();
+	if (configured === "") {
+		return DEFAULT_METRICS_PORT;
+	}
+	const parsed = Number(configured);
+	return isBindablePort(parsed)
+		? parsed
+		: new Error(`METRICS_PORT is not a port number: ${configured}`);
+};
+
 /**
  * The listener D2 adds to each worker image, for `/metrics` alone. Bound to the
  * compose network and never published to the host: the only host ports in the
@@ -239,8 +264,10 @@ const reportToStderr = (error: Error): void => {
  * later tick, by which time the poll loop is already running, so an unhandled
  * `'error'` event here would kill a worker in the middle of syncing mail —
  * 9464 is the OpenTelemetry Prometheus exporter's default, so a collector on
- * the same host is a real trigger. An observability endpoint must never be able
- * to stop mail from arriving; absent metrics are the correct failure.
+ * the same host is a real trigger. A port that is not a port at all is refused
+ * the same way, before `listen` can throw it at the caller. An observability
+ * endpoint must never be able to stop mail from arriving; absent metrics are
+ * the correct failure.
  *
  * Unreferenced from the event loop, so it never keeps a worker alive past the
  * end of its poll loop.
@@ -248,14 +275,18 @@ const reportToStderr = (error: Error): void => {
 export const startMetricsServer = (
 	options: MetricsServerOptions = {},
 ): Server => {
-	const port =
-		options.port ??
-		Number(process.env.METRICS_PORT ?? String(DEFAULT_METRICS_PORT));
 	const host = options.host ?? process.env.METRICS_HOST ?? "0.0.0.0";
 	const onError = options.onError ?? reportToStderr;
 	const server = createServer(createMetricsRequestListener());
 	server.unref();
 	server.on("error", onError);
+
+	const port = configuredPort(options.port);
+	if (port instanceof Error) {
+		onError(port);
+		return server;
+	}
+
 	server.listen(port, host);
 	return server;
 };