@openstatus/health-grpc 0.1.4-dev.0

package/README.md

@@ -0,0 +1,79 @@
+# @openstatus/health-grpc
+
+gRPC probe for [`@openstatus/health`](https://jsr.io/@openstatus/health).
+Calls the standard
+[`grpc.health.v1.Health/Check`](https://github.com/grpc/grpc/blob/master/doc/health-checking.md)
+method through a generated `@grpc/grpc-js` client and fails the check
+unless the server answers `SERVING` — for every upstream that speaks gRPC
+and implements the health protocol, which most do.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-grpc
+npm install @openstatus/health @openstatus/health-grpc grpc-health-check @grpc/grpc-js
+```
+
+```ts
+import { credentials } from "@grpc/grpc-js";
+import { HealthClient } from "grpc-health-check";
+import { createHealthHandler } from "@openstatus/health";
+import { grpcProbe } from "@openstatus/health-grpc";
+
+const client = new HealthClient(env.ORDERS_GRPC_ADDR, credentials.createInsecure());
+
+Deno.serve(
+  createHealthHandler({
+    probes: [grpcProbe({ client, service: "orders.Orders" })],
+  }),
+);
+```
+
+Any client with `check(request, callback)` works: the `HealthClient` from
+[`grpc-health-check`](https://github.com/grpc/grpc-node/tree/master/packages/grpc-health-check),
+stubs generated from `health.proto` with `@grpc/proto-loader` or
+`ts-proto`'s grpc-js output. `service` names the service to ask about;
+the default empty string asks about the server as a whole. The probe
+accepts the status as the enum number (`1`) or its name (`"SERVING"`),
+whichever way the stubs were generated, and reports `NOT_SERVING`,
+`SERVICE_UNKNOWN` or a transport error otherwise. A `timeoutMs` cancels
+the call in flight. Reuse the client your application already holds: a
+grpc-js channel reconnects on its own and one client per process is the
+intended pattern.
+
+```ts
+grpcProbe({
+  client,
+  service: "orders.Orders",
+  // optional overrides from the Probe contract
+  name: "orders",
+  critical: true,
+  timeoutMs: 1000,
+  skip: () => env.ORDERS_GRPC_ADDR == null,
+});
+```
+
+Non-critical by default: an upstream that is down degrades the report
+instead of taking this service out of rotation with it. Set
+`critical: true` when requests cannot be served without that upstream.
+
+The client is typed structurally as `{ check(request, callback) }`, so
+`@grpc/grpc-js` 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 `check()`.
+
+## 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,59 @@
+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 grpcDefaultName = "grpc";
+/** Service checked when `service` is unset: the empty string means the server as a whole. */
+const grpcDefaultService = "";
+/** A probe that calls `Health/Check` and expects `SERVING`; non-critical by default. Throws `ProbeConfigError` without `check()` or for a non-string `service`. */
+function grpcProbe(options) {
+	const client = options.client;
+	if (typeof client?.check !== "function") throw new __openstatus_health.ProbeConfigError("grpcProbe", "client", `must expose check(), got ${describe(client)}`);
+	const service = options.service === void 0 ? grpcDefaultService : options.service;
+	if (typeof service !== "string") throw new __openstatus_health.ProbeConfigError("grpcProbe", "service", `must be a string, got ${String(service)}`);
+	return {
+		name: options.name ?? grpcDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: (signal) => new Promise((resolve, reject) => {
+			signal.throwIfAborted();
+			const onAbort = () => {
+				call.cancel();
+				reject(signal.reason);
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			const call = client.check({ service }, (error, response) => {
+				signal.removeEventListener("abort", onAbort);
+				if (error != null) {
+					reject(error);
+					return;
+				}
+				const status = response?.status;
+				if (status === 1 || status === "SERVING") {
+					resolve();
+					return;
+				}
+				reject(/* @__PURE__ */ new Error(`serving status ${describeStatus(status)}`));
+			});
+		})
+	};
+}
+function describeStatus(status) {
+	if (status === 0 || status === "UNKNOWN") return "UNKNOWN";
+	if (status === 2 || status === "NOT_SERVING") return "NOT_SERVING";
+	if (status === 3 || status === "SERVICE_UNKNOWN") return "SERVICE_UNKNOWN";
+	return String(status);
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.grpcDefaultName = grpcDefaultName;
+exports.grpcDefaultService = grpcDefaultService;
+exports.grpcProbe = grpcProbe;

package/dist/mod.d.cts

@@ -0,0 +1,38 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const grpcDefaultName = "grpc";
+/** Service checked when `service` is unset: the empty string means the server as a whole. */
+declare const grpcDefaultService = "";
+/** What `Check` answers; `status` is `1` or `"SERVING"` when healthy, depending on how enums were loaded. */
+interface GrpcHealthCheckResponse {
+  /** The `ServingStatus` enum value. */
+  readonly status?: number | string;
+}
+/** The subset of a `ClientUnaryCall` the probe uses. */
+interface GrpcLikeCall {
+  /** Cancel the in-flight call. */
+  cancel(): void;
+}
+/** The subset of a generated `Health` client the probe uses. */
+interface GrpcLikeHealthClient {
+  /** Call `Health/Check` for `service`. */
+  check(request: {
+    readonly service: string;
+  }, callback: (error: Error | null, response?: GrpcHealthCheckResponse) => void): GrpcLikeCall;
+}
+/** Options for `grpcProbe()`. */
+interface GrpcProbeOptions extends ProbeOverrides {
+  /** A `grpc.health.v1.Health` client, e.g. from `grpc-health-check` or your generated stubs. */
+  readonly client: GrpcLikeHealthClient;
+  /** The service name to check. Default `grpcDefaultService`. */
+  readonly service?: string;
+}
+/** A probe that calls `Health/Check` and expects `SERVING`; non-critical by default. Throws `ProbeConfigError` without `check()` or for a non-string `service`. */
+declare function grpcProbe(options: GrpcProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { GrpcHealthCheckResponse, GrpcLikeCall, GrpcLikeHealthClient, GrpcProbeOptions, grpcDefaultName, grpcDefaultService, grpcProbe };
+//# 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":";;;;;AAoDmB,cA/BN,eAAA,GA+BM,MAAA;;AAFqC,cA3B3C,kBAAA,GA2B2C,EAAA;AAQxD;AAAyB,UAhCR,uBAAA,CAgCQ;EAAA;EAA0B,SAAG,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA;AAAK;;UA1B1C,YAAA;;;;;UAMA,oBAAA;;;;uBAKJ,yBACI,mCAEZ;;;UAIY,gBAAA,SAAyB;;mBAEvB;;;;;iBAMH,SAAA,UAAmB,mBAAmB"}

package/dist/mod.d.ts

@@ -0,0 +1,38 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const grpcDefaultName = "grpc";
+/** Service checked when `service` is unset: the empty string means the server as a whole. */
+declare const grpcDefaultService = "";
+/** What `Check` answers; `status` is `1` or `"SERVING"` when healthy, depending on how enums were loaded. */
+interface GrpcHealthCheckResponse {
+  /** The `ServingStatus` enum value. */
+  readonly status?: number | string;
+}
+/** The subset of a `ClientUnaryCall` the probe uses. */
+interface GrpcLikeCall {
+  /** Cancel the in-flight call. */
+  cancel(): void;
+}
+/** The subset of a generated `Health` client the probe uses. */
+interface GrpcLikeHealthClient {
+  /** Call `Health/Check` for `service`. */
+  check(request: {
+    readonly service: string;
+  }, callback: (error: Error | null, response?: GrpcHealthCheckResponse) => void): GrpcLikeCall;
+}
+/** Options for `grpcProbe()`. */
+interface GrpcProbeOptions extends ProbeOverrides {
+  /** A `grpc.health.v1.Health` client, e.g. from `grpc-health-check` or your generated stubs. */
+  readonly client: GrpcLikeHealthClient;
+  /** The service name to check. Default `grpcDefaultService`. */
+  readonly service?: string;
+}
+/** A probe that calls `Health/Check` and expects `SERVING`; non-critical by default. Throws `ProbeConfigError` without `check()` or for a non-string `service`. */
+declare function grpcProbe(options: GrpcProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { GrpcHealthCheckResponse, GrpcLikeCall, GrpcLikeHealthClient, GrpcProbeOptions, grpcDefaultName, grpcDefaultService, grpcProbe };
+//# 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":";;;;;AAoDmB,cA/BN,eAAA,GA+BM,MAAA;;AAFqC,cA3B3C,kBAAA,GA2B2C,EAAA;AAQxD;AAAyB,UAhCR,uBAAA,CAgCQ;EAAA;EAA0B,SAAG,MAAA,CAAA,EAAA,MAAA,GAAA,MAAA;AAAK;;UA1B1C,YAAA;;;;;UAMA,oBAAA;;;;uBAKJ,yBACI,mCAEZ;;;UAIY,gBAAA,SAAyB;;mBAEvB;;;;;iBAMH,SAAA,UAAmB,mBAAmB"}

package/dist/mod.js

@@ -0,0 +1,57 @@
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const grpcDefaultName = "grpc";
+/** Service checked when `service` is unset: the empty string means the server as a whole. */
+const grpcDefaultService = "";
+/** A probe that calls `Health/Check` and expects `SERVING`; non-critical by default. Throws `ProbeConfigError` without `check()` or for a non-string `service`. */
+function grpcProbe(options) {
+	const client = options.client;
+	if (typeof client?.check !== "function") throw new ProbeConfigError("grpcProbe", "client", `must expose check(), got ${describe(client)}`);
+	const service = options.service === void 0 ? grpcDefaultService : options.service;
+	if (typeof service !== "string") throw new ProbeConfigError("grpcProbe", "service", `must be a string, got ${String(service)}`);
+	return {
+		name: options.name ?? grpcDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: (signal) => new Promise((resolve, reject) => {
+			signal.throwIfAborted();
+			const onAbort = () => {
+				call.cancel();
+				reject(signal.reason);
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			const call = client.check({ service }, (error, response) => {
+				signal.removeEventListener("abort", onAbort);
+				if (error != null) {
+					reject(error);
+					return;
+				}
+				const status = response?.status;
+				if (status === 1 || status === "SERVING") {
+					resolve();
+					return;
+				}
+				reject(/* @__PURE__ */ new Error(`serving status ${describeStatus(status)}`));
+			});
+		})
+	};
+}
+function describeStatus(status) {
+	if (status === 0 || status === "UNKNOWN") return "UNKNOWN";
+	if (status === 2 || status === "NOT_SERVING") return "NOT_SERVING";
+	if (status === 3 || status === "SERVICE_UNKNOWN") return "SERVICE_UNKNOWN";
+	return String(status);
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { grpcDefaultName, grpcDefaultService, grpcProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: GrpcProbeOptions","status: number | string | undefined","client: GrpcLikeHealthClient"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * gRPC probe for `@openstatus/health`: calls `grpc.health.v1.Health/Check`\n * through a generated `@grpc/grpc-js` health client and expects `SERVING`.\n *\n * ```ts\n * import { HealthClient } from \"grpc-health-check\";\n * import { grpcProbe } from \"@openstatus/health-grpc\";\n *\n * const probe = grpcProbe({ client: new HealthClient(address, credentials) });\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 grpcDefaultName = \"grpc\";\n/** Service checked when `service` is unset: the empty string means the server as a whole. */\nexport const grpcDefaultService = \"\";\n\n/** What `Check` answers; `status` is `1` or `\"SERVING\"` when healthy, depending on how enums were loaded. */\nexport interface GrpcHealthCheckResponse {\n  /** The `ServingStatus` enum value. */\n  readonly status?: number | string;\n}\n\n/** The subset of a `ClientUnaryCall` the probe uses. */\nexport interface GrpcLikeCall {\n  /** Cancel the in-flight call. */\n  cancel(): void;\n}\n\n/** The subset of a generated `Health` client the probe uses. */\nexport interface GrpcLikeHealthClient {\n  /** Call `Health/Check` for `service`. */\n  check(\n    request: { readonly service: string },\n    callback: (\n      error: Error | null,\n      response?: GrpcHealthCheckResponse,\n    ) => void,\n  ): GrpcLikeCall;\n}\n\n/** Options for `grpcProbe()`. */\nexport interface GrpcProbeOptions extends ProbeOverrides {\n  /** A `grpc.health.v1.Health` client, e.g. from `grpc-health-check` or your generated stubs. */\n  readonly client: GrpcLikeHealthClient;\n  /** The service name to check. Default `grpcDefaultService`. */\n  readonly service?: string;\n}\n\n/** A probe that calls `Health/Check` and expects `SERVING`; non-critical by default. Throws `ProbeConfigError` without `check()` or for a non-string `service`. */\nexport function grpcProbe(options: GrpcProbeOptions): Probe {\n  const client = options.client;\n  if (typeof client?.check !== \"function\") {\n    throw new ProbeConfigError(\n      \"grpcProbe\",\n      \"client\",\n      `must expose check(), got ${describe(client)}`,\n    );\n  }\n  const service = options.service === undefined\n    ? grpcDefaultService\n    : options.service;\n  if (typeof service !== \"string\") {\n    throw new ProbeConfigError(\n      \"grpcProbe\",\n      \"service\",\n      `must be a string, got ${String(service)}`,\n    );\n  }\n  return {\n    name: options.name ?? grpcDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: (signal) =>\n      new Promise<void>((resolve, reject) => {\n        signal.throwIfAborted();\n        const onAbort = () => {\n          call.cancel();\n          reject(signal.reason);\n        };\n        signal.addEventListener(\"abort\", onAbort, { once: true });\n        const call = client.check({ service }, (error, response) => {\n          signal.removeEventListener(\"abort\", onAbort);\n          if (error != null) {\n            reject(error);\n            return;\n          }\n          const status = response?.status;\n          if (status === 1 || status === \"SERVING\") {\n            resolve();\n            return;\n          }\n          reject(new Error(`serving status ${describeStatus(status)}`));\n        });\n      }),\n  };\n}\n\nfunction describeStatus(status: number | string | undefined): string {\n  if (status === 0 || status === \"UNKNOWN\") return \"UNKNOWN\";\n  if (status === 2 || status === \"NOT_SERVING\") return \"NOT_SERVING\";\n  if (status === 3 || status === \"SERVICE_UNKNOWN\") return \"SERVICE_UNKNOWN\";\n  return String(status);\n}\n\nfunction describe(client: GrpcLikeHealthClient): string {\n  if (client == null) return String(client);\n  if (typeof client !== \"object\") return typeof client;\n  const keys = Object.keys(client);\n  return keys.length === 0\n    ? \"an object with no keys\"\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;AAqBA,MAAa,kBAAkB;;AAE/B,MAAa,qBAAqB;;AAmClC,SAAgB,UAAUA,SAAkC;CAC1D,MAAM,SAAS,QAAQ;AACvB,YAAW,QAAQ,UAAU,WAC3B,OAAM,IAAI,iBACR,aACA,WACC,2BAA2B,SAAS,OAAO,CAAC;CAGjD,MAAM,UAAU,QAAQ,qBACpB,qBACA,QAAQ;AACZ,YAAW,YAAY,SACrB,OAAM,IAAI,iBACR,aACA,YACC,wBAAwB,OAAO,QAAQ,CAAC;AAG7C,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,CAAC,WACJ,IAAI,QAAc,CAAC,SAAS,WAAW;AACrC,UAAO,gBAAgB;GACvB,MAAM,UAAU,MAAM;AACpB,SAAK,QAAQ;AACb,WAAO,OAAO,OAAO;GACtB;AACD,UAAO,iBAAiB,SAAS,SAAS,EAAE,MAAM,KAAM,EAAC;GACzD,MAAM,OAAO,OAAO,MAAM,EAAE,QAAS,GAAE,CAAC,OAAO,aAAa;AAC1D,WAAO,oBAAoB,SAAS,QAAQ;AAC5C,QAAI,SAAS,MAAM;AACjB,YAAO,MAAM;AACb;IACD;IACD,MAAM,SAAS,UAAU;AACzB,QAAI,WAAW,KAAK,WAAW,WAAW;AACxC,cAAS;AACT;IACD;AACD,2BAAO,IAAI,OAAO,iBAAiB,eAAe,OAAO,CAAC,GAAG;GAC9D,EAAC;EACH;CACJ;AACF;AAED,SAAS,eAAeC,QAA6C;AACnE,KAAI,WAAW,KAAK,WAAW,UAAW,QAAO;AACjD,KAAI,WAAW,KAAK,WAAW,cAAe,QAAO;AACrD,KAAI,WAAW,KAAK,WAAW,kBAAmB,QAAO;AACzD,QAAO,OAAO,OAAO;AACtB;AAED,SAAS,SAASC,QAAsC;AACtD,KAAI,UAAU,KAAM,QAAO,OAAO,OAAO;AACzC,YAAW,WAAW,SAAU,eAAc;CAC9C,MAAM,OAAO,OAAO,KAAK,OAAO;AAChC,QAAO,KAAK,WAAW,IACnB,4BACC,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@openstatus/health-grpc",
+  "version": "0.1.4-dev.0",
+  "description": "gRPC health check probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "grpc",
+    "grpc-js",
+    "health-check"
+  ],
+  "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/grpc/"
+  },
+  "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",
+    "@grpc/grpc-js": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@grpc/grpc-js": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}