@checkstack/healthcheck-ping-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/healthcheck-ping-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-ping-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 { PingHealthCheckStrategy } 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 Ping Health Check Strategy...");
+        const strategy = new PingHealthCheckStrategy();
+        healthCheckRegistry.register(strategy);
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Ping Health Check backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "healthcheck-ping",
+});

package/src/strategy.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, it, mock, beforeEach } from "bun:test";
+import { PingHealthCheckStrategy } from "./strategy";
+
+// Mock Bun.spawn for testing
+const mockSpawn = mock(() => ({
+  stdout: new ReadableStream({
+    start(controller) {
+      controller.enqueue(
+        new TextEncoder().encode(
+          `PING 8.8.8.8 (8.8.8.8): 56 data bytes
+64 bytes from 8.8.8.8: icmp_seq=0 ttl=118 time=10.123 ms
+64 bytes from 8.8.8.8: icmp_seq=1 ttl=118 time=12.456 ms
+64 bytes from 8.8.8.8: icmp_seq=2 ttl=118 time=11.789 ms
+
+--- 8.8.8.8 ping statistics ---
+3 packets transmitted, 3 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 10.123/11.456/12.456/0.957 ms`
+        )
+      );
+      controller.close();
+    },
+  }),
+  stderr: new ReadableStream(),
+  exited: Promise.resolve(0),
+}));
+
+describe("PingHealthCheckStrategy", () => {
+  let strategy: PingHealthCheckStrategy;
+  const originalSpawn = Bun.spawn;
+
+  beforeEach(() => {
+    strategy = new PingHealthCheckStrategy();
+    mockSpawn.mockClear();
+    // @ts-expect-error - mocking global
+    Bun.spawn = mockSpawn;
+  });
+
+  afterEach(() => {
+    Bun.spawn = originalSpawn;
+  });
+
+  describe("execute", () => {
+    it("should return healthy for successful ping", async () => {
+      const result = await strategy.execute({
+        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);
+    });
+
+    it("should return unhealthy for 100% packet loss", async () => {
+      // @ts-expect-error - mocking global
+      Bun.spawn = mock(() => ({
+        stdout: new ReadableStream({
+          start(controller) {
+            controller.enqueue(
+              new TextEncoder().encode(
+                `PING 10.0.0.1 (10.0.0.1): 56 data bytes
+
+--- 10.0.0.1 ping statistics ---
+3 packets transmitted, 0 packets received, 100.0% packet loss`
+              )
+            );
+            controller.close();
+          },
+        }),
+        stderr: new ReadableStream(),
+        exited: Promise.resolve(1),
+      }));
+
+      const result = await strategy.execute({
+        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.status).toBe("healthy");
+    });
+
+    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 pass packet loss assertion", async () => {
+      const result = await strategy.execute({
+        host: "8.8.8.8",
+        count: 3,
+        timeout: 5000,
+        assertions: [{ field: "packetLoss", operator: "equals", value: 0 }],
+      });
+
+      expect(result.status).toBe("healthy");
+    });
+
+    it("should handle spawn errors gracefully", async () => {
+      Bun.spawn = mock(() => {
+        throw new Error("Command not found");
+      }) as typeof Bun.spawn;
+
+      const result = await strategy.execute({
+        host: "8.8.8.8",
+        count: 3,
+        timeout: 5000,
+      });
+
+      expect(result.status).toBe("unhealthy");
+      expect(result.metadata?.error).toBeDefined();
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate averages correctly", () => {
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 10,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            packetsSent: 3,
+            packetsReceived: 3,
+            packetLoss: 0,
+            avgLatency: 10,
+            maxLatency: 15,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 20,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            packetsSent: 3,
+            packetsReceived: 2,
+            packetLoss: 33,
+            avgLatency: 20,
+            maxLatency: 25,
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.avgPacketLoss).toBeCloseTo(16.5, 1);
+      expect(aggregated.avgLatency).toBeCloseTo(15, 1);
+      expect(aggregated.maxLatency).toBe(25);
+      expect(aggregated.errorCount).toBe(0);
+    });
+
+    it("should count errors", () => {
+      const runs = [
+        {
+          id: "1",
+          status: "unhealthy" as const,
+          latencyMs: 0,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            packetsSent: 3,
+            packetsReceived: 0,
+            packetLoss: 100,
+            error: "Timeout",
+          },
+        },
+      ];
+
+      const aggregated = strategy.aggregateResult(runs);
+
+      expect(aggregated.errorCount).toBe(1);
+    });
+  });
+});
+
+// Import afterEach
+import { afterEach } from "bun:test";

package/src/strategy.ts

@@ -0,0 +1,323 @@
+import {
+  HealthCheckStrategy,
+  HealthCheckResult,
+  HealthCheckRunForAggregation,
+  Versioned,
+  z,
+  numericField,
+  timeThresholdField,
+  evaluateAssertions,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+
+// ============================================================================
+// 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.
+ */
+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"),
+});
+
+export type PingConfig = z.infer<typeof pingConfigSchema>;
+
+/**
+ * Per-run result metadata.
+ */
+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(),
+  failedAssertion: pingAssertionSchema.optional(),
+  error: healthResultString({
+    "x-chart-type": "status",
+    "x-chart-label": "Error",
+  }).optional(),
+});
+
+export type PingResult = z.infer<typeof pingResultSchema>;
+
+/**
+ * Aggregated metadata for buckets.
+ */
+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",
+  }),
+  maxLatency: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Latency",
+    "x-chart-unit": "ms",
+  }),
+  errorCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Errors",
+  }),
+});
+
+export type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
+
+// ============================================================================
+// STRATEGY
+// ============================================================================
+
+export class PingHealthCheckStrategy
+  implements HealthCheckStrategy<PingConfig, PingResult, PingAggregatedResult>
+{
+  id = "ping";
+  displayName = "Ping Health Check";
+  description = "ICMP ping check for network reachability and latency";
+
+  config: Versioned<PingConfig> = new Versioned({
+    version: 1,
+    schema: pingConfigSchema,
+  });
+
+  result: Versioned<PingResult> = new Versioned({
+    version: 1,
+    schema: pingResultSchema,
+  });
+
+  aggregatedResult: Versioned<PingAggregatedResult> = new Versioned({
+    version: 1,
+    schema: pingAggregatedSchema,
+  });
+
+  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;
+        }
+      }
+    }
+
+    return {
+      avgPacketLoss: runs.length > 0 ? totalPacketLoss / runs.length : 0,
+      avgLatency: validRuns > 0 ? totalLatency / validRuns : 0,
+      maxLatency,
+      errorCount,
+    };
+  }
+
+  async execute(config: PingConfig): Promise<HealthCheckResult<PingResult>> {
+    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,
+        };
+      }
+
+      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",
+        },
+      };
+    }
+  }
+
+  /**
+   * 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">> {
+    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",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    // Parse ping output
+    return this.parsePingOutput(output, count, exitCode);
+  }
+
+  /**
+   * 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"
+    const statsMatch = output.match(
+      /(\d+) packets transmitted, (\d+) (?:packets )?received/
+    );
+    const packetsSent = statsMatch
+      ? Number.parseInt(statsMatch[1], 10)
+      : expectedCount;
+    const packetsReceived = statsMatch ? Number.parseInt(statsMatch[2], 10) : 0;
+    const packetLoss =
+      packetsSent > 0
+        ? 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.]+)/);
+
+    const minLatency = latencyMatch
+      ? Number.parseFloat(latencyMatch[1])
+      : undefined;
+    const avgLatency = latencyMatch
+      ? Number.parseFloat(latencyMatch[2])
+      : undefined;
+    const maxLatency = latencyMatch
+      ? Number.parseFloat(latencyMatch[3])
+      : undefined;
+
+    return {
+      packetsSent,
+      packetsReceived,
+      packetLoss,
+      minLatency,
+      avgLatency,
+      maxLatency,
+    };
+  }
+}

package/tsconfig.json

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