@checkstack/healthcheck-tls-backend 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @checkstack/healthcheck-tls-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-tls-backend",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "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/certificate-collector.test.ts

@@ -76,7 +76,7 @@ describe("CertificateCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average days remaining", () => {
       const collector = new CertificateCollector();
       const runs = [
@@ -112,7 +112,8 @@ describe("CertificateCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgDaysRemaining).toBe(45);
       expect(aggregated.validRate).toBe(100);
@@ -153,7 +154,8 @@ describe("CertificateCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.validRate).toBe(50);
     });

package/src/certificate-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,
@@ -58,7 +64,7 @@ const certificateResultSchema = healthResultSchema({
 
 export type CertificateResult = z.infer<typeof certificateResultSchema>;
 
-const certificateAggregatedSchema = healthResultSchema({
+const certificateAggregatedDisplaySchema = healthResultSchema({
   avgDaysRemaining: healthResultNumber({
     "x-chart-type": "gauge",
     "x-chart-label": "Avg Days Remaining",
@@ -71,6 +77,17 @@ const certificateAggregatedSchema = healthResultSchema({
   }),
 });
 
+const certificateAggregatedInternalSchema = z.object({
+  _daysRemaining: averageStateSchema
+    .optional(),
+  _valid: rateStateSchema
+    .optional(),
+});
+
+const certificateAggregatedSchema = certificateAggregatedDisplaySchema.merge(
+  certificateAggregatedInternalSchema,
+);
+
 export type CertificateAggregatedResult = z.infer<
   typeof certificateAggregatedSchema
 >;
@@ -83,15 +100,12 @@ export type CertificateAggregatedResult = z.infer<
  * Built-in TLS certificate collector.
  * Returns certificate information from the TLS connection.
  */
-export class CertificateCollector
-  implements
-    CollectorStrategy<
-      TlsTransportClient,
-      CertificateConfig,
-      CertificateResult,
-      CertificateAggregatedResult
-    >
-{
+export class CertificateCollector implements CollectorStrategy<
+  TlsTransportClient,
+  CertificateConfig,
+  CertificateResult,
+  CertificateAggregatedResult
+> {
   id = "certificate";
   displayName = "TLS Certificate";
   description = "Check TLS certificate validity and expiration";
@@ -142,30 +156,27 @@ export class CertificateCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<CertificateResult>[]
+  mergeResult(
+    existing: CertificateAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<CertificateResult>,
   ): CertificateAggregatedResult {
-    const daysRemaining = runs
-      .map((r) => r.metadata?.daysRemaining)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
-    const validResults = runs
-      .map((r) => r.metadata?.valid)
-      .filter((v): v is boolean => typeof v === "boolean");
+    const daysState = mergeAverage(
+      existing?._daysRemaining as AverageState | undefined,
+      metadata?.daysRemaining,
+    );
 
-    const validCount = validResults.filter(Boolean).length;
+    const validState = mergeRate(
+      existing?._valid as RateState | undefined,
+      metadata?.valid,
+    );
 
     return {
-      avgDaysRemaining:
-        daysRemaining.length > 0
-          ? Math.round(
-              daysRemaining.reduce((a, b) => a + b, 0) / daysRemaining.length
-            )
-          : 0,
-      validRate:
-        validResults.length > 0
-          ? Math.round((validCount / validResults.length) * 100)
-          : 0,
+      avgDaysRemaining: daysState.avg,
+      validRate: validState.rate,
+      _daysRemaining: daysState,
+      _valid: validState,
     };
   }
 }

package/src/strategy.test.ts

@@ -164,7 +164,7 @@ describe("TlsHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const strategy = new TlsHealthCheckStrategy();
       const runs = [
@@ -204,7 +204,8 @@ describe("TlsHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgDaysUntilExpiry).toBe(25);
       expect(aggregated.minDaysUntilExpiry).toBe(20);
@@ -252,7 +253,8 @@ describe("TlsHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.invalidCount).toBe(2);
       expect(aggregated.errorCount).toBe(1);

package/src/strategy.ts

@@ -5,6 +5,14 @@ import {
   Versioned,
   z,
   type ConnectedClient,
+  mergeAverage,
+  averageStateSchema,
+  mergeCounter,
+  counterStateSchema,
+  mergeMinMax,
+  type AverageState,
+  type CounterState,
+  type MinMaxState,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
@@ -83,7 +91,7 @@ type TlsResult = z.infer<typeof tlsResultSchema>;
 /**
  * Aggregated metadata for buckets.
  */
-const tlsAggregatedSchema = healthResultSchema({
+const tlsAggregatedDisplaySchema = healthResultSchema({
   avgDaysUntilExpiry: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Days Until Expiry",
@@ -104,6 +112,19 @@ const tlsAggregatedSchema = healthResultSchema({
   }),
 });
 
+const tlsAggregatedInternalSchema = z.object({
+  _daysUntilExpiry: averageStateSchema.optional(),
+  _minDaysUntilExpiry: z
+    .object({ min: z.number(), max: z.number() })
+    .optional(),
+  _invalid: counterStateSchema.optional(),
+  _errors: counterStateSchema.optional(),
+});
+
+const tlsAggregatedSchema = tlsAggregatedDisplaySchema.merge(
+  tlsAggregatedInternalSchema,
+);
+
 type TlsAggregatedResult = z.infer<typeof tlsAggregatedSchema>;
 
 // ============================================================================
@@ -156,7 +177,7 @@ const defaultTlsClient: TlsClient = {
             getCipher: () => socket.getCipher(),
             end: () => socket.end(),
           });
-        }
+        },
       );
 
       socket.on("error", reject);
@@ -172,15 +193,12 @@ const defaultTlsClient: TlsClient = {
 // STRATEGY
 // ============================================================================
 
-export class TlsHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      TlsConfig,
-      TlsTransportClient,
-      TlsResult,
-      TlsAggregatedResult
-    >
-{
+export class TlsHealthCheckStrategy implements HealthCheckStrategy<
+  TlsConfig,
+  TlsTransportClient,
+  TlsResult,
+  TlsAggregatedResult
+> {
   id = "tls";
   displayName = "TLS/SSL Health Check";
   description = "SSL/TLS certificate validation and expiry monitoring";
@@ -222,50 +240,46 @@ export class TlsHealthCheckStrategy
     schema: tlsAggregatedSchema,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<TlsResult>[]
+  mergeResult(
+    existing: TlsAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<TlsResult>,
   ): TlsAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
-
-    if (validRuns.length === 0) {
-      return {
-        avgDaysUntilExpiry: 0,
-        minDaysUntilExpiry: 0,
-        invalidCount: 0,
-        errorCount: 0,
-      };
-    }
+    const metadata = run.metadata;
 
-    const daysValues = validRuns
-      .map((r) => r.metadata?.daysUntilExpiry)
-      .filter((d): d is number => typeof d === "number");
-
-    const avgDaysUntilExpiry =
-      daysValues.length > 0
-        ? Math.round(daysValues.reduce((a, b) => a + b, 0) / daysValues.length)
-        : 0;
+    const daysState = mergeAverage(
+      existing?._daysUntilExpiry as AverageState | undefined,
+      metadata?.daysUntilExpiry,
+    );
 
-    const minDaysUntilExpiry =
-      daysValues.length > 0 ? Math.min(...daysValues) : 0;
+    const minDaysState = mergeMinMax(
+      existing?._minDaysUntilExpiry as MinMaxState | undefined,
+      metadata?.daysUntilExpiry,
+    );
 
-    const invalidCount = validRuns.filter(
-      (r) => r.metadata?.isValid === false
-    ).length;
+    const invalidState = mergeCounter(
+      existing?._invalid as CounterState | undefined,
+      metadata?.isValid === false,
+    );
 
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
+    const errorState = mergeCounter(
+      existing?._errors as CounterState | undefined,
+      metadata?.error !== undefined,
+    );
 
     return {
-      avgDaysUntilExpiry,
-      minDaysUntilExpiry,
-      invalidCount,
-      errorCount,
+      avgDaysUntilExpiry: daysState.avg,
+      minDaysUntilExpiry: minDaysState.min,
+      invalidCount: invalidState.count,
+      errorCount: errorState.count,
+      _daysUntilExpiry: daysState,
+      _minDaysUntilExpiry: minDaysState,
+      _invalid: invalidState,
+      _errors: errorState,
     };
   }
 
   async createClient(
-    config: TlsConfig
+    config: TlsConfig,
   ): Promise<ConnectedClient<TlsTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
@@ -280,7 +294,7 @@ export class TlsHealthCheckStrategy
     const cert = connection.getPeerCertificate();
     const validTo = new Date(cert.valid_to);
     const daysUntilExpiry = Math.floor(
-      (validTo.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
+      (validTo.getTime() - Date.now()) / (1000 * 60 * 60 * 24),
     );
 
     const certInfo: TlsCertificateInfo = {