@checkstack/healthcheck-ping-backend 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @checkstack/healthcheck-ping-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-ping-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 { PingHealthCheckStrategy } from "./strategy";
 import { pluginMetadata } from "./plugin-metadata";
+import { PingCollector } from "./ping-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 Ping Health Check Strategy...");
         const strategy = new PingHealthCheckStrategy();
         healthCheckRegistry.register(strategy);
+        collectorRegistry.register(new PingCollector());
       },
     });
   },
 });
+
+export { pluginMetadata } from "./plugin-metadata";

package/src/ping-collector.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it, mock } from "bun:test";
+import { PingCollector, type PingConfig } from "./ping-collector";
+import type { PingTransportClient } from "./transport-client";
+
+describe("PingCollector", () => {
+  const createMockClient = (
+    response: {
+      packetsSent?: number;
+      packetsReceived?: number;
+      packetLoss?: number;
+      minLatency?: number;
+      avgLatency?: number;
+      maxLatency?: number;
+      error?: string;
+    } = {}
+  ): PingTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        packetsSent: response.packetsSent ?? 3,
+        packetsReceived: response.packetsReceived ?? 3,
+        packetLoss: response.packetLoss ?? 0,
+        minLatency: response.minLatency ?? 10,
+        avgLatency: response.avgLatency ?? 15,
+        maxLatency: response.maxLatency ?? 20,
+        error: response.error,
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should execute ping successfully", async () => {
+      const collector = new PingCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { host: "192.168.1.1", count: 3, timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.packetsSent).toBe(3);
+      expect(result.result.packetsReceived).toBe(3);
+      expect(result.result.packetLoss).toBe(0);
+      expect(result.result.avgLatency).toBe(15);
+      expect(result.error).toBeUndefined();
+    });
+
+    it("should return error for failed ping", async () => {
+      const collector = new PingCollector();
+      const client = createMockClient({
+        packetsSent: 3,
+        packetsReceived: 0,
+        packetLoss: 100,
+        error: "Host unreachable",
+      });
+
+      const result = await collector.execute({
+        config: { host: "10.255.255.1", count: 3, timeout: 5000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.packetLoss).toBe(100);
+      expect(result.error).toBe("Host unreachable");
+    });
+
+    it("should pass correct parameters to client", async () => {
+      const collector = new PingCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { host: "8.8.8.8", count: 5, timeout: 3000 },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith({
+        host: "8.8.8.8",
+        count: 5,
+        timeout: 3000,
+      });
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average packet loss and latency", () => {
+      const collector = new PingCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            packetsSent: 3,
+            packetsReceived: 3,
+            packetLoss: 0,
+            avgLatency: 10,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 15,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            packetsSent: 3,
+            packetsReceived: 3,
+            packetLoss: 10,
+            avgLatency: 20,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgPacketLoss).toBe(5);
+      expect(aggregated.avgLatency).toBe(15);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new PingCollector();
+
+      expect(collector.id).toBe("ping");
+      expect(collector.displayName).toBe("ICMP Ping");
+      expect(collector.allowMultiple).toBe(true);
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/ping-collector.ts

@@ -0,0 +1,171 @@
+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 { PingTransportClient } from "./transport-client";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const pingConfigSchema = z.object({
+  host: z.string().min(1).describe("Hostname or IP address to ping"),
+  count: z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .default(3)
+    .describe("Number of ping packets"),
+  timeout: z
+    .number()
+    .min(100)
+    .default(5000)
+    .describe("Timeout in milliseconds"),
+});
+
+export type PingConfig = z.infer<typeof pingConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const pingResultSchema = z.object({
+  packetsSent: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Packets Sent",
+  }),
+  packetsReceived: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Packets Received",
+  }),
+  packetLoss: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Packet Loss",
+    "x-chart-unit": "%",
+  }),
+  minLatency: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Min Latency",
+    "x-chart-unit": "ms",
+  }).optional(),
+  avgLatency: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Latency",
+    "x-chart-unit": "ms",
+  }).optional(),
+  maxLatency: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Latency",
+    "x-chart-unit": "ms",
+  }).optional(),
+});
+
+export type PingResult = z.infer<typeof pingResultSchema>;
+
+const pingAggregatedSchema = z.object({
+  avgPacketLoss: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Avg Packet Loss",
+    "x-chart-unit": "%",
+  }),
+  avgLatency: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Latency",
+    "x-chart-unit": "ms",
+  }),
+});
+
+export type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
+
+// ============================================================================
+// PING COLLECTOR
+// ============================================================================
+
+/**
+ * Built-in Ping collector.
+ * Performs ICMP ping and checks latency.
+ */
+export class PingCollector
+  implements
+    CollectorStrategy<
+      PingTransportClient,
+      PingConfig,
+      PingResult,
+      PingAggregatedResult
+    >
+{
+  id = "ping";
+  displayName = "ICMP Ping";
+  description = "Ping a host and check latency";
+
+  supportedPlugins = [pluginMetadata];
+
+  allowMultiple = true;
+
+  config = new Versioned({ version: 1, schema: pingConfigSchema });
+  result = new Versioned({ version: 1, schema: pingResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: pingAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: PingConfig;
+    client: PingTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<PingResult>> {
+    const response = await client.exec({
+      host: config.host,
+      count: config.count,
+      timeout: config.timeout,
+    });
+
+    return {
+      result: {
+        packetsSent: response.packetsSent,
+        packetsReceived: response.packetsReceived,
+        packetLoss: response.packetLoss,
+        minLatency: response.minLatency,
+        avgLatency: response.avgLatency,
+        maxLatency: response.maxLatency,
+      },
+      error: response.error,
+    };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<PingResult>[]
+  ): PingAggregatedResult {
+    const losses = runs
+      .map((r) => r.metadata?.packetLoss)
+      .filter((v): v is number => typeof v === "number");
+
+    const latencies = runs
+      .map((r) => r.metadata?.avgLatency)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgPacketLoss:
+        losses.length > 0
+          ? Math.round(
+              (losses.reduce((a, b) => a + b, 0) / losses.length) * 10
+            ) / 10
+          : 0,
+      avgLatency:
+        latencies.length > 0
+          ? Math.round(
+              (latencies.reduce((a, b) => a + b, 0) / latencies.length) * 10
+            ) / 10
+          : 0,
+    };
+  }
+}

package/src/strategy.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, mock, beforeEach } from "bun:test";
+import { describe, expect, it, mock, beforeEach, afterEach } from "bun:test";
 import { PingHealthCheckStrategy } from "./strategy";
 
 // Mock Bun.spawn for testing
@@ -39,22 +39,41 @@ describe("PingHealthCheckStrategy", () => {
     Bun.spawn = originalSpawn;
   });
 
-  describe("execute", () => {
-    it("should return healthy for successful ping", async () => {
-      const result = await strategy.execute({
+  describe("createClient", () => {
+    it("should return a connected client", async () => {
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+
+      expect(connectedClient.client).toBeDefined();
+      expect(connectedClient.client.exec).toBeDefined();
+      expect(connectedClient.close).toBeDefined();
+    });
+
+    it("should allow closing the client", async () => {
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+
+      // Close should not throw
+      expect(() => connectedClient.close()).not.toThrow();
+    });
+  });
+
+  describe("client.exec", () => {
+    it("should return healthy result for successful ping", async () => {
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const result = await connectedClient.client.exec({
         host: "8.8.8.8",
         count: 3,
         timeout: 5000,
       });
 
-      expect(result.status).toBe("healthy");
-      expect(result.metadata?.packetsSent).toBe(3);
-      expect(result.metadata?.packetsReceived).toBe(3);
-      expect(result.metadata?.packetLoss).toBe(0);
-      expect(result.metadata?.avgLatency).toBeCloseTo(11.456, 2);
+      expect(result.packetsSent).toBe(3);
+      expect(result.packetsReceived).toBe(3);
+      expect(result.packetLoss).toBe(0);
+      expect(result.avgLatency).toBeCloseTo(11.456, 2);
+
+      connectedClient.close();
     });
 
-    it("should return unhealthy for 100% packet loss", async () => {
+    it("should return unhealthy result for 100% packet loss", async () => {
       // @ts-expect-error - mocking global
       Bun.spawn = mock(() => ({
         stdout: new ReadableStream({
@@ -74,65 +93,49 @@ describe("PingHealthCheckStrategy", () => {
         exited: Promise.resolve(1),
       }));
 
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const result = await connectedClient.client.exec({
         host: "10.0.0.1",
         count: 3,
         timeout: 5000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.metadata?.packetLoss).toBe(100);
-      expect(result.message).toContain("unreachable");
-    });
-
-    it("should pass latency assertion when below threshold", async () => {
-      const result = await strategy.execute({
-        host: "8.8.8.8",
-        count: 3,
-        timeout: 5000,
-        assertions: [{ field: "avgLatency", operator: "lessThan", value: 50 }],
-      });
+      expect(result.packetLoss).toBe(100);
+      expect(result.error).toContain("unreachable");
 
-      expect(result.status).toBe("healthy");
+      connectedClient.close();
     });
 
-    it("should fail latency assertion when above threshold", async () => {
-      const result = await strategy.execute({
-        host: "8.8.8.8",
-        count: 3,
-        timeout: 5000,
-        assertions: [{ field: "avgLatency", operator: "lessThan", value: 5 }],
-      });
-
-      expect(result.status).toBe("unhealthy");
-      expect(result.message).toContain("Assertion failed");
-      expect(result.metadata?.failedAssertion).toBeDefined();
-    });
+    it("should handle spawn errors gracefully", async () => {
+      Bun.spawn = mock(() => {
+        throw new Error("Command not found");
+      }) as typeof Bun.spawn;
 
-    it("should pass packet loss assertion", async () => {
-      const result = await strategy.execute({
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
+      const result = await connectedClient.client.exec({
         host: "8.8.8.8",
         count: 3,
         timeout: 5000,
-        assertions: [{ field: "packetLoss", operator: "equals", value: 0 }],
       });
 
-      expect(result.status).toBe("healthy");
+      expect(result.error).toBeDefined();
+
+      connectedClient.close();
     });
 
-    it("should handle spawn errors gracefully", async () => {
-      Bun.spawn = mock(() => {
-        throw new Error("Command not found");
-      }) as typeof Bun.spawn;
+    it("should use strategy timeout as fallback", async () => {
+      const connectedClient = await strategy.createClient({ timeout: 5000 });
 
-      const result = await strategy.execute({
+      // The exec should work without timeout specified in request
+      const result = await connectedClient.client.exec({
         host: "8.8.8.8",
         count: 3,
-        timeout: 5000,
+        timeout: 30_000,
       });
 
-      expect(result.status).toBe("unhealthy");
-      expect(result.metadata?.error).toBeDefined();
+      expect(result.packetsSent).toBe(3);
+
+      connectedClient.close();
     });
   });
 
@@ -200,6 +203,3 @@ describe("PingHealthCheckStrategy", () => {
     });
   });
 });
-
-// Import afterEach
-import { afterEach } from "bun:test";

package/src/strategy.ts

@@ -1,59 +1,45 @@
 import {
   HealthCheckStrategy,
-  HealthCheckResult,
   HealthCheckRunForAggregation,
   Versioned,
   z,
-  numericField,
-  timeThresholdField,
-  evaluateAssertions,
+  type ConnectedClient,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
   healthResultString,
 } from "@checkstack/healthcheck-common";
+import type {
+  PingTransportClient,
+  PingRequest,
+  PingResult as PingResultType,
+} from "./transport-client";
 
 // ============================================================================
 // SCHEMAS
 // ============================================================================
 
-/**
- * Assertion schema for Ping health checks using shared factories.
- */
-const pingAssertionSchema = z.discriminatedUnion("field", [
-  numericField("packetLoss", { min: 0, max: 100 }),
-  timeThresholdField("avgLatency"),
-  timeThresholdField("maxLatency"),
-  timeThresholdField("minLatency"),
-]);
-
-export type PingAssertion = z.infer<typeof pingAssertionSchema>;
-
 /**
  * Configuration schema for Ping health checks.
+ * Global defaults only - action params moved to PingCollector.
  */
 export const pingConfigSchema = z.object({
-  host: z.string().describe("Hostname or IP address to ping"),
-  count: z
-    .number()
-    .int()
-    .min(1)
-    .max(10)
-    .default(3)
-    .describe("Number of ping packets to send"),
   timeout: z
     .number()
     .min(100)
     .default(5000)
-    .describe("Timeout in milliseconds"),
-  assertions: z
-    .array(pingAssertionSchema)
-    .optional()
-    .describe("Conditions that must pass for a healthy result"),
+    .describe("Default timeout in milliseconds"),
 });
 
 export type PingConfig = z.infer<typeof pingConfigSchema>;
 
+// Legacy config type for migrations
+interface PingConfigV1 {
+  host: string;
+  count: number;
+  timeout: number;
+}
+
 /**
  * Per-run result metadata.
  */
@@ -86,14 +72,13 @@ const pingResultSchema = z.object({
     "x-chart-label": "Max Latency",
     "x-chart-unit": "ms",
   }).optional(),
-  failedAssertion: pingAssertionSchema.optional(),
   error: healthResultString({
     "x-chart-type": "status",
     "x-chart-label": "Error",
   }).optional(),
 });
 
-export type PingResult = z.infer<typeof pingResultSchema>;
+type PingResult = z.infer<typeof pingResultSchema>;
 
 /**
  * Aggregated metadata for buckets.
@@ -120,27 +105,51 @@ const pingAggregatedSchema = z.object({
   }),
 });
 
-export type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
+type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
 
 // ============================================================================
 // STRATEGY
 // ============================================================================
 
 export class PingHealthCheckStrategy
-  implements HealthCheckStrategy<PingConfig, PingResult, PingAggregatedResult>
+  implements
+    HealthCheckStrategy<
+      PingConfig,
+      PingTransportClient,
+      PingResult,
+      PingAggregatedResult
+    >
 {
   id = "ping";
   displayName = "Ping Health Check";
   description = "ICMP ping check for network reachability and latency";
 
   config: Versioned<PingConfig> = new Versioned({
-    version: 1,
+    version: 2,
     schema: pingConfigSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Remove host/count (moved to PingCollector)",
+        migrate: (data: PingConfigV1): PingConfig => ({
+          timeout: data.timeout,
+        }),
+      },
+    ],
   });
 
   result: Versioned<PingResult> = new Versioned({
-    version: 1,
+    version: 2,
     schema: pingResultSchema,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description: "Migrate to createClient pattern (no result changes)",
+        migrate: (data: unknown) => data,
+      },
+    ],
   });
 
   aggregatedResult: Versioned<PingAggregatedResult> = new Versioned({
@@ -151,141 +160,108 @@ export class PingHealthCheckStrategy
   aggregateResult(
     runs: HealthCheckRunForAggregation<PingResult>[]
   ): PingAggregatedResult {
-    let totalPacketLoss = 0;
-    let totalLatency = 0;
-    let maxLatency = 0;
-    let errorCount = 0;
-    let validRuns = 0;
-
-    for (const run of runs) {
-      if (run.metadata?.error) {
-        errorCount++;
-        continue;
-      }
-      if (run.metadata) {
-        totalPacketLoss += run.metadata.packetLoss ?? 0;
-        if (run.metadata.avgLatency !== undefined) {
-          totalLatency += run.metadata.avgLatency;
-          validRuns++;
-        }
-        if (
-          run.metadata.maxLatency !== undefined &&
-          run.metadata.maxLatency > maxLatency
-        ) {
-          maxLatency = run.metadata.maxLatency;
-        }
-      }
+    const validRuns = runs.filter((r) => r.metadata);
+
+    if (validRuns.length === 0) {
+      return { avgPacketLoss: 0, avgLatency: 0, maxLatency: 0, errorCount: 0 };
     }
 
-    return {
-      avgPacketLoss: runs.length > 0 ? totalPacketLoss / runs.length : 0,
-      avgLatency: validRuns > 0 ? totalLatency / validRuns : 0,
-      maxLatency,
-      errorCount,
-    };
+    const packetLosses = validRuns
+      .map((r) => r.metadata?.packetLoss)
+      .filter((l): l is number => typeof l === "number");
+
+    const avgPacketLoss =
+      packetLosses.length > 0
+        ? Math.round(
+            (packetLosses.reduce((a, b) => a + b, 0) / packetLosses.length) * 10
+          ) / 10
+        : 0;
+
+    const latencies = validRuns
+      .map((r) => r.metadata?.avgLatency)
+      .filter((l): l is number => typeof l === "number");
+
+    const avgLatency =
+      latencies.length > 0
+        ? Math.round(
+            (latencies.reduce((a, b) => a + b, 0) / latencies.length) * 10
+          ) / 10
+        : 0;
+
+    const maxLatencies = validRuns
+      .map((r) => r.metadata?.maxLatency)
+      .filter((l): l is number => typeof l === "number");
+
+    const maxLatency = maxLatencies.length > 0 ? Math.max(...maxLatencies) : 0;
+
+    const errorCount = validRuns.filter(
+      (r) => r.metadata?.error !== undefined
+    ).length;
+
+    return { avgPacketLoss, avgLatency, maxLatency, errorCount };
   }
 
-  async execute(config: PingConfig): Promise<HealthCheckResult<PingResult>> {
+  async createClient(
+    config: PingConfig
+  ): Promise<ConnectedClient<PingTransportClient>> {
     const validatedConfig = this.config.validate(config);
-    const start = performance.now();
 
-    try {
-      const result = await this.runPing(
-        validatedConfig.host,
-        validatedConfig.count,
-        validatedConfig.timeout
-      );
-
-      const latencyMs =
-        result.avgLatency ?? Math.round(performance.now() - start);
-
-      // Evaluate assertions using shared utility
-      const failedAssertion = evaluateAssertions(validatedConfig.assertions, {
-        packetLoss: result.packetLoss,
-        avgLatency: result.avgLatency,
-        maxLatency: result.maxLatency,
-        minLatency: result.minLatency,
-      });
-
-      if (failedAssertion) {
-        return {
-          status: "unhealthy",
-          latencyMs,
-          message: `Assertion failed: ${failedAssertion.field} ${failedAssertion.operator} ${failedAssertion.value}`,
-          metadata: { ...result, failedAssertion },
-        };
-      }
-
-      // Check for packet loss without explicit assertion
-      if (result.packetLoss === 100) {
-        return {
-          status: "unhealthy",
-          latencyMs,
-          message: `Host ${validatedConfig.host} is unreachable (100% packet loss)`,
-          metadata: result,
-        };
-      }
+    const client: PingTransportClient = {
+      exec: async (request: PingRequest): Promise<PingResultType> => {
+        return this.runPing(
+          request.host,
+          request.count,
+          request.timeout ?? validatedConfig.timeout
+        );
+      },
+    };
 
-      return {
-        status: "healthy",
-        latencyMs,
-        message: `Ping to ${validatedConfig.host}: ${result.packetsReceived}/${
-          result.packetsSent
-        } packets, avg ${result.avgLatency?.toFixed(1)}ms`,
-        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 : "Ping failed",
-        metadata: {
-          packetsSent: validatedConfig.count,
-          packetsReceived: 0,
-          packetLoss: 100,
-          error: isError ? error.name : "UnknownError",
-        },
-      };
-    }
+    return {
+      client,
+      close: () => {
+        // Ping is stateless, nothing to close
+      },
+    };
   }
 
-  /**
-   * Execute ping using Bun subprocess.
-   * Uses system ping command for cross-platform compatibility.
-   */
   private async runPing(
     host: string,
     count: number,
     timeout: number
-  ): Promise<Omit<PingResult, "failedAssertion" | "error">> {
+  ): Promise<PingResultType> {
     const isMac = process.platform === "darwin";
     const args = isMac
       ? ["-c", String(count), "-W", String(Math.ceil(timeout / 1000)), host]
       : ["-c", String(count), "-W", String(Math.ceil(timeout / 1000)), host];
 
-    const proc = Bun.spawn(["ping", ...args], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
+    try {
+      const proc = Bun.spawn({
+        cmd: ["ping", ...args],
+        stdout: "pipe",
+        stderr: "pipe",
+      });
 
-    const output = await new Response(proc.stdout).text();
-    const exitCode = await proc.exited;
+      const output = await new Response(proc.stdout).text();
+      const exitCode = await proc.exited;
 
-    // Parse ping output
-    return this.parsePingOutput(output, count, exitCode);
+      return this.parsePingOutput(output, count, exitCode);
+    } catch (error_) {
+      const error = error_ instanceof Error ? error_.message : String(error_);
+      return {
+        packetsSent: count,
+        packetsReceived: 0,
+        packetLoss: 100,
+        error,
+      };
+    }
   }
 
-  /**
-   * Parse ping command output to extract statistics.
-   */
   private parsePingOutput(
     output: string,
     expectedCount: number,
     _exitCode: number
-  ): Omit<PingResult, "failedAssertion" | "error"> {
-    // Match statistics line: "X packets transmitted, Y received"
+  ): PingResultType {
+    // Parse packet statistics
     const statsMatch = output.match(
       /(\d+) packets transmitted, (\d+) (?:packets )?received/
     );
@@ -298,18 +274,22 @@ export class PingHealthCheckStrategy
         ? Math.round(((packetsSent - packetsReceived) / packetsSent) * 100)
         : 100;
 
-    // Match latency line: "min/avg/max" or "min/avg/max/mdev"
-    const latencyMatch = output.match(/= ([\d.]+)\/([\d.]+)\/([\d.]+)/);
+    // Parse latency statistics (format varies by OS)
+    // macOS: round-trip min/avg/max/stddev = 0.043/0.059/0.082/0.016 ms
+    // Linux: rtt min/avg/max/mdev = 0.039/0.049/0.064/0.009 ms
+    const latencyMatch = output.match(
+      /(?:round-trip|rtt) min\/avg\/max\/(?:stddev|mdev) = ([\d.]+)\/([\d.]+)\/([\d.]+)/
+    );
+
+    let minLatency: number | undefined;
+    let avgLatency: number | undefined;
+    let maxLatency: number | undefined;
 
-    const minLatency = latencyMatch
-      ? Number.parseFloat(latencyMatch[1])
-      : undefined;
-    const avgLatency = latencyMatch
-      ? Number.parseFloat(latencyMatch[2])
-      : undefined;
-    const maxLatency = latencyMatch
-      ? Number.parseFloat(latencyMatch[3])
-      : undefined;
+    if (latencyMatch) {
+      minLatency = Number.parseFloat(latencyMatch[1]);
+      avgLatency = Number.parseFloat(latencyMatch[2]);
+      maxLatency = Number.parseFloat(latencyMatch[3]);
+    }
 
     return {
       packetsSent,
@@ -318,6 +298,9 @@ export class PingHealthCheckStrategy
       minLatency,
       avgLatency,
       maxLatency,
+      ...(packetLoss === 100 && {
+        error: "Host unreachable or 100% packet loss",
+      }),
     };
   }
 }

package/src/transport-client.ts

@@ -0,0 +1,28 @@
+import type { TransportClient } from "@checkstack/common";
+
+/**
+ * Ping request.
+ */
+export interface PingRequest {
+  host: string;
+  count: number;
+  timeout: number;
+}
+
+/**
+ * Ping result.
+ */
+export interface PingResult {
+  packetsSent: number;
+  packetsReceived: number;
+  packetLoss: number;
+  minLatency?: number;
+  avgLatency?: number;
+  maxLatency?: number;
+  error?: string;
+}
+
+/**
+ * Ping transport client for ICMP checks.
+ */
+export type PingTransportClient = TransportClient<PingRequest, PingResult>;