@openstatus/health-kafka 0.1.4-dev.0

package/README.md

@@ -0,0 +1,75 @@
+# @openstatus/health-kafka
+
+[Apache Kafka](https://kafka.apache.org/) probe for
+[`@openstatus/health`](https://jsr.io/@openstatus/health). Describes the
+cluster through a connected [KafkaJS](https://kafka.js.org/)-style `Admin`
+client — one metadata request to the broker — and fails the check when no
+broker answers or the cluster reports none.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-kafka
+npm install @openstatus/health @openstatus/health-kafka
+```
+
+```ts
+import { Kafka } from "kafkajs";
+import { createHealthHandler } from "@openstatus/health";
+import { kafkaProbe } from "@openstatus/health-kafka";
+
+const kafka = new Kafka({ brokers: env.KAFKA_BROKERS.split(",") });
+const admin = kafka.admin();
+await admin.connect();
+
+Deno.serve(
+  createHealthHandler({ probes: [kafkaProbe({ admin })] }),
+);
+```
+
+Connect the `Admin` client once at start-up and keep it: KafkaJS only
+sends the metadata request over an established connection, and creating
+one per health request would add a broker handshake to every poll.
+`describeCluster()` needs no topic and no ACL beyond `Describe` on the
+cluster, so it works with the most restricted credentials. The
+`@confluentinc/kafka-javascript` KafkaJS-compatible `Admin` does not
+implement `describeCluster()`, so it is not supported.
+
+```ts
+kafkaProbe({
+  admin,
+  // optional overrides from the Probe contract
+  name: "events",
+  critical: true,
+  timeoutMs: 2000,
+  skip: () => env.KAFKA_BROKERS == null,
+});
+```
+
+Non-critical by default: Kafka usually carries events processed out of
+band, so an outage degrades the report instead of taking the service out
+of rotation. Set `critical: true` when requests cannot complete without
+producing.
+
+The admin client is typed structurally as
+`{ describeCluster(): PromiseLike<{ brokers: [...] }> }`, so `kafkajs` is an
+optional peer dependency for its types only and the probe adds no runtime
+import of it. The factory throws
+`ProbeConfigError` at construction when the client has no
+`describeCluster()`.
+
+## 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,34 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const kafkaDefaultName = "kafka";
+/** A probe that describes the cluster and expects at least one broker; non-critical by default. Throws `ProbeConfigError` without `describeCluster()`. */
+function kafkaProbe(options) {
+	const admin = options.admin;
+	if (typeof admin?.describeCluster !== "function") throw new __openstatus_health.ProbeConfigError("kafkaProbe", "admin", `must expose describeCluster(), got ${describe(admin)}`);
+	return {
+		name: options.name ?? kafkaDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const cluster = await admin.describeCluster();
+			const brokers = cluster?.brokers;
+			if (!Array.isArray(brokers)) throw new Error("unexpected response shape");
+			if (brokers.length === 0) throw new Error("no brokers in cluster");
+			return { brokers: brokers.length };
+		}
+	};
+}
+function describe(admin) {
+	if (admin == null) return String(admin);
+	if (typeof admin !== "object") return typeof admin;
+	const keys = Object.keys(admin);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.kafkaDefaultName = kafkaDefaultName;
+exports.kafkaProbe = kafkaProbe;

package/dist/mod.d.cts

@@ -0,0 +1,29 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const kafkaDefaultName = "kafka";
+/** What `describeCluster()` resolves to. */
+interface KafkaClusterDescription {
+  /** The brokers currently in the cluster. */
+  readonly brokers: readonly {
+    readonly nodeId: number;
+  }[];
+}
+/** The subset of a KafkaJS `Admin` client the probe uses. */
+interface KafkaLikeAdmin {
+  /** Fetch cluster metadata from the connected broker. */
+  describeCluster(): PromiseLike<KafkaClusterDescription>;
+}
+/** Options for `kafkaProbe()`. */
+interface KafkaProbeOptions extends ProbeOverrides {
+  /** A connected `kafkajs` `Admin` client. */
+  readonly admin: KafkaLikeAdmin;
+}
+/** A probe that describes the cluster and expects at least one broker; non-critical by default. Throws `ProbeConfigError` without `describeCluster()`. */
+declare function kafkaProbe(options: KafkaProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { KafkaClusterDescription, KafkaLikeAdmin, KafkaProbeOptions, kafkaDefaultName, kafkaProbe };
+//# 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":";;;;;AA4CoC,cArBvB,gBAAA,GAqBuB,OAAA;;AAAyB,UAlB5C,uBAAA,CAkB4C;;;;;;;UAZ5C,cAAA;;qBAEI,YAAY;;;UAIhB,iBAAA,SAA0B;;kBAEzB;;;iBAIF,UAAA,UAAoB,oBAAoB"}

package/dist/mod.d.ts

@@ -0,0 +1,29 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const kafkaDefaultName = "kafka";
+/** What `describeCluster()` resolves to. */
+interface KafkaClusterDescription {
+  /** The brokers currently in the cluster. */
+  readonly brokers: readonly {
+    readonly nodeId: number;
+  }[];
+}
+/** The subset of a KafkaJS `Admin` client the probe uses. */
+interface KafkaLikeAdmin {
+  /** Fetch cluster metadata from the connected broker. */
+  describeCluster(): PromiseLike<KafkaClusterDescription>;
+}
+/** Options for `kafkaProbe()`. */
+interface KafkaProbeOptions extends ProbeOverrides {
+  /** A connected `kafkajs` `Admin` client. */
+  readonly admin: KafkaLikeAdmin;
+}
+/** A probe that describes the cluster and expects at least one broker; non-critical by default. Throws `ProbeConfigError` without `describeCluster()`. */
+declare function kafkaProbe(options: KafkaProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { KafkaClusterDescription, KafkaLikeAdmin, KafkaProbeOptions, kafkaDefaultName, kafkaProbe };
+//# 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":";;;;;AA4CoC,cArBvB,gBAAA,GAqBuB,OAAA;;AAAyB,UAlB5C,uBAAA,CAkB4C;;;;;;;UAZ5C,cAAA;;qBAEI,YAAY;;;UAIhB,iBAAA,SAA0B;;kBAEzB;;;iBAIF,UAAA,UAAoB,oBAAoB"}

package/dist/mod.js

@@ -0,0 +1,33 @@
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const kafkaDefaultName = "kafka";
+/** A probe that describes the cluster and expects at least one broker; non-critical by default. Throws `ProbeConfigError` without `describeCluster()`. */
+function kafkaProbe(options) {
+	const admin = options.admin;
+	if (typeof admin?.describeCluster !== "function") throw new ProbeConfigError("kafkaProbe", "admin", `must expose describeCluster(), got ${describe(admin)}`);
+	return {
+		name: options.name ?? kafkaDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const cluster = await admin.describeCluster();
+			const brokers = cluster?.brokers;
+			if (!Array.isArray(brokers)) throw new Error("unexpected response shape");
+			if (brokers.length === 0) throw new Error("no brokers in cluster");
+			return { brokers: brokers.length };
+		}
+	};
+}
+function describe(admin) {
+	if (admin == null) return String(admin);
+	if (typeof admin !== "object") return typeof admin;
+	const keys = Object.keys(admin);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { kafkaDefaultName, kafkaProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: KafkaProbeOptions","admin: KafkaLikeAdmin"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * Kafka probe for `@openstatus/health`: describes the cluster through a\n * connected KafkaJS-style `Admin` client and fails when no broker answers.\n *\n * ```ts\n * import { Kafka } from \"kafkajs\";\n * import { kafkaProbe } from \"@openstatus/health-kafka\";\n *\n * const admin = new Kafka({ brokers }).admin();\n * await admin.connect();\n * const probe = kafkaProbe({ admin });\n * ```\n *\n * @module\n */\n\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const kafkaDefaultName = \"kafka\";\n\n/** What `describeCluster()` resolves to. */\nexport interface KafkaClusterDescription {\n  /** The brokers currently in the cluster. */\n  readonly brokers: readonly { readonly nodeId: number }[];\n}\n\n/** The subset of a KafkaJS `Admin` client the probe uses. */\nexport interface KafkaLikeAdmin {\n  /** Fetch cluster metadata from the connected broker. */\n  describeCluster(): PromiseLike<KafkaClusterDescription>;\n}\n\n/** Options for `kafkaProbe()`. */\nexport interface KafkaProbeOptions extends ProbeOverrides {\n  /** A connected `kafkajs` `Admin` client. */\n  readonly admin: KafkaLikeAdmin;\n}\n\n/** A probe that describes the cluster and expects at least one broker; non-critical by default. Throws `ProbeConfigError` without `describeCluster()`. */\nexport function kafkaProbe(options: KafkaProbeOptions): Probe {\n  const admin = options.admin;\n  if (typeof admin?.describeCluster !== \"function\") {\n    throw new ProbeConfigError(\n      \"kafkaProbe\",\n      \"admin\",\n      `must expose describeCluster(), got ${describe(admin)}`,\n    );\n  }\n  return {\n    name: options.name ?? kafkaDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async () => {\n      const cluster = await admin.describeCluster();\n      const brokers = cluster?.brokers;\n      if (!Array.isArray(brokers)) throw new Error(\"unexpected response shape\");\n      if (brokers.length === 0) throw new Error(\"no brokers in cluster\");\n      return { brokers: brokers.length };\n    },\n  };\n}\n\nfunction describe(admin: KafkaLikeAdmin): string {\n  if (admin == null) return String(admin);\n  if (typeof admin !== \"object\") return typeof admin;\n  const keys = Object.keys(admin);\n  return keys.length === 0\n    ? \"an object with no keys\"\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;AAuBA,MAAa,mBAAmB;;AAqBhC,SAAgB,WAAWA,SAAmC;CAC5D,MAAM,QAAQ,QAAQ;AACtB,YAAW,OAAO,oBAAoB,WACpC,OAAM,IAAI,iBACR,cACA,UACC,qCAAqC,SAAS,MAAM,CAAC;AAG1D,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,YAAY;GACf,MAAM,UAAU,MAAM,MAAM,iBAAiB;GAC7C,MAAM,UAAU,SAAS;AACzB,QAAK,MAAM,QAAQ,QAAQ,CAAE,OAAM,IAAI,MAAM;AAC7C,OAAI,QAAQ,WAAW,EAAG,OAAM,IAAI,MAAM;AAC1C,UAAO,EAAE,SAAS,QAAQ,OAAQ;EACnC;CACF;AACF;AAED,SAAS,SAASC,OAA+B;AAC/C,KAAI,SAAS,KAAM,QAAO,OAAO,MAAM;AACvC,YAAW,UAAU,SAAU,eAAc;CAC7C,MAAM,OAAO,OAAO,KAAK,MAAM;AAC/B,QAAO,KAAK,WAAW,IACnB,4BACC,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@openstatus/health-kafka",
+  "version": "0.1.4-dev.0",
+  "description": "Kafka probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "kafka",
+    "kafkajs",
+    "messaging",
+    "streaming"
+  ],
+  "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/kafka/"
+  },
+  "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",
+    "kafkajs": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "kafkajs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}