@checkstack/healthcheck-dns-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-dns-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/healthcheck-common@0.0.2
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/healthcheck-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [0babb9c]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/healthcheck-common@0.1.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/healthcheck-dns-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { DnsHealthCheckStrategy } from "./strategy";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ healthCheckRegistry, logger }) => {
+        logger.debug("🔌 Registering DNS Health Check Strategy...");
+        const strategy = new DnsHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,8 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the DNS Health Check backend.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-dns",
+});

package/src/strategy.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it, mock } from "bun:test";
+import {
+  DnsHealthCheckStrategy,
+  DnsResolver,
+  ResolverFactory,
+} from "./strategy";
+
+describe("DnsHealthCheckStrategy", () => {
+  // Helper to create mock resolver factory
+  const createMockResolver = (
+    config: {
+      resolve4?: string[] | Error;
+      resolve6?: string[] | Error;
+      resolveCname?: string[] | Error;
+      resolveMx?: { priority: number; exchange: string }[] | Error;
+      resolveTxt?: string[][] | Error;
+      resolveNs?: string[] | Error;
+    } = {}
+  ): ResolverFactory => {
+    return () =>
+      ({
+        setServers: mock(() => {}),
+        resolve4: mock(() =>
+          config.resolve4 instanceof Error
+            ? Promise.reject(config.resolve4)
+            : Promise.resolve(config.resolve4 ?? [])
+        ),
+        resolve6: mock(() =>
+          config.resolve6 instanceof Error
+            ? Promise.reject(config.resolve6)
+            : Promise.resolve(config.resolve6 ?? [])
+        ),
+        resolveCname: mock(() =>
+          config.resolveCname instanceof Error
+            ? Promise.reject(config.resolveCname)
+            : Promise.resolve(config.resolveCname ?? [])
+        ),
+        resolveMx: mock(() =>
+          config.resolveMx instanceof Error
+            ? Promise.reject(config.resolveMx)
+            : Promise.resolve(config.resolveMx ?? [])
+        ),
+        resolveTxt: mock(() =>
+          config.resolveTxt instanceof Error
+            ? Promise.reject(config.resolveTxt)
+            : Promise.resolve(config.resolveTxt ?? [])
+        ),
+        resolveNs: mock(() =>
+          config.resolveNs instanceof Error
+            ? Promise.reject(config.resolveNs)
+            : Promise.resolve(config.resolveNs ?? [])
+        ),
+      } as DnsResolver);
+  };
+
+  describe("execute", () => {
+    it("should return healthy for successful A record resolution", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8"] })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "A",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.resolvedValues).toEqual(["1.2.3.4", "5.6.7.8"]);
+      expect(result.metadata?.recordCount).toBe(2);
+    });
+
+    it("should return unhealthy for DNS error", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolve4: new Error("NXDOMAIN") })
+      );
+
+      const result = await strategy.execute({
+        hostname: "nonexistent.example.com",
+        recordType: "A",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("NXDOMAIN");
+      expect(result.metadata?.error).toBeDefined();
+    });
+
+    it("should pass recordExists assertion when records found", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolve4: ["1.2.3.4"] })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "A",
+        timeout: 5000,
+        assertions: [{ field: "recordExists", operator: "isTrue" }],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should fail recordExists assertion when no records", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolve4: [] })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "A",
+        timeout: 5000,
+        assertions: [{ field: "recordExists", operator: "isTrue" }],
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.message).toContain("Assertion failed");
+    });
+
+    it("should pass recordValue assertion with matching value", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolveCname: ["cdn.example.com"] })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "CNAME",
+        timeout: 5000,
+        assertions: [
+          { field: "recordValue", operator: "contains", value: "cdn" },
+        ],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should pass recordCount assertion", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8", "9.10.11.12"] })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "A",
+        timeout: 5000,
+        assertions: [
+          { field: "recordCount", operator: "greaterThanOrEqual", value: 2 },
+        ],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should resolve MX records correctly", async () => {
+      const strategy = new DnsHealthCheckStrategy(
+        createMockResolver({
+          resolveMx: [
+            { priority: 0, exchange: "mail1.example.com" },
+            { priority: 10, exchange: "mail2.example.com" },
+          ],
+        })
+      );
+
+      const result = await strategy.execute({
+        hostname: "example.com",
+        recordType: "MX",
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("healthy");
+      expect(result.metadata?.resolvedValues).toContain("0 mail1.example.com");
+    });
+
+    it("should use custom nameserver when provided", async () => {
+      const setServersMock = mock(() => {});
+      const strategy = new DnsHealthCheckStrategy(() => ({
+        setServers: setServersMock,
+        resolve4: mock(() => Promise.resolve(["1.2.3.4"])),
+        resolve6: mock(() => Promise.resolve([])),
+        resolveCname: mock(() => Promise.resolve([])),
+        resolveMx: mock(() => Promise.resolve([])),
+        resolveTxt: mock(() => Promise.resolve([])),
+        resolveNs: mock(() => Promise.resolve([])),
+      }));
+
+      await strategy.execute({
+        hostname: "example.com",
+        recordType: "A",
+        nameserver: "8.8.8.8",
+        timeout: 5000,
+      });
+
+      expect(setServersMock).toHaveBeenCalledWith(["8.8.8.8"]);
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const strategy = new DnsHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            resolvedValues: ["1.2.3.4"],
+            recordCount: 1,
+            resolutionTimeMs: 10,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 20,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            resolvedValues: ["5.6.7.8"],
+            recordCount: 1,
+            resolutionTimeMs: 20,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgResolutionTime).toBe(15);
+      expect(aggregated.failureCount).toBe(0);
+      expect(aggregated.errorCount).toBe(0);
+    });
+
+    it("should count failures and errors", () => {
+      const strategy = new DnsHealthCheckStrategy();
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            resolvedValues: [],
+            recordCount: 0,
+            resolutionTimeMs: 10,
+            error: "NXDOMAIN",
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 20,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            resolvedValues: [],
+            recordCount: 0,
+            resolutionTimeMs: 20,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.failureCount).toBe(1);
+    });
+  });
+});

package/src/strategy.ts

@@ -0,0 +1,314 @@
+import * as dns from "node:dns/promises";
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  booleanField,
+  stringField,
+  numericField,
+  timeThresholdField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// SCHEMAS
+// ============================================================================
+
+/**
+ * Assertion schema for DNS health checks using shared factories.
+ */
+const dnsAssertionSchema = z.discriminatedUnion("field", [
+  booleanField("recordExists"),
+  stringField("recordValue"),
+  numericField("recordCount", { min: 0 }),
+  timeThresholdField("resolutionTime"),
+]);
+
+export type DnsAssertion = z.infer<typeof dnsAssertionSchema>;
+
+/**
+ * Configuration schema for DNS health checks.
+ */
+export const dnsConfigSchema = z.object({
+  hostname: z.string().describe("Hostname to resolve"),
+  recordType: z
+    .enum(["A", "AAAA", "CNAME", "MX", "TXT", "NS"])
+    .default("A")
+    .describe("DNS record type to query"),
+  nameserver: z
+    .string()
+    .optional()
+    .describe("Custom nameserver (optional, uses system default)"),
+  timeout: z
+    .number()
+    .min(100)
+    .default(5000)
+    .describe("Timeout in milliseconds"),
+  assertions: z
+    .array(dnsAssertionSchema)
+    .optional()
+    .describe("Conditions for validation"),
+});
+
+export type DnsConfig = z.infer<typeof dnsConfigSchema>;
+
+/**
+ * Per-run result metadata.
+ */
+const dnsResultSchema = z.object({
+  resolvedValues: z.array(z.string()).meta({
+    "x-chart-type": "text",
+    "x-chart-label": "Resolved Values",
+  }),
+  recordCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Record Count",
+  }),
+  nameserver: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Nameserver",
+  }).optional(),
+  resolutionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Resolution Time",
+    "x-chart-unit": "ms",
+  }),
+  failedAssertion: dnsAssertionSchema.optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+export type DnsResult = z.infer<typeof dnsResultSchema>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+const dnsAggregatedSchema = z.object({
+  avgResolutionTime: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Resolution Time",
+    "x-chart-unit": "ms",
+  }),
+  failureCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Failures",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+export type DnsAggregatedResult = z.infer<typeof dnsAggregatedSchema>;
+
+// ============================================================================
+// RESOLVER INTERFACE (for testability)
+// ============================================================================
+
+export interface DnsResolver {
+  setServers(servers: string[]): void;
+  resolve4(hostname: string): Promise<string[]>;
+  resolve6(hostname: string): Promise<string[]>;
+  resolveCname(hostname: string): Promise<string[]>;
+  resolveMx(
+    hostname: string
+  ): Promise<{ priority: number; exchange: string }[]>;
+  resolveTxt(hostname: string): Promise<string[][]>;
+  resolveNs(hostname: string): Promise<string[]>;
+}
+
+export type ResolverFactory = () => DnsResolver;
+
+// Default factory using Node.js dns module
+const defaultResolverFactory: ResolverFactory = () =>
+  new dns.Resolver() as DnsResolver;
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class DnsHealthCheckStrategy
+  implements HealthCheckStrategy<DnsConfig, DnsResult, DnsAggregatedResult>
+{
+  id = "dns";
+  displayName = "DNS Health Check";
+  description = "DNS record resolution with response validation";
+
+  // Injected resolver factory for testing
+  private resolverFactory: ResolverFactory;
+
+  constructor(resolverFactory: ResolverFactory = defaultResolverFactory) {
+    this.resolverFactory = resolverFactory;
+  }
+
+  config: Versioned<DnsConfig> = new Versioned({
+    version: 1,
+    schema: dnsConfigSchema,
+  });
+
+  result: Versioned<DnsResult> = new Versioned({
+    version: 1,
+    schema: dnsResultSchema,
+  });
+
+  aggregatedResult: Versioned<DnsAggregatedResult> = new Versioned({
+    version: 1,
+    schema: dnsAggregatedSchema,
+  });
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<DnsResult>[]
+  ): DnsAggregatedResult {
+    let totalResolutionTime = 0;
+    let failureCount = 0;
+    let errorCount = 0;
+    let validRuns = 0;
+
+    for (const run of runs) {
+      if (run.metadata?.error) {
+        errorCount++;
+        continue;
+      }
+      if (run.status === "unhealthy") {
+        failureCount++;
+      }
+      if (run.metadata) {
+        totalResolutionTime += run.metadata.resolutionTimeMs;
+        validRuns++;
+      }
+    }
+
+    return {
+      avgResolutionTime: validRuns > 0 ? totalResolutionTime / validRuns : 0,
+      failureCount,
+      errorCount,
+    };
+  }
+
+  async execute(config: DnsConfig): Promise<HealthCheckResult<DnsResult>> {
+    const validatedConfig = this.config.validate(config);
+    const start = performance.now();
+
+    try {
+      // Configure resolver with custom nameserver if provided
+      const resolver = this.resolverFactory();
+      if (validatedConfig.nameserver) {
+        resolver.setServers([validatedConfig.nameserver]);
+      }
+
+      // Perform DNS lookup based on record type
+      const resolvedValues = await this.resolveRecords(
+        resolver,
+        validatedConfig.hostname,
+        validatedConfig.recordType,
+        validatedConfig.timeout
+      );
+
+      const end = performance.now();
+      const resolutionTimeMs = Math.round(end - start);
+
+      const result: Omit<DnsResult, "failedAssertion" | "error"> = {
+        resolvedValues,
+        recordCount: resolvedValues.length,
+        nameserver: validatedConfig.nameserver,
+        resolutionTimeMs,
+      };
+
+      // Evaluate assertions using shared utility
+      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
+        recordExists: resolvedValues.length > 0,
+        recordValue: resolvedValues[0] ?? "",
+        recordCount: resolvedValues.length,
+        resolutionTime: resolutionTimeMs,
+      });
+
+      if (failedAssertion) {
+        return {
+          status: "unhealthy",
+          latencyMs: resolutionTimeMs,
+          message: `Assertion failed: ${failedAssertion.field} ${
+            failedAssertion.operator
+          }${"value" in failedAssertion ? ` ${failedAssertion.value}` : ""}`,
+          metadata: { ...result, failedAssertion },
+        };
+      }
+
+      return {
+        status: "healthy",
+        latencyMs: resolutionTimeMs,
+        message: `Resolved ${validatedConfig.hostname} (${
+          validatedConfig.recordType
+        }): ${resolvedValues.slice(0, 3).join(", ")}${
+          resolvedValues.length > 3 ? "..." : ""
+        }`,
+        metadata: result,
+      };
+    } catch (error: unknown) {
+      const end = performance.now();
+      const isError = error instanceof Error;
+      return {
+        status: "unhealthy",
+        latencyMs: Math.round(end - start),
+        message: isError ? error.message : "DNS resolution failed",
+        metadata: {
+          resolvedValues: [],
+          recordCount: 0,
+          nameserver: validatedConfig.nameserver,
+          resolutionTimeMs: Math.round(end - start),
+          error: isError ? error.name : "UnknownError",
+        },
+      };
+    }
+  }
+
+  /**
+   * Resolve DNS records based on type.
+   */
+  private async resolveRecords(
+    resolver: DnsResolver,
+    hostname: string,
+    recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS",
+    timeout: number
+  ): Promise<string[]> {
+    // Create timeout promise
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => reject(new Error("DNS resolution timeout")), timeout);
+    });
+
+    // Resolve based on record type
+    const resolvePromise = (async () => {
+      switch (recordType) {
+        case "A": {
+          return await resolver.resolve4(hostname);
+        }
+        case "AAAA": {
+          return await resolver.resolve6(hostname);
+        }
+        case "CNAME": {
+          return await resolver.resolveCname(hostname);
+        }
+        case "MX": {
+          const records = await resolver.resolveMx(hostname);
+          return records.map((r) => `${r.priority} ${r.exchange}`);
+        }
+        case "TXT": {
+          const records = await resolver.resolveTxt(hostname);
+          return records.map((r) => r.join(""));
+        }
+        case "NS": {
+          return await resolver.resolveNs(hostname);
+        }
+      }
+    })();
+
+    return Promise.race([resolvePromise, timeoutPromise]);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}