@checkstack/healthcheck-dns-backend 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @checkstack/healthcheck-dns-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-dns-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/lookup-collector.test.ts

@@ -4,7 +4,9 @@ import type { DnsTransportClient } from "./transport-client";
 
 describe("LookupCollector", () => {
   const createMockClient = (
-    response: { values: string[]; error?: string } = { values: ["192.168.1.1"] }
+    response: { values: string[]; error?: string } = {
+      values: ["192.168.1.1"],
+    },
   ): DnsTransportClient => ({
     exec: mock(() => Promise.resolve(response)),
   });
@@ -59,7 +61,7 @@ describe("LookupCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average resolution time", () => {
       const collector = new LookupCollector();
       const runs = [
@@ -89,7 +91,9 @@ describe("LookupCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgResolutionTimeMs).toBe(75);
       expect(aggregated.successRate).toBe(100);
@@ -120,7 +124,9 @@ describe("LookupCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.successRate).toBe(50);
     });

package/src/lookup-collector.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeRate,
+  averageStateSchema,
+  rateStateSchema,
+  type AverageState,
+  type RateState,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -50,7 +56,8 @@ const lookupResultSchema = healthResultSchema({
 
 export type LookupResult = z.infer<typeof lookupResultSchema>;
 
-const lookupAggregatedSchema = healthResultSchema({
+// UI-visible aggregated fields (for charts)
+const lookupAggregatedDisplaySchema = healthResultSchema({
   avgResolutionTimeMs: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Resolution Time",
@@ -63,6 +70,17 @@ const lookupAggregatedSchema = healthResultSchema({
   }),
 });
 
+// Internal state for incremental aggregation (not shown in charts)
+const lookupAggregatedInternalSchema = z.object({
+  _resolutionTime: averageStateSchema.optional(),
+  _success: rateStateSchema.optional(),
+});
+
+// Combined schema for storage
+const lookupAggregatedSchema = lookupAggregatedDisplaySchema.merge(
+  lookupAggregatedInternalSchema,
+);
+
 export type LookupAggregatedResult = z.infer<typeof lookupAggregatedSchema>;
 
 // ============================================================================
@@ -73,15 +91,12 @@ export type LookupAggregatedResult = z.infer<typeof lookupAggregatedSchema>;
  * Built-in DNS lookup collector.
  * Resolves DNS records and checks results.
  */
-export class LookupCollector
-  implements
-    CollectorStrategy<
-      DnsTransportClient,
-      LookupConfig,
-      LookupResult,
-      LookupAggregatedResult
-    >
-{
+export class LookupCollector implements CollectorStrategy<
+  DnsTransportClient,
+  LookupConfig,
+  LookupResult,
+  LookupAggregatedResult
+> {
   id = "lookup";
   displayName = "DNS Lookup";
   description = "Resolve DNS records and check the results";
@@ -124,28 +139,30 @@ export class LookupCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<LookupResult>[]
+  mergeResult(
+    existing: LookupAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<LookupResult>,
   ): LookupAggregatedResult {
-    const times = runs
-      .map((r) => r.metadata?.resolutionTimeMs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
-    const recordCounts = runs
-      .map((r) => r.metadata?.recordCount)
-      .filter((v): v is number => typeof v === "number");
+    // Merge resolution time average
+    const resolutionTimeState = mergeAverage(
+      existing?._resolutionTime as AverageState | undefined,
+      metadata?.resolutionTimeMs,
+    );
 
-    const successCount = recordCounts.filter((c) => c > 0).length;
+    // Merge success rate (recordCount > 0 means success)
+    const isSuccess = (metadata?.recordCount ?? 0) > 0;
+    const successState = mergeRate(
+      existing?._success as RateState | undefined,
+      isSuccess,
+    );
 
     return {
-      avgResolutionTimeMs:
-        times.length > 0
-          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
-          : 0,
-      successRate:
-        recordCounts.length > 0
-          ? Math.round((successCount / recordCounts.length) * 100)
-          : 0,
+      avgResolutionTimeMs: resolutionTimeState.avg,
+      successRate: successState.rate,
+      _resolutionTime: resolutionTimeState,
+      _success: successState,
     };
   }
 }

package/src/strategy.test.ts

@@ -15,7 +15,7 @@ describe("DnsHealthCheckStrategy", () => {
       resolveMx?: { priority: number; exchange: string }[] | Error;
       resolveTxt?: string[][] | Error;
       resolveNs?: string[] | Error;
-    } = {}
+    } = {},
   ): ResolverFactory => {
     return () =>
       ({
@@ -23,34 +23,34 @@ describe("DnsHealthCheckStrategy", () => {
         resolve4: mock(() =>
           config.resolve4 instanceof Error
             ? Promise.reject(config.resolve4)
-            : Promise.resolve(config.resolve4 ?? [])
+            : Promise.resolve(config.resolve4 ?? []),
         ),
         resolve6: mock(() =>
           config.resolve6 instanceof Error
             ? Promise.reject(config.resolve6)
-            : Promise.resolve(config.resolve6 ?? [])
+            : Promise.resolve(config.resolve6 ?? []),
         ),
         resolveCname: mock(() =>
           config.resolveCname instanceof Error
             ? Promise.reject(config.resolveCname)
-            : Promise.resolve(config.resolveCname ?? [])
+            : Promise.resolve(config.resolveCname ?? []),
         ),
         resolveMx: mock(() =>
           config.resolveMx instanceof Error
             ? Promise.reject(config.resolveMx)
-            : Promise.resolve(config.resolveMx ?? [])
+            : Promise.resolve(config.resolveMx ?? []),
         ),
         resolveTxt: mock(() =>
           config.resolveTxt instanceof Error
             ? Promise.reject(config.resolveTxt)
-            : Promise.resolve(config.resolveTxt ?? [])
+            : Promise.resolve(config.resolveTxt ?? []),
         ),
         resolveNs: mock(() =>
           config.resolveNs instanceof Error
             ? Promise.reject(config.resolveNs)
-            : Promise.resolve(config.resolveNs ?? [])
+            : Promise.resolve(config.resolveNs ?? []),
         ),
-      } as DnsResolver);
+      }) as DnsResolver;
   };
 
   describe("createClient", () => {
@@ -102,7 +102,7 @@ describe("DnsHealthCheckStrategy", () => {
   describe("client.exec", () => {
     it("should return resolved values for successful A record resolution", async () => {
       const strategy = new DnsHealthCheckStrategy(
-        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8"] })
+        createMockResolver({ resolve4: ["1.2.3.4", "5.6.7.8"] }),
       );
       const connectedClient = await strategy.createClient({ timeout: 5000 });
 
@@ -118,7 +118,7 @@ describe("DnsHealthCheckStrategy", () => {
 
     it("should return error for DNS error", async () => {
       const strategy = new DnsHealthCheckStrategy(
-        createMockResolver({ resolve4: new Error("NXDOMAIN") })
+        createMockResolver({ resolve4: new Error("NXDOMAIN") }),
       );
       const connectedClient = await strategy.createClient({ timeout: 5000 });
 
@@ -139,7 +139,7 @@ describe("DnsHealthCheckStrategy", () => {
             { priority: 0, exchange: "mail1.example.com" },
             { priority: 10, exchange: "mail2.example.com" },
           ],
-        })
+        }),
       );
       const connectedClient = await strategy.createClient({ timeout: 5000 });
 
@@ -154,7 +154,7 @@ describe("DnsHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const strategy = new DnsHealthCheckStrategy();
       const runs = [
@@ -184,7 +184,9 @@ describe("DnsHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgResolutionTime).toBe(15);
       expect(aggregated.failureCount).toBe(0);
@@ -221,7 +223,9 @@ describe("DnsHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      // Merge runs incrementally
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.errorCount).toBe(1);
       expect(aggregated.failureCount).toBe(2);

package/src/strategy.ts

@@ -5,6 +5,12 @@ import {
   Versioned,
   z,
   type ConnectedClient,
+  mergeCounter,
+  mergeAverage,
+  averageStateSchema,
+  counterStateSchema,
+  type CounterState,
+  type AverageState,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -73,7 +79,8 @@ type DnsResult = z.infer<typeof dnsResultSchema>;
 /**
  * Aggregated metadata for buckets.
  */
-const dnsAggregatedSchema = healthResultSchema({
+// UI-visible aggregated fields (for charts)
+const dnsAggregatedDisplaySchema = healthResultSchema({
   avgResolutionTime: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Resolution Time",
@@ -89,6 +96,18 @@ const dnsAggregatedSchema = healthResultSchema({
   }),
 });
 
+// Internal state for incremental aggregation (not shown in charts)
+const dnsAggregatedInternalSchema = z.object({
+  _resolutionTime: averageStateSchema.optional(),
+  _failures: counterStateSchema.optional(),
+  _errors: counterStateSchema.optional(),
+});
+
+// Combined schema for storage
+const dnsAggregatedSchema = dnsAggregatedDisplaySchema.merge(
+  dnsAggregatedInternalSchema,
+);
+
 type DnsAggregatedResult = z.infer<typeof dnsAggregatedSchema>;
 
 // ============================================================================
@@ -101,7 +120,7 @@ export interface DnsResolver {
   resolve6(hostname: string): Promise<string[]>;
   resolveCname(hostname: string): Promise<string[]>;
   resolveMx(
-    hostname: string
+    hostname: string,
   ): Promise<{ priority: number; exchange: string }[]>;
   resolveTxt(hostname: string): Promise<string[][]>;
   resolveNs(hostname: string): Promise<string[]>;
@@ -116,15 +135,12 @@ const defaultResolverFactory: ResolverFactory = () => new dns.Resolver();
 // STRATEGY
 // ============================================================================
 
-export class DnsHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      DnsConfig,
-      DnsTransportClient,
-      DnsResult,
-      DnsAggregatedResult
-    >
-{
+export class DnsHealthCheckStrategy implements HealthCheckStrategy<
+  DnsConfig,
+  DnsTransportClient,
+  DnsResult,
+  DnsAggregatedResult
+> {
   id = "dns";
   displayName = "DNS Health Check";
   description = "DNS record resolution with response validation";
@@ -169,39 +185,44 @@ export class DnsHealthCheckStrategy
     schema: dnsAggregatedSchema,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<DnsResult>[]
+  mergeResult(
+    existing: DnsAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<DnsResult>,
   ): DnsAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
-
-    if (validRuns.length === 0) {
-      return { avgResolutionTime: 0, failureCount: 0, errorCount: 0 };
-    }
+    const metadata = run.metadata;
+
+    // Merge resolution time average
+    const resolutionTimeState = mergeAverage(
+      existing?._resolutionTime as AverageState | undefined,
+      metadata?.resolutionTimeMs,
+    );
+
+    // Merge failure count (recordCount === 0 means failure)
+    const isFailure = metadata?.recordCount === 0;
+    const failureState = mergeCounter(
+      existing?._failures as CounterState | undefined,
+      isFailure,
+    );
+
+    // Merge error count
+    const hasError = metadata?.error !== undefined;
+    const errorState = mergeCounter(
+      existing?._errors as CounterState | undefined,
+      hasError,
+    );
 
-    const resolutionTimes = validRuns
-      .map((r) => r.metadata?.resolutionTimeMs)
-      .filter((t): t is number => typeof t === "number");
-
-    const avgResolutionTime =
-      resolutionTimes.length > 0
-        ? Math.round(
-            resolutionTimes.reduce((a, b) => a + b, 0) / resolutionTimes.length
-          )
-        : 0;
-
-    const failureCount = validRuns.filter(
-      (r) => r.metadata?.recordCount === 0
-    ).length;
-
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
-
-    return { avgResolutionTime, failureCount, errorCount };
+    return {
+      avgResolutionTime: resolutionTimeState.avg,
+      failureCount: failureState.count,
+      errorCount: errorState.count,
+      _resolutionTime: resolutionTimeState,
+      _failures: failureState,
+      _errors: errorState,
+    };
   }
 
   async createClient(
-    config: DnsConfig
+    config: DnsConfig,
   ): Promise<ConnectedClient<DnsTransportClient>> {
     const validatedConfig = this.config.validate(config);
     const resolver = this.resolverFactory();
@@ -214,14 +235,17 @@ export class DnsHealthCheckStrategy
       exec: async (request: DnsLookupRequest): Promise<DnsLookupResult> => {
         const timeout = validatedConfig.timeout;
         const timeoutPromise = new Promise<never>((_, reject) =>
-          setTimeout(() => reject(new Error("DNS resolution timeout")), timeout)
+          setTimeout(
+            () => reject(new Error("DNS resolution timeout")),
+            timeout,
+          ),
         );
 
         try {
           const resolvePromise = this.resolveRecords(
             resolver,
             request.hostname,
-            request.recordType
+            request.recordType,
           );
 
           const values = await Promise.race([resolvePromise, timeoutPromise]);
@@ -246,7 +270,7 @@ export class DnsHealthCheckStrategy
   private async resolveRecords(
     resolver: DnsResolver,
     hostname: string,
-    recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS"
+    recordType: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS",
   ): Promise<string[]> {
     switch (recordType) {
       case "A": {