@openstatus/health-tcp 0.1.4-dev.0

package/README.md

@@ -0,0 +1,71 @@
+# @openstatus/health-tcp
+
+TCP probe for [`@openstatus/health`](https://jsr.io/@openstatus/health).
+Opens a socket to `host:port`, reports `ok` as soon as the connection is
+established and closes it again — the check for every dependency that has
+no client library or HTTP endpoint: an SMTP relay, a Memcached node, a
+database behind a bastion, a legacy service on a bare port.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-tcp
+npm install @openstatus/health @openstatus/health-tcp
+```
+
+```ts
+import { createHealthHandler } from "@openstatus/health";
+import { tcpProbe } from "@openstatus/health-tcp";
+
+Deno.serve(
+  createHealthHandler({
+    probes: [
+      tcpProbe({ name: "smtp", host: "smtp.example.com", port: 587 }),
+      tcpProbe({ name: "memcached", host: "10.0.0.5", port: 11211 }),
+    ],
+  }),
+);
+```
+
+A successful connect proves the host resolves, the network path is open
+and something is listening on the port; it does not prove that the
+listener speaks the protocol you expect or would accept your credentials.
+Refused and unreachable connections fail the check with the socket error,
+and a `timeoutMs` destroys a socket that is still waiting for the
+handshake. Give each probe a `name` when you mount more than one — they all
+default to `tcp`, and duplicate names are rejected.
+
+```ts
+tcpProbe({
+  host: "smtp.example.com",
+  port: 587,
+  // optional overrides from the Probe contract
+  name: "smtp",
+  critical: true,
+  timeoutMs: 1000,
+  skip: () => env.SMTP_HOST == null,
+});
+```
+
+Non-critical by default: a bare port check rarely maps to a dependency
+requests cannot proceed without. Set `critical: true` when it does.
+
+This probe uses `node:net`, so it runs on Node.js, Deno and Bun but not on
+edge runtimes without a socket API. The connect function is typed
+structurally, and `connect` can be replaced for tests.
+
+## About openstatus
+
+[openstatus](https://www.openstatus.dev/) is the open-source uptime monitoring
+and status page platform. This package is part of
+[`@openstatus/health`](https://github.com/openstatusHQ/health), the `/health`
+endpoints behind openstatus's own services, extracted so any JavaScript server
+can expose one. Point an
+[openstatus monitor](https://www.openstatus.dev/docs/reference/http-monitor)
+at the endpoint and assert on `status` in the body to be alerted on
+`degraded` before it becomes `unhealthy`.
+
+Source: [github.com/openstatusHQ/health](https://github.com/openstatusHQ/health).
+Issues and PRs welcome.
+
+## License
+
+[MIT](https://github.com/openstatusHQ/health/blob/main/LICENSE)

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,39 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_net = require_rolldown_runtime.__toESM(require("node:net"));
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const tcpDefaultName = "tcp";
+/** A probe that connects to `host:port`; non-critical by default. Throws `ProbeConfigError` for an empty `host` or an invalid `port`. */
+function tcpProbe(options) {
+	const { host, port } = options;
+	if (typeof host !== "string" || host.length === 0) throw new __openstatus_health.ProbeConfigError("tcpProbe", "host", typeof host !== "string" ? `must be a string, got ${String(host)}` : "must not be empty");
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new __openstatus_health.ProbeConfigError("tcpProbe", "port", `must be an integer between 1 and 65535, got ${String(port)}`);
+	const connect = options.connect ?? node_net.connect;
+	return {
+		name: options.name ?? tcpDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: (signal) => new Promise((resolve, reject) => {
+			const socket = connect({
+				host,
+				port
+			});
+			const settle = (finish) => {
+				signal.removeEventListener("abort", onAbort);
+				socket.destroy();
+				finish();
+			};
+			const onAbort = () => settle(() => reject(signal.reason));
+			socket.once("connect", () => settle(resolve));
+			socket.once("error", (error) => settle(() => reject(error ?? /* @__PURE__ */ new Error("socket error"))));
+			signal.addEventListener("abort", onAbort, { once: true });
+		})
+	};
+}
+
+//#endregion
+exports.tcpDefaultName = tcpDefaultName;
+exports.tcpProbe = tcpProbe;

package/dist/mod.d.cts

@@ -0,0 +1,33 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const tcpDefaultName = "tcp";
+/** The subset of a `net.Socket` the probe uses. */
+interface TcpLikeSocket {
+  /** Listen once for `connect` (established) or `error` (failed). */
+  once(event: "connect" | "error", listener: (error?: Error) => void): TcpLikeSocket;
+  /** Close the socket. */
+  destroy(): void;
+}
+/** What the probe connects with; `net.connect` by default. */
+type TcpConnect = (options: {
+  readonly host: string;
+  readonly port: number;
+}) => TcpLikeSocket;
+/** Options for `tcpProbe()`. */
+interface TcpProbeOptions extends ProbeOverrides {
+  /** Hostname or IP address. */
+  readonly host: string;
+  /** Port, 1–65535. */
+  readonly port: number;
+  /** Replacement `connect`, for tests. */
+  readonly connect?: TcpConnect;
+}
+/** A probe that connects to `host:port`; non-critical by default. Throws `ProbeConfigError` for an empty `host` or an invalid `port`. */
+declare function tcpProbe(options: TcpProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { TcpConnect, TcpLikeSocket, TcpProbeOptions, tcpDefaultName, tcpProbe };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;AAoDA;AAAwB,cA7BX,cAAA,GA6BW,KAAA;;AAA4B,UA1BnC,aAAA,CA0BmC;EAAK;sDAtBlC,iBAClB;;;;;KAMO,UAAA;;;MAEP;;UAGY,eAAA,SAAwB;;;;;;qBAMpB;;;iBAIL,QAAA,UAAkB,kBAAkB"}

package/dist/mod.d.ts

@@ -0,0 +1,33 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const tcpDefaultName = "tcp";
+/** The subset of a `net.Socket` the probe uses. */
+interface TcpLikeSocket {
+  /** Listen once for `connect` (established) or `error` (failed). */
+  once(event: "connect" | "error", listener: (error?: Error) => void): TcpLikeSocket;
+  /** Close the socket. */
+  destroy(): void;
+}
+/** What the probe connects with; `net.connect` by default. */
+type TcpConnect = (options: {
+  readonly host: string;
+  readonly port: number;
+}) => TcpLikeSocket;
+/** Options for `tcpProbe()`. */
+interface TcpProbeOptions extends ProbeOverrides {
+  /** Hostname or IP address. */
+  readonly host: string;
+  /** Port, 1–65535. */
+  readonly port: number;
+  /** Replacement `connect`, for tests. */
+  readonly connect?: TcpConnect;
+}
+/** A probe that connects to `host:port`; non-critical by default. Throws `ProbeConfigError` for an empty `host` or an invalid `port`. */
+declare function tcpProbe(options: TcpProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { TcpConnect, TcpLikeSocket, TcpProbeOptions, tcpDefaultName, tcpProbe };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;AAoDA;AAAwB,cA7BX,cAAA,GA6BW,KAAA;;AAA4B,UA1BnC,aAAA,CA0BmC;EAAK;sDAtBlC,iBAClB;;;;;KAMO,UAAA;;;MAEP;;UAGY,eAAA,SAAwB;;;;;;qBAMpB;;;iBAIL,QAAA,UAAkB,kBAAkB"}

package/dist/mod.js

@@ -0,0 +1,38 @@
+import { connect } from "node:net";
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const tcpDefaultName = "tcp";
+/** A probe that connects to `host:port`; non-critical by default. Throws `ProbeConfigError` for an empty `host` or an invalid `port`. */
+function tcpProbe(options) {
+	const { host, port } = options;
+	if (typeof host !== "string" || host.length === 0) throw new ProbeConfigError("tcpProbe", "host", typeof host !== "string" ? `must be a string, got ${String(host)}` : "must not be empty");
+	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new ProbeConfigError("tcpProbe", "port", `must be an integer between 1 and 65535, got ${String(port)}`);
+	const connect$1 = options.connect ?? connect;
+	return {
+		name: options.name ?? tcpDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: (signal) => new Promise((resolve, reject) => {
+			const socket = connect$1({
+				host,
+				port
+			});
+			const settle = (finish) => {
+				signal.removeEventListener("abort", onAbort);
+				socket.destroy();
+				finish();
+			};
+			const onAbort = () => settle(() => reject(signal.reason));
+			socket.once("connect", () => settle(resolve));
+			socket.once("error", (error) => settle(() => reject(error ?? /* @__PURE__ */ new Error("socket error"))));
+			signal.addEventListener("abort", onAbort, { once: true });
+		})
+	};
+}
+
+//#endregion
+export { tcpDefaultName, tcpProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: TcpProbeOptions","connect","netConnect","finish: () => void"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * TCP probe for `@openstatus/health`: opens a socket to `host:port` and\n * closes it again, for any dependency without a client library.\n *\n * ```ts\n * import { tcpProbe } from \"@openstatus/health-tcp\";\n *\n * const probe = tcpProbe({ host: \"smtp.example.com\", port: 587 });\n * ```\n *\n * Node.js, Deno and Bun only: it uses `node:net`.\n *\n * @module\n */\n\nimport { connect as netConnect } from \"node:net\";\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const tcpDefaultName = \"tcp\";\n\n/** The subset of a `net.Socket` the probe uses. */\nexport interface TcpLikeSocket {\n  /** Listen once for `connect` (established) or `error` (failed). */\n  once(\n    event: \"connect\" | \"error\",\n    listener: (error?: Error) => void,\n  ): TcpLikeSocket;\n  /** Close the socket. */\n  destroy(): void;\n}\n\n/** What the probe connects with; `net.connect` by default. */\nexport type TcpConnect = (\n  options: { readonly host: string; readonly port: number },\n) => TcpLikeSocket;\n\n/** Options for `tcpProbe()`. */\nexport interface TcpProbeOptions extends ProbeOverrides {\n  /** Hostname or IP address. */\n  readonly host: string;\n  /** Port, 1–65535. */\n  readonly port: number;\n  /** Replacement `connect`, for tests. */\n  readonly connect?: TcpConnect;\n}\n\n/** A probe that connects to `host:port`; non-critical by default. Throws `ProbeConfigError` for an empty `host` or an invalid `port`. */\nexport function tcpProbe(options: TcpProbeOptions): Probe {\n  const { host, port } = options;\n  if (typeof host !== \"string\" || host.length === 0) {\n    throw new ProbeConfigError(\n      \"tcpProbe\",\n      \"host\",\n      typeof host !== \"string\"\n        ? `must be a string, got ${String(host)}`\n        : \"must not be empty\",\n    );\n  }\n  if (!Number.isInteger(port) || port < 1 || port > 65535) {\n    throw new ProbeConfigError(\n      \"tcpProbe\",\n      \"port\",\n      `must be an integer between 1 and 65535, got ${String(port)}`,\n    );\n  }\n  const connect = options.connect ?? netConnect;\n  return {\n    name: options.name ?? tcpDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: (signal) =>\n      new Promise<void>((resolve, reject) => {\n        const socket = connect({ host, port });\n        const settle = (finish: () => void) => {\n          signal.removeEventListener(\"abort\", onAbort);\n          socket.destroy();\n          finish();\n        };\n        const onAbort = () => settle(() => reject(signal.reason));\n        socket.once(\"connect\", () => settle(resolve));\n        socket.once(\n          \"error\",\n          (error) => settle(() => reject(error ?? new Error(\"socket error\"))),\n        );\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n      }),\n  };\n}\n"],"mappings":";;;;;AAuBA,MAAa,iBAAiB;;AA6B9B,SAAgB,SAASA,SAAiC;CACxD,MAAM,EAAE,MAAM,MAAM,GAAG;AACvB,YAAW,SAAS,YAAY,KAAK,WAAW,EAC9C,OAAM,IAAI,iBACR,YACA,eACO,SAAS,YACX,wBAAwB,OAAO,KAAK,CAAC,IACtC;AAGR,MAAK,OAAO,UAAU,KAAK,IAAI,OAAO,KAAK,OAAO,MAChD,OAAM,IAAI,iBACR,YACA,SACC,8CAA8C,OAAO,KAAK,CAAC;CAGhE,MAAMC,YAAU,QAAQ,WAAWC;AACnC,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,CAAC,WACJ,IAAI,QAAc,CAAC,SAAS,WAAW;GACrC,MAAM,SAAS,UAAQ;IAAE;IAAM;GAAM,EAAC;GACtC,MAAM,SAAS,CAACC,WAAuB;AACrC,WAAO,oBAAoB,SAAS,QAAQ;AAC5C,WAAO,SAAS;AAChB,YAAQ;GACT;GACD,MAAM,UAAU,MAAM,OAAO,MAAM,OAAO,OAAO,OAAO,CAAC;AACzD,UAAO,KAAK,WAAW,MAAM,OAAO,QAAQ,CAAC;AAC7C,UAAO,KACL,SACA,CAAC,UAAU,OAAO,MAAM,OAAO,yBAAS,IAAI,MAAM,gBAAgB,CAAC,CACpE;AACD,UAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAM,EAAC;EAC1D;CACJ;AACF"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@openstatus/health-tcp",
+  "version": "0.1.4-dev.0",
+  "description": "TCP connect probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "tcp",
+    "socket",
+    "network",
+    "port"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "openstatus",
+    "url": "https://www.openstatus.dev/"
+  },
+  "homepage": "https://github.com/openstatusHQ/health",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openstatusHQ/health.git",
+    "directory": "packages/tcp/"
+  },
+  "bugs": {
+    "url": "https://github.com/openstatusHQ/health/issues"
+  },
+  "type": "module",
+  "module": "./dist/mod.js",
+  "main": "./dist/mod.cjs",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@openstatus/health": "^0.1.4-dev.0"
+  },
+  "devDependencies": {
+    "@types/node": ">=22",
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}