@openstatus/health-dns 0.1.4-dev.0

package/README.md

@@ -0,0 +1,74 @@
+# @openstatus/health-dns
+
+DNS probe for [`@openstatus/health`](https://jsr.io/@openstatus/health).
+Resolves a hostname through the runtime's resolver and fails the check
+when the name does not resolve — the early warning for an expired domain,
+a broken record change or a resolver outage on the host, before the first
+request to that dependency fails.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-dns
+npm install @openstatus/health @openstatus/health-dns
+```
+
+```ts
+import { createHealthHandler } from "@openstatus/health";
+import { dnsProbe } from "@openstatus/health-dns";
+
+Deno.serve(
+  createHealthHandler({
+    probes: [dnsProbe({ hostname: "api.stripe.com" })],
+  }),
+);
+```
+
+The probe calls `dns.promises.lookup(hostname)`, which uses the same path
+your `fetch` and sockets use — the OS resolver, `/etc/hosts` and whatever
+cache the OS keeps — so it answers "would a connection to this name find an
+address" rather than "what do the authoritative servers say". Pass
+`lookup` to resolve through something else, such as a `Resolver` pointed at
+specific servers with its `resolve4` result mapped to `{ address }` as
+below, and give each probe a `name` when you mount more than one.
+
+```ts
+import { Resolver } from "node:dns/promises";
+
+const resolver = new Resolver();
+resolver.setServers(["1.1.1.1"]);
+
+dnsProbe({
+  hostname: "api.example.com",
+  lookup: async (hostname) =>
+    (await resolver.resolve4(hostname)).map((address) => ({ address })),
+  // optional overrides from the Probe contract
+  name: "upstream-dns",
+  critical: true,
+  timeoutMs: 1000,
+  skip: () => env.UPSTREAM_HOST == null,
+});
+```
+
+Non-critical by default: a name that stops resolving is worth alerting on,
+but the dependency behind it usually has a probe of its own that decides
+whether the service can still serve. Set `critical: true` when it cannot.
+
+This probe uses `node:dns`, so it runs on Node.js, Deno and Bun but not on
+edge runtimes without a resolver API.
+
+## 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,30 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const node_dns_promises = require_rolldown_runtime.__toESM(require("node:dns/promises"));
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const dnsDefaultName = "dns";
+/** A probe that resolves `hostname` to at least one address; non-critical by default. Throws `ProbeConfigError` for an empty `hostname`. */
+function dnsProbe(options) {
+	const hostname = options.hostname;
+	if (typeof hostname !== "string" || hostname.length === 0) throw new __openstatus_health.ProbeConfigError("dnsProbe", "hostname", typeof hostname !== "string" ? `must be a string, got ${String(hostname)}` : "must not be empty");
+	const lookup = options.lookup ?? node_dns_promises.lookup;
+	return {
+		name: options.name ?? dnsDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const result = await lookup(hostname);
+			const addresses = Array.isArray(result) ? result : [result];
+			const address = addresses.find((entry) => typeof entry?.address === "string" && entry.address.length > 0)?.address;
+			if (address == null) throw new Error(`no address for ${hostname}`);
+			return { address };
+		}
+	};
+}
+
+//#endregion
+exports.dnsDefaultName = dnsDefaultName;
+exports.dnsProbe = dnsProbe;

package/dist/mod.d.cts

@@ -0,0 +1,26 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const dnsDefaultName = "dns";
+/** One resolved address. */
+interface DnsAddress {
+  /** The IPv4 or IPv6 address. */
+  readonly address: string;
+}
+/** What the probe resolves with; `dns.promises.lookup` by default. */
+type DnsLookup = (hostname: string) => PromiseLike<DnsAddress | readonly DnsAddress[]>;
+/** Options for `dnsProbe()`. */
+interface DnsProbeOptions extends ProbeOverrides {
+  /** The name to resolve. */
+  readonly hostname: string;
+  /** Replacement `lookup`, for tests or a custom resolver. */
+  readonly lookup?: DnsLookup;
+}
+/** A probe that resolves `hostname` to at least one address; non-critical by default. Throws `ProbeConfigError` for an empty `hostname`. */
+declare function dnsProbe(options: DnsProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { DnsAddress, DnsLookup, DnsProbeOptions, dnsDefaultName, dnsProbe };
+//# 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":";;;;AAqCuD;AAQvC,cAtBH,cAAA,GAsBW,KAAA;;AAAU,UAnBjB,UAAA,CAmBiB;EAAe;EAAQ,SAAA,OAAA,EAAA,MAAA;;;KAb7C,SAAA,yBAEP,YAAY,sBAAsB;;UAGtB,eAAA,SAAwB;;;;oBAIrB;;;iBAIJ,QAAA,UAAkB,kBAAkB"}

package/dist/mod.d.ts

@@ -0,0 +1,26 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const dnsDefaultName = "dns";
+/** One resolved address. */
+interface DnsAddress {
+  /** The IPv4 or IPv6 address. */
+  readonly address: string;
+}
+/** What the probe resolves with; `dns.promises.lookup` by default. */
+type DnsLookup = (hostname: string) => PromiseLike<DnsAddress | readonly DnsAddress[]>;
+/** Options for `dnsProbe()`. */
+interface DnsProbeOptions extends ProbeOverrides {
+  /** The name to resolve. */
+  readonly hostname: string;
+  /** Replacement `lookup`, for tests or a custom resolver. */
+  readonly lookup?: DnsLookup;
+}
+/** A probe that resolves `hostname` to at least one address; non-critical by default. Throws `ProbeConfigError` for an empty `hostname`. */
+declare function dnsProbe(options: DnsProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { DnsAddress, DnsLookup, DnsProbeOptions, dnsDefaultName, dnsProbe };
+//# 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":";;;;AAqCuD;AAQvC,cAtBH,cAAA,GAsBW,KAAA;;AAAU,UAnBjB,UAAA,CAmBiB;EAAe;EAAQ,SAAA,OAAA,EAAA,MAAA;;;KAb7C,SAAA,yBAEP,YAAY,sBAAsB;;UAGtB,eAAA,SAAwB;;;;oBAIrB;;;iBAIJ,QAAA,UAAkB,kBAAkB"}

package/dist/mod.js

@@ -0,0 +1,29 @@
+import { lookup } from "node:dns/promises";
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const dnsDefaultName = "dns";
+/** A probe that resolves `hostname` to at least one address; non-critical by default. Throws `ProbeConfigError` for an empty `hostname`. */
+function dnsProbe(options) {
+	const hostname = options.hostname;
+	if (typeof hostname !== "string" || hostname.length === 0) throw new ProbeConfigError("dnsProbe", "hostname", typeof hostname !== "string" ? `must be a string, got ${String(hostname)}` : "must not be empty");
+	const lookup$1 = options.lookup ?? lookup;
+	return {
+		name: options.name ?? dnsDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const result = await lookup$1(hostname);
+			const addresses = Array.isArray(result) ? result : [result];
+			const address = addresses.find((entry) => typeof entry?.address === "string" && entry.address.length > 0)?.address;
+			if (address == null) throw new Error(`no address for ${hostname}`);
+			return { address };
+		}
+	};
+}
+
+//#endregion
+export { dnsDefaultName, dnsProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: DnsProbeOptions","lookup","dnsLookup"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * DNS probe for `@openstatus/health`: resolves a hostname through the\n * runtime's resolver and fails when it does not resolve.\n *\n * ```ts\n * import { dnsProbe } from \"@openstatus/health-dns\";\n *\n * const probe = dnsProbe({ hostname: \"api.example.com\" });\n * ```\n *\n * Node.js, Deno and Bun only: it uses `node:dns`.\n *\n * @module\n */\n\nimport { lookup as dnsLookup } from \"node:dns/promises\";\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const dnsDefaultName = \"dns\";\n\n/** One resolved address. */\nexport interface DnsAddress {\n  /** The IPv4 or IPv6 address. */\n  readonly address: string;\n}\n\n/** What the probe resolves with; `dns.promises.lookup` by default. */\nexport type DnsLookup = (\n  hostname: string,\n) => PromiseLike<DnsAddress | readonly DnsAddress[]>;\n\n/** Options for `dnsProbe()`. */\nexport interface DnsProbeOptions extends ProbeOverrides {\n  /** The name to resolve. */\n  readonly hostname: string;\n  /** Replacement `lookup`, for tests or a custom resolver. */\n  readonly lookup?: DnsLookup;\n}\n\n/** A probe that resolves `hostname` to at least one address; non-critical by default. Throws `ProbeConfigError` for an empty `hostname`. */\nexport function dnsProbe(options: DnsProbeOptions): Probe {\n  const hostname = options.hostname;\n  if (typeof hostname !== \"string\" || hostname.length === 0) {\n    throw new ProbeConfigError(\n      \"dnsProbe\",\n      \"hostname\",\n      typeof hostname !== \"string\"\n        ? `must be a string, got ${String(hostname)}`\n        : \"must not be empty\",\n    );\n  }\n  const lookup = options.lookup ?? dnsLookup;\n  return {\n    name: options.name ?? dnsDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async () => {\n      const result = await lookup(hostname);\n      const addresses = Array.isArray(result) ? result : [result];\n      const address = addresses.find((entry) =>\n        typeof entry?.address === \"string\" && entry.address.length > 0\n      )?.address;\n      if (address == null) throw new Error(`no address for ${hostname}`);\n      return { address };\n    },\n  };\n}\n"],"mappings":";;;;;AAuBA,MAAa,iBAAiB;;AAsB9B,SAAgB,SAASA,SAAiC;CACxD,MAAM,WAAW,QAAQ;AACzB,YAAW,aAAa,YAAY,SAAS,WAAW,EACtD,OAAM,IAAI,iBACR,YACA,mBACO,aAAa,YACf,wBAAwB,OAAO,SAAS,CAAC,IAC1C;CAGR,MAAMC,WAAS,QAAQ,UAAUC;AACjC,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,YAAY;GACf,MAAM,SAAS,MAAM,SAAO,SAAS;GACrC,MAAM,YAAY,MAAM,QAAQ,OAAO,GAAG,SAAS,CAAC,MAAO;GAC3D,MAAM,UAAU,UAAU,KAAK,CAAC,iBACvB,OAAO,YAAY,YAAY,MAAM,QAAQ,SAAS,EAC9D,EAAE;AACH,OAAI,WAAW,KAAM,OAAM,IAAI,OAAO,iBAAiB,SAAS;AAChE,UAAO,EAAE,QAAS;EACnB;CACF;AACF"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@openstatus/health-dns",
+  "version": "0.1.4-dev.0",
+  "description": "DNS lookup probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "dns",
+    "lookup",
+    "network"
+  ],
+  "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/dns/"
+  },
+  "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"
+  }
+}