@checkstack/healthcheck-grpc-backend 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @checkstack/healthcheck-grpc-backend
 
+## 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-grpc-backend",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -9,15 +9,15 @@
     "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",
     "@grpc/grpc-js": "^1.9.0"
   },
   "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/health-collector.test.ts

@@ -65,7 +65,7 @@ describe("HealthCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average response time and serving rate", () => {
       const collector = new HealthCollector();
       const runs = [
@@ -87,7 +87,8 @@ describe("HealthCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgResponseTimeMs).toBe(75);
       expect(aggregated.servingRate).toBe(100);
@@ -118,7 +119,8 @@ describe("HealthCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.servingRate).toBe(50);
     });

package/src/health-collector.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  averageStateSchema,
+  mergeRate,
+  rateStateSchema,
+  type AverageState,
+  type RateState,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -49,7 +55,7 @@ const grpcHealthResultSchema = healthResultSchema({
 
 export type HealthResult = z.infer<typeof grpcHealthResultSchema>;
 
-const healthAggregatedSchema = healthResultSchema({
+const healthAggregatedDisplaySchema = healthResultSchema({
   avgResponseTimeMs: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Response Time",
@@ -62,6 +68,17 @@ const healthAggregatedSchema = healthResultSchema({
   }),
 });
 
+const healthAggregatedInternalSchema = z.object({
+  _responseTime: averageStateSchema
+    .optional(),
+  _serving: rateStateSchema
+    .optional(),
+});
+
+const healthAggregatedSchema = healthAggregatedDisplaySchema.merge(
+  healthAggregatedInternalSchema,
+);
+
 export type HealthAggregatedResult = z.infer<typeof healthAggregatedSchema>;
 
 // ============================================================================
@@ -72,15 +89,12 @@ export type HealthAggregatedResult = z.infer<typeof healthAggregatedSchema>;
  * Built-in gRPC health collector.
  * Checks gRPC health status using the standard Health Checking Protocol.
  */
-export class HealthCollector
-  implements
-    CollectorStrategy<
-      GrpcTransportClient,
-      HealthConfig,
-      HealthResult,
-      HealthAggregatedResult
-    >
-{
+export class HealthCollector implements CollectorStrategy<
+  GrpcTransportClient,
+  HealthConfig,
+  HealthResult,
+  HealthAggregatedResult
+> {
   id = "health";
   displayName = "gRPC Health Check";
   description = "Check gRPC service health status";
@@ -124,28 +138,27 @@ export class HealthCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<HealthResult>[]
+  mergeResult(
+    existing: HealthAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<HealthResult>,
   ): HealthAggregatedResult {
-    const times = runs
-      .map((r) => r.metadata?.responseTimeMs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
-    const servingResults = runs
-      .map((r) => r.metadata?.serving)
-      .filter((v): v is boolean => typeof v === "boolean");
+    const responseTimeState = mergeAverage(
+      existing?._responseTime as AverageState | undefined,
+      metadata?.responseTimeMs,
+    );
 
-    const servingCount = servingResults.filter(Boolean).length;
+    const servingState = mergeRate(
+      existing?._serving as RateState | undefined,
+      metadata?.serving,
+    );
 
     return {
-      avgResponseTimeMs:
-        times.length > 0
-          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
-          : 0,
-      servingRate:
-        servingResults.length > 0
-          ? Math.round((servingCount / servingResults.length) * 100)
-          : 0,
+      avgResponseTimeMs: responseTimeState.avg,
+      servingRate: servingState.rate,
+      _responseTime: responseTimeState,
+      _serving: servingState,
     };
   }
 }

package/src/strategy.test.ts

@@ -111,7 +111,7 @@ describe("GrpcHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const strategy = new GrpcHealthCheckStrategy();
       const runs = [
@@ -141,7 +141,8 @@ describe("GrpcHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgResponseTime).toBe(10);
       expect(aggregated.successRate).toBe(100);
@@ -179,7 +180,8 @@ describe("GrpcHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.errorCount).toBe(1);
       expect(aggregated.servingCount).toBe(0);

package/src/strategy.ts

@@ -5,6 +5,15 @@ import {
   Versioned,
   z,
   type ConnectedClient,
+  mergeAverage,
+  averageStateSchema,
+  mergeRate,
+  rateStateSchema,
+  mergeCounter,
+  counterStateSchema,
+  type AverageState,
+  type RateState,
+  type CounterState,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
@@ -83,7 +92,7 @@ type GrpcResult = z.infer<typeof grpcResultSchema>;
 /**
  * Aggregated metadata for buckets.
  */
-const grpcAggregatedSchema = healthResultSchema({
+const grpcAggregatedDisplaySchema = healthResultSchema({
   avgResponseTime: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Response Time",
@@ -104,6 +113,19 @@ const grpcAggregatedSchema = healthResultSchema({
   }),
 });
 
+const grpcAggregatedInternalSchema = z.object({
+  _responseTime: averageStateSchema
+    .optional(),
+  _success: rateStateSchema
+    .optional(),
+  _errors: counterStateSchema.optional(),
+  _serving: counterStateSchema.optional(),
+});
+
+const grpcAggregatedSchema = grpcAggregatedDisplaySchema.merge(
+  grpcAggregatedInternalSchema,
+);
+
 type GrpcAggregatedResult = z.infer<typeof grpcAggregatedSchema>;
 
 // ============================================================================
@@ -176,7 +198,7 @@ const defaultGrpcClient: GrpcHealthClient = {
           resolve({
             status: statusMap[response?.status ?? 0] ?? "UNKNOWN",
           });
-        }
+        },
       );
     });
   },
@@ -186,15 +208,12 @@ const defaultGrpcClient: GrpcHealthClient = {
 // STRATEGY
 // ============================================================================
 
-export class GrpcHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      GrpcConfig,
-      GrpcTransportClient,
-      GrpcResult,
-      GrpcAggregatedResult
-    >
-{
+export class GrpcHealthCheckStrategy implements HealthCheckStrategy<
+  GrpcConfig,
+  GrpcTransportClient,
+  GrpcResult,
+  GrpcAggregatedResult
+> {
   id = "grpc";
   displayName = "gRPC Health Check";
   description =
@@ -237,50 +256,46 @@ export class GrpcHealthCheckStrategy
     schema: grpcAggregatedSchema,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<GrpcResult>[]
+  mergeResult(
+    existing: GrpcAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<GrpcResult>,
   ): GrpcAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
-
-    if (validRuns.length === 0) {
-      return {
-        avgResponseTime: 0,
-        successRate: 0,
-        errorCount: 0,
-        servingCount: 0,
-      };
-    }
+    const metadata = run.metadata;
 
-    const responseTimes = validRuns
-      .map((r) => r.metadata?.responseTimeMs)
-      .filter((t): t is number => typeof t === "number");
+    const responseTimeState = mergeAverage(
+      existing?._responseTime as AverageState | undefined,
+      metadata?.responseTimeMs,
+    );
 
-    const avgResponseTime =
-      responseTimes.length > 0
-        ? Math.round(
-            responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length
-          )
-        : 0;
+    const successState = mergeRate(
+      existing?._success as RateState | undefined,
+      metadata?.status === "SERVING",
+    );
 
-    const servingCount = validRuns.filter(
-      (r) => r.metadata?.status === "SERVING"
-    ).length;
-    const successRate = Math.round((servingCount / validRuns.length) * 100);
+    const errorState = mergeCounter(
+      existing?._errors as CounterState | undefined,
+      metadata?.error !== undefined,
+    );
 
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
+    const servingState = mergeCounter(
+      existing?._serving as CounterState | undefined,
+      metadata?.status === "SERVING",
+    );
 
     return {
-      avgResponseTime,
-      successRate,
-      errorCount,
-      servingCount,
+      avgResponseTime: responseTimeState.avg,
+      successRate: successState.rate,
+      errorCount: errorState.count,
+      servingCount: servingState.count,
+      _responseTime: responseTimeState,
+      _success: successState,
+      _errors: errorState,
+      _serving: servingState,
     };
   }
 
   async createClient(
-    config: GrpcConfigInput
+    config: GrpcConfigInput,
   ): Promise<ConnectedClient<GrpcTransportClient>> {
     const validatedConfig = this.config.validate(config);