@checkstack/healthcheck-dns-backend 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @checkstack/healthcheck-dns-backend
 
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Refactored health check strategies to use `createClient()` pattern with built-in collectors.
+
+  **Strategy Changes:**
+
+  - Replaced `execute()` with `createClient()` that returns a transport client
+  - Strategy configs now only contain connection parameters
+  - Collector configs handle what to do with the connection
+
+  **Built-in Collectors Added:**
+
+  - DNS: `LookupCollector` for hostname resolution
+  - gRPC: `HealthCollector` for gRPC health protocol
+  - HTTP: `RequestCollector` for HTTP requests
+  - MySQL: `QueryCollector` for database queries
+  - Ping: `PingCollector` for ICMP ping
+  - Postgres: `QueryCollector` for database queries
+  - Redis: `CommandCollector` for Redis commands
+  - Script: `ExecuteCollector` for script execution
+  - SSH: `CommandCollector` for SSH commands
+  - TCP: `BannerCollector` for TCP banner grabbing
+  - TLS: `CertificateCollector` for certificate inspection
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/common@0.0.3
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [cb82e4d]
+  - @checkstack/healthcheck-common@0.0.3
+
 ## 0.0.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-dns-backend",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/index.ts

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

package/src/lookup-collector.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it, mock } from "bun:test";
+import { LookupCollector, type LookupConfig } from "./lookup-collector";
+import type { DnsTransportClient } from "./transport-client";
+
+describe("LookupCollector", () => {
+  const createMockClient = (
+    response: { values: string[]; error?: string } = { values: ["192.168.1.1"] }
+  ): DnsTransportClient => ({
+    exec: mock(() => Promise.resolve(response)),
+  });
+
+  describe("execute", () => {
+    it("should resolve DNS records successfully", async () => {
+      const collector = new LookupCollector();
+      const client = createMockClient({
+        values: ["192.168.1.1", "192.168.1.2"],
+      });
+
+      const result = await collector.execute({
+        config: { hostname: "example.com", recordType: "A" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.values).toEqual(["192.168.1.1", "192.168.1.2"]);
+      expect(result.result.recordCount).toBe(2);
+      expect(result.result.resolutionTimeMs).toBeGreaterThanOrEqual(0);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for failed lookups", async () => {
+      const collector = new LookupCollector();
+      const client = createMockClient({ values: [], error: "NXDOMAIN" });
+
+      const result = await collector.execute({
+        config: { hostname: "nonexistent.invalid", recordType: "A" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.recordCount).toBe(0);
+      expect(result.error).toBe("NXDOMAIN");
+    });
+
+    it("should pass correct parameters to client", async () => {
+      const collector = new LookupCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { hostname: "example.com", recordType: "MX" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        hostname: "example.com",
+        recordType: "MX",
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average resolution time", () => {
+      const collector = new LookupCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            values: ["1.1.1.1"],
+            recordCount: 1,
+            resolutionTimeMs: 50,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            values: ["1.1.1.1"],
+            recordCount: 1,
+            resolutionTimeMs: 100,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgResolutionTimeMs).toBe(75);
+      expect(aggregated.successRate).toBe(100);
+    });
+
+    it("should calculate success rate correctly", () => {
+      const collector = new LookupCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            values: ["1.1.1.1"],
+            recordCount: 1,
+            resolutionTimeMs: 50,
+          },
+        },
+        {
+          id: "2",
+          status: "unhealthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { values: [], recordCount: 0, resolutionTimeMs: 100 },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.successRate).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new LookupCollector();
+
+      expect(collector.id).toBe("lookup");
+      expect(collector.displayName).toBe("DNS Lookup");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/lookup-collector.ts

@@ -0,0 +1,147 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import { healthResultNumber } from "@checkstack/healthcheck-common";
+import { pluginMetadata } from "./plugin-metadata";
+import type { DnsTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const lookupConfigSchema = z.object({
+  hostname: z.string().min(1).describe("Hostname to resolve"),
+  recordType: z
+    .enum(["A", "AAAA", "CNAME", "MX", "TXT", "NS"])
+    .default("A")
+    .describe("DNS record type"),
+  nameserver: z.string().optional().describe("Custom nameserver (optional)"),
+});
+
+export type LookupConfig = z.infer<typeof lookupConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const lookupResultSchema = z.object({
+  values: 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",
+  }),
+  resolutionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Resolution Time",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type LookupResult = z.infer<typeof lookupResultSchema>;
+
+const lookupAggregatedSchema = z.object({
+  avgResolutionTimeMs: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Resolution Time",
+    "x-chart-unit": "ms",
+  }),
+  successRate: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Success Rate",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type LookupAggregatedResult = z.infer<typeof lookupAggregatedSchema>;
+
+// ============================================================================
+// LOOKUP COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in DNS lookup collector.
+ * Resolves DNS records and checks results.
+ */
+export class LookupCollector
+  implements
+    CollectorStrategy<
+      DnsTransportClient,
+      LookupConfig,
+      LookupResult,
+      LookupAggregatedResult
+    >
+{
+  id = "lookup";
+  displayName = "DNS Lookup";
+  description = "Resolve DNS records and check the results";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: lookupConfigSchema });
+  result = new Versioned({ version: 1, schema: lookupResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: lookupAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: LookupConfig;
+    client: DnsTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<LookupResult>> {
+    const startTime = Date.now();
+
+    const response = await client.exec({
+      hostname: config.hostname,
+      recordType: config.recordType,
+    });
+
+    const resolutionTimeMs = Date.now() - startTime;
+
+    return {
+      result: {
+        values: response.values,
+        recordCount: response.values.length,
+        resolutionTimeMs,
+      },
+      error: response.error,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<LookupResult>[]
+  ): LookupAggregatedResult {
+    const times = runs
+      .map((r) => r.metadata?.resolutionTimeMs)
+      .filter((v): v is number => typeof v === "number");
+
+    const recordCounts = runs
+      .map((r) => r.metadata?.recordCount)
+      .filter((v): v is number => typeof v === "number");
+
+    const successCount = recordCounts.filter((c) => c > 0).length;
+
+    return {
+      avgResolutionTimeMs:
+        times.length > 0
+          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
+          : 0,
+      successRate:
+        recordCounts.length > 0
+          ? Math.round((successCount / recordCounts.length) * 100)
+          : 0,
+    };
+  }
+}

package/src/strategy.test.ts

@@ -53,102 +53,83 @@ describe("DnsHealthCheckStrategy", () => {
       } 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"] })
-      );
+  describe("createClient", () => {
+    it("should return a connected client", async () => {
+      const strategy = new DnsHealthCheckStrategy(createMockResolver());
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+    });
 
-      const result = await strategy.execute({
-        hostname: "example.com",
-        recordType: "A",
-        timeout: 5000,
-      });
+    it("should allow closing the client", async () => {
+      const strategy = new DnsHealthCheckStrategy(createMockResolver());
+      const connectedClient = await strategy.createClient({ 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);
+      expect(() => connectedClient.close()).not.toThrow();
     });
 
-    it("should return unhealthy for DNS error", async () => {
-      const strategy = new DnsHealthCheckStrategy(
-        createMockResolver({ resolve4: new Error("NXDOMAIN") })
-      );
+    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([])),
+      }));
 
-      const result = await strategy.execute({
-        hostname: "nonexistent.example.com",
-        recordType: "A",
+      const connectedClient = await strategy.createClient({
+        nameserver: "8.8.8.8",
         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({
+      // Execute to trigger resolver setup
+      await connectedClient.client.exec({
         hostname: "example.com",
         recordType: "A",
-        timeout: 5000,
-        assertions: [{ field: "recordExists", operator: "isTrue" }],
       });
 
-      expect(result.status).toBe("healthy");
+      expect(setServersMock).toHaveBeenCalledWith(["8.8.8.8"]);
+
+      connectedClient.close();
     });
+  });
 
-    it("should fail recordExists assertion when no records", async () => {
+  describe("client.exec", () => {
+    it("should return resolved values for successful A record resolution", async () => {
       const strategy = new DnsHealthCheckStrategy(
-        createMockResolver({ resolve4: [] })
+        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8"] })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         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.values).toEqual(["1.2.3.4", "5.6.7.8"]);
 
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should pass recordCount assertion", async () => {
+    it("should return error for DNS error", async () => {
       const strategy = new DnsHealthCheckStrategy(
-        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8", "9.10.11.12"] })
+        createMockResolver({ resolve4: new Error("NXDOMAIN") })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
-        hostname: "example.com",
+      const result = await connectedClient.client.exec({
+        hostname: "nonexistent.example.com",
         recordType: "A",
-        timeout: 5000,
-        assertions: [
-          { field: "recordCount", operator: "greaterThanOrEqual", value: 2 },
-        ],
       });
 
-      expect(result.status).toBe("healthy");
+      expect(result.error).toContain("NXDOMAIN");
+
+      connectedClient.close();
     });
 
     it("should resolve MX records correctly", async () => {
@@ -160,37 +141,16 @@ describe("DnsHealthCheckStrategy", () => {
           ],
         })
       );
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      const result = await connectedClient.client.exec({
         hostname: "example.com",
         recordType: "MX",
-        timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.resolvedValues).toContain("0 mail1.example.com");
-    });
+      expect(result.values).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"]);
+      connectedClient.close();
     });
   });
 
@@ -264,7 +224,7 @@ describe("DnsHealthCheckStrategy", () => {
       const aggregated = strategy.aggregateResult(runs);
 
       expect(aggregated.errorCount).toBe(1);
-      expect(aggregated.failureCount).toBe(1);
+      expect(aggregated.failureCount).toBe(2);
     });
   });
 });

package/src/strategy.ts

@@ -1,63 +1,48 @@
 import * as dns from "node:dns/promises";
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  booleanField,
-  stringField,
-  numericField,
-  timeThresholdField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  DnsTransportClient,
+  DnsLookupRequest,
+  DnsLookupResult,
+} from "./transport-client";
 
 // ============================================================================
 // 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.
+ * Resolver configuration only - action params moved to LookupCollector.
  */
 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)"),
+  nameserver: z.string().optional().describe("Custom nameserver (optional)"),
   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>;
 
+// Legacy config type for migrations
+interface DnsConfigV1 {
+  hostname: string;
+  recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS";
+  nameserver?: string;
+  timeout: number;
+}
+
 /**
  * Per-run result metadata.
  */
@@ -70,23 +55,18 @@ const dnsResultSchema = z.object({
     "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>;
+type DnsResult = z.infer<typeof dnsResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -107,7 +87,7 @@ const dnsAggregatedSchema = z.object({
   }),
 });
 
-export type DnsAggregatedResult = z.infer<typeof dnsAggregatedSchema>;
+type DnsAggregatedResult = z.infer<typeof dnsAggregatedSchema>;
 
 // ============================================================================
 // RESOLVER INTERFACE (for testability)
@@ -128,21 +108,25 @@ export interface DnsResolver {
 export type ResolverFactory = () => DnsResolver;
 
 // Default factory using Node.js dns module
-const defaultResolverFactory: ResolverFactory = () =>
-  new dns.Resolver() as DnsResolver;
+const defaultResolverFactory: ResolverFactory = () => new dns.Resolver();
 
 // ============================================================================
 // STRATEGY
 // ============================================================================
 
 export class DnsHealthCheckStrategy
-  implements HealthCheckStrategy<DnsConfig, DnsResult, DnsAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      DnsConfig,
+      DnsTransportClient,
+      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) {
@@ -150,13 +134,32 @@ export class DnsHealthCheckStrategy
   }
 
   config: Versioned<DnsConfig> = new Versioned({
-    version: 1,
+    version: 2,
     schema: dnsConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Remove hostname/recordType (moved to LookupCollector)",
+        migrate: (data: DnsConfigV1): DnsConfig => ({
+          nameserver: data.nameserver,
+          timeout: data.timeout,
+        }),
+      },
+    ],
   });
 
   result: Versioned<DnsResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: dnsResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<DnsAggregatedResult> = new Versioned({
@@ -167,148 +170,103 @@ export class DnsHealthCheckStrategy
   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++;
-      }
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return { avgResolutionTime: 0, failureCount: 0, errorCount: 0 };
     }
 
-    return {
-      avgResolutionTime: validRuns > 0 ? totalResolutionTime / validRuns : 0,
-      failureCount,
-      errorCount,
-    };
+    const resolutionTimes = validRuns
+      .map((r) => r.metadata?.resolutionTimeMs)
+      .filter((t): t is number => typeof t === "number");
+
+    const avgResolutionTime =
+      resolutionTimes.length > 0
+        ? Math.round(
+            resolutionTimes.reduce((a, b) => a + b, 0) / resolutionTimes.length
+          )
+        : 0;
+
+    const failureCount = validRuns.filter(
+      (r) => r.metadata?.recordCount === 0
+    ).length;
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
+    return { avgResolutionTime, failureCount, errorCount };
   }
 
-  async execute(config: DnsConfig): Promise<HealthCheckResult<DnsResult>> {
+  async createClient(
+    config: DnsConfig
+  ): Promise<ConnectedClient<DnsTransportClient>> {
     const validatedConfig = this.config.validate(config);
-    const start = performance.now();
+    const resolver = this.resolverFactory();
 
-    try {
-      // Configure resolver with custom nameserver if provided
-      const resolver = this.resolverFactory();
-      if (validatedConfig.nameserver) {
-        resolver.setServers([validatedConfig.nameserver]);
-      }
+    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 },
-        };
-      }
+    const client: DnsTransportClient = {
+      exec: async (request: DnsLookupRequest): Promise<DnsLookupResult> => {
+        const timeout = validatedConfig.timeout;
+        const timeoutPromise = new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error("DNS resolution timeout")), timeout)
+        );
+
+        try {
+          const resolvePromise = this.resolveRecords(
+            resolver,
+            request.hostname,
+            request.recordType
+          );
+
+          const values = await Promise.race([resolvePromise, timeoutPromise]);
+          return { values };
+        } catch (error) {
+          return {
+            values: [],
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      },
+    };
 
-      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",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => {
+        // DNS resolver is stateless, nothing to close
+      },
+    };
   }
 
-  /**
-   * Resolve DNS records based on type.
-   */
   private async resolveRecords(
     resolver: DnsResolver,
     hostname: string,
-    recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS",
-    timeout: number
+    recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS"
   ): 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);
-        }
+    switch (recordType) {
+      case "A": {
+        return resolver.resolve4(hostname);
       }
-    })();
-
-    return Promise.race([resolvePromise, timeoutPromise]);
+      case "AAAA": {
+        return resolver.resolve6(hostname);
+      }
+      case "CNAME": {
+        return 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 resolver.resolveNs(hostname);
+      }
+    }
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,25 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * DNS lookup request.
+ */
+export interface DnsLookupRequest {
+  hostname: string;
+  recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS";
+}
+
+/**
+ * DNS lookup result.
+ */
+export interface DnsLookupResult {
+  values: string[];
+  error?: string;
+}
+
+/**
+ * DNS transport client for record lookups.
+ */
+export type DnsTransportClient = TransportClient<
+  DnsLookupRequest,
+  DnsLookupResult
+>;