@checkstack/healthcheck-ping-backend 0.1.13 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @checkstack/healthcheck-ping-backend
 
+## 0.2.0
+
+### Minor Changes
+
+- 3dd1914: Migrate health check strategies to VersionedAggregated with \_type discriminator
+
+  All 13 health check strategies now use `VersionedAggregated` for their `aggregatedResult` property, enabling automatic bucket merging with 100% mathematical fidelity.
+
+  **Key changes:**
+
+  - **`_type` discriminator**: All aggregated state objects now include a required `_type` field (`"average"`, `"rate"`, `"counter"`, `"minmax"`) for reliable type detection
+  - The `HealthCheckStrategy` interface now requires `aggregatedResult` to be a `VersionedAggregated<AggregatedResultShape>`
+  - Strategy/collector `mergeResult` methods return state objects with `_type` (e.g., `{ _type: "average", _sum, _count, avg }`)
+  - `mergeAggregatedBucketResults`, `combineBuckets`, and `reaggregateBuckets` now require `registry` and `strategyId` parameters
+  - `HealthCheckService` constructor now requires both `registry` and `collectorRegistry` parameters
+  - Frontend `extractComputedValue` now uses `_type` discriminator for robust type detection
+
+  **Breaking Change**: State objects now require `_type`. Merge functions automatically add `_type` to output. The bucket merging functions and `HealthCheckService` now require additional required parameters.
+
+### Patch Changes
+
+- Updated dependencies [3dd1914]
+  - @checkstack/backend-api@0.7.0
+
+## 0.1.14
+
+### Patch Changes
+
+- 48c2080: Migrate aggregation from batch to incremental (`mergeResult`)
+
+  ### Breaking Changes (Internal)
+
+  - Replaced `aggregateResult(runs[])` with `mergeResult(existing, run)` interface across all HealthCheckStrategy and CollectorStrategy implementations
+
+  ### New Features
+
+  - Added incremental aggregation utilities in `@checkstack/backend-api`:
+    - `mergeCounter()` - track occurrences
+    - `mergeAverage()` - track sum/count, compute avg
+    - `mergeRate()` - track success/total, compute %
+    - `mergeMinMax()` - track min/max values
+  - Exported Zod schemas for internal state: `averageStateSchema`, `rateStateSchema`, `minMaxStateSchema`, `counterStateSchema`
+
+  ### Improvements
+
+  - Enables O(1) storage overhead by maintaining incremental aggregation state
+  - Prepares for real-time hourly aggregation without batch accumulation
+
+- Updated dependencies [f676e11]
+- Updated dependencies [48c2080]
+  - @checkstack/common@0.6.2
+  - @checkstack/backend-api@0.6.0
+  - @checkstack/healthcheck-common@0.8.2
+
 ## 0.1.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ping-backend",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -9,14 +9,14 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.1",
-    "@checkstack/common": "0.6.0",
-    "@checkstack/healthcheck-common": "0.7.0"
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
-    "@checkstack/tsconfig": "0.0.2",
-    "@checkstack/scripts": "0.1.0"
+    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/scripts": "0.1.1"
   }
 }

package/src/ping-collector.test.ts

@@ -82,7 +82,7 @@ describe("PingCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average packet loss and latency", () => {
       const collector = new PingCollector();
       const runs = [
@@ -114,10 +114,11 @@ describe("PingCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.avgPacketLoss).toBe(5);
-      expect(aggregated.avgLatency).toBe(15);
+      expect(aggregated.avgPacketLoss.avg).toBe(5);
+      expect(aggregated.avgLatency.avg).toBe(15);
     });
   });
 

package/src/ping-collector.ts

@@ -4,6 +4,10 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  VersionedAggregated,
+  aggregatedAverage,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -71,20 +75,24 @@ const pingResultSchema = healthResultSchema({
 
 export type PingResult = z.infer<typeof pingResultSchema>;
 
-const pingAggregatedSchema = healthResultSchema({
-  avgPacketLoss: healthResultNumber({
+// Aggregated result fields definition
+const pingAggregatedFields = {
+  avgPacketLoss: aggregatedAverage({
     "x-chart-type": "gauge",
     "x-chart-label": "Avg Packet Loss",
     "x-chart-unit": "%",
   }),
-  avgLatency: healthResultNumber({
+  avgLatency: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Latency",
     "x-chart-unit": "ms",
   }),
-});
+};
 
-export type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
+// Type inferred from field definitions
+export type PingAggregatedResult = InferAggregatedResult<
+  typeof pingAggregatedFields
+>;
 
 // ============================================================================
 // PING COLLECTOR
@@ -94,15 +102,12 @@ export type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
  * Built-in Ping collector.
  * Performs ICMP ping and checks latency.
  */
-export class PingCollector
-  implements
-    CollectorStrategy<
-      PingTransportClient,
-      PingConfig,
-      PingResult,
-      PingAggregatedResult
-    >
-{
+export class PingCollector implements CollectorStrategy<
+  PingTransportClient,
+  PingConfig,
+  PingResult,
+  PingAggregatedResult
+> {
   id = "ping";
   displayName = "ICMP Ping";
   description = "Ping a host and check latency";
@@ -113,9 +118,9 @@ export class PingCollector
 
   config = new Versioned({ version: 1, schema: pingConfigSchema });
   result = new Versioned({ version: 1, schema: pingResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: pingAggregatedSchema,
+    fields: pingAggregatedFields,
   });
 
   async execute({
@@ -145,30 +150,18 @@ export class PingCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<PingResult>[]
+  mergeResult(
+    existing: PingAggregatedResult | undefined,
+    run: 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");
+    const metadata = run.metadata;
 
     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,
+      avgPacketLoss: mergeAverage(
+        existing?.avgPacketLoss,
+        metadata?.packetLoss,
+      ),
+      avgLatency: mergeAverage(existing?.avgLatency, metadata?.avgLatency),
     };
   }
 }

package/src/strategy.test.ts

@@ -14,8 +14,8 @@ const mockSpawn = mock(() => ({
 
 --- 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`
-        )
+round-trip min/avg/max/stddev = 10.123/11.456/12.456/0.957 ms`,
+        ),
       );
       controller.close();
     },
@@ -83,8 +83,8 @@ describe("PingHealthCheckStrategy", () => {
                 `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`
-              )
+3 packets transmitted, 0 packets received, 100.0% packet loss`,
+              ),
             );
             controller.close();
           },
@@ -139,7 +139,7 @@ describe("PingHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const runs = [
         {
@@ -172,34 +172,34 @@ describe("PingHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
-      expect(aggregated.avgPacketLoss).toBeCloseTo(16.5, 1);
-      expect(aggregated.avgLatency).toBeCloseTo(15, 1);
-      expect(aggregated.maxLatency).toBe(25);
-      expect(aggregated.errorCount).toBe(0);
+      // (0 + 33) / 2 = 16.5
+      expect(aggregated.avgPacketLoss.avg).toBeCloseTo(16.5, 1);
+      expect(aggregated.avgLatency.avg).toBeCloseTo(15, 1);
+      expect(aggregated.maxLatency.max).toBe(25);
+      expect(aggregated.errorCount.count).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 run = {
+        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);
+      const aggregated = strategy.mergeResult(undefined, run);
 
-      expect(aggregated.errorCount).toBe(1);
+      expect(aggregated.errorCount.count).toBe(1);
     });
   });
 });

package/src/strategy.ts

@@ -2,8 +2,16 @@ import {
   HealthCheckStrategy,
   HealthCheckRunForAggregation,
   Versioned,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  aggregatedCounter,
+  mergeAverage,
+  mergeCounter,
+  mergeMinMax,
   z,
   type ConnectedClient,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -81,46 +89,41 @@ const pingResultSchema = healthResultSchema({
 
 type PingResult = z.infer<typeof pingResultSchema>;
 
-/**
- * Aggregated metadata for buckets.
- */
-const pingAggregatedSchema = healthResultSchema({
-  avgPacketLoss: healthResultNumber({
+/** Aggregated field definitions for bucket merging */
+const pingAggregatedFields = {
+  avgPacketLoss: aggregatedAverage({
     "x-chart-type": "gauge",
     "x-chart-label": "Avg Packet Loss",
     "x-chart-unit": "%",
   }),
-  avgLatency: healthResultNumber({
+  avgLatency: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Latency",
     "x-chart-unit": "ms",
   }),
-  maxLatency: healthResultNumber({
+  maxLatency: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Latency",
     "x-chart-unit": "ms",
   }),
-  errorCount: healthResultNumber({
+  errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
   }),
-});
+};
 
-type PingAggregatedResult = z.infer<typeof pingAggregatedSchema>;
+type PingAggregatedResult = InferAggregatedResult<typeof pingAggregatedFields>;
 
 // ============================================================================
 // STRATEGY
 // ============================================================================
 
-export class PingHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      PingConfig,
-      PingTransportClient,
-      PingResult,
-      PingAggregatedResult
-    >
-{
+export class PingHealthCheckStrategy implements HealthCheckStrategy<
+  PingConfig,
+  PingTransportClient,
+  PingResult,
+  typeof pingAggregatedFields
+> {
   id = "ping";
   displayName = "Ping Health Check";
   description = "ICMP ping check for network reachability and latency";
@@ -153,57 +156,34 @@ export class PingHealthCheckStrategy
     ],
   });
 
-  aggregatedResult: Versioned<PingAggregatedResult> = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: pingAggregatedSchema,
+    fields: pingAggregatedFields,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<PingResult>[]
+  mergeResult(
+    existing: PingAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<PingResult>,
   ): PingAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
+    const metadata = run.metadata;
 
-    if (validRuns.length === 0) {
-      return { avgPacketLoss: 0, avgLatency: 0, maxLatency: 0, errorCount: 0 };
-    }
-
-    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 avgPacketLoss = mergeAverage(
+      existing?.avgPacketLoss,
+      metadata?.packetLoss,
+    );
 
-    const maxLatencies = validRuns
-      .map((r) => r.metadata?.maxLatency)
-      .filter((l): l is number => typeof l === "number");
+    const avgLatency = mergeAverage(existing?.avgLatency, metadata?.avgLatency);
 
-    const maxLatency = maxLatencies.length > 0 ? Math.max(...maxLatencies) : 0;
+    const maxLatency = mergeMinMax(existing?.maxLatency, metadata?.maxLatency);
 
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
+    const hasError = metadata?.error !== undefined;
+    const errorCount = mergeCounter(existing?.errorCount, hasError);
 
     return { avgPacketLoss, avgLatency, maxLatency, errorCount };
   }
 
   async createClient(
-    config: PingConfig
+    config: PingConfig,
   ): Promise<ConnectedClient<PingTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
@@ -212,7 +192,7 @@ export class PingHealthCheckStrategy
         return this.runPing(
           request.host,
           request.count,
-          request.timeout ?? validatedConfig.timeout
+          request.timeout ?? validatedConfig.timeout,
         );
       },
     };
@@ -228,7 +208,7 @@ export class PingHealthCheckStrategy
   private async runPing(
     host: string,
     count: number,
-    timeout: number
+    timeout: number,
   ): Promise<PingResultType> {
     const isMac = process.platform === "darwin";
     const args = isMac
@@ -260,11 +240,11 @@ export class PingHealthCheckStrategy
   private parsePingOutput(
     output: string,
     expectedCount: number,
-    _exitCode: number
+    _exitCode: number,
   ): PingResultType {
     // Parse packet statistics
     const statsMatch = output.match(
-      /(\d+) packets transmitted, (\d+) (?:packets )?received/
+      /(\d+) packets transmitted, (\d+) (?:packets )?received/,
     );
     const packetsSent = statsMatch
       ? Number.parseInt(statsMatch[1], 10)
@@ -279,7 +259,7 @@ export class PingHealthCheckStrategy
     // 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.]+)/
+      /(?:round-trip|rtt) min\/avg\/max\/(?:stddev|mdev) = ([\d.]+)\/([\d.]+)\/([\d.]+)/,
     );
 
     let minLatency: number | undefined;