@checkstack/healthcheck-ssh-backend 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/healthcheck-ssh-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
+  - @checkstack/healthcheck-ssh-common@0.1.8
+
 ## 0.1.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ssh-backend",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -9,17 +9,17 @@
     "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/healthcheck-ssh-common": "0.1.6",
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1",
+    "@checkstack/healthcheck-ssh-common": "0.1.7",
     "ssh2": "^1.15.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "@types/ssh2": "^1.15.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/command-collector.test.ts

@@ -69,7 +69,7 @@ describe("CommandCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average execution time and success rate", () => {
       const collector = new CommandCollector();
       const runs = [
@@ -101,7 +101,8 @@ describe("CommandCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgExecutionTimeMs).toBe(75);
       expect(aggregated.successRate).toBe(100);
@@ -138,7 +139,8 @@ describe("CommandCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.successRate).toBe(50);
     });

package/src/command-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 commandResultSchema = healthResultSchema({
 
 export type CommandResult = z.infer<typeof commandResultSchema>;
 
-const commandAggregatedSchema = healthResultSchema({
+const commandAggregatedDisplaySchema = healthResultSchema({
   avgExecutionTimeMs: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Execution Time",
@@ -62,6 +68,17 @@ const commandAggregatedSchema = healthResultSchema({
   }),
 });
 
+const commandAggregatedInternalSchema = z.object({
+  _executionTime: averageStateSchema
+    .optional(),
+  _success: rateStateSchema
+    .optional(),
+});
+
+const commandAggregatedSchema = commandAggregatedDisplaySchema.merge(
+  commandAggregatedInternalSchema,
+);
+
 export type CommandAggregatedResult = z.infer<typeof commandAggregatedSchema>;
 
 // ============================================================================
@@ -73,15 +90,12 @@ export type CommandAggregatedResult = z.infer<typeof commandAggregatedSchema>;
  * Allows users to run arbitrary shell commands as check items.
  * This is the "basic mode" functionality exposed as a collector.
  */
-export class CommandCollector
-  implements
-    CollectorStrategy<
-      SshTransportClient,
-      CommandConfig,
-      CommandResult,
-      CommandAggregatedResult
-    >
-{
+export class CommandCollector implements CollectorStrategy<
+  SshTransportClient,
+  CommandConfig,
+  CommandResult,
+  CommandAggregatedResult
+> {
   /**
    * ID for this collector.
    * Built-in collectors are identified by ownerPlugin matching the strategy's plugin.
@@ -125,28 +139,28 @@ export class CommandCollector
     };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<CommandResult>[]
+  mergeResult(
+    existing: CommandAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<CommandResult>,
   ): CommandAggregatedResult {
-    const times = runs
-      .map((r) => r.metadata?.executionTimeMs)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
-    const exitCodes = runs
-      .map((r) => r.metadata?.exitCode)
-      .filter((v): v is number => typeof v === "number");
+    const executionTimeState = mergeAverage(
+      existing?._executionTime as AverageState | undefined,
+      metadata?.executionTimeMs,
+    );
 
-    const successCount = exitCodes.filter((code) => code === 0).length;
+    // Success is exit code 0
+    const successState = mergeRate(
+      existing?._success as RateState | undefined,
+      metadata?.exitCode === 0,
+    );
 
     return {
-      avgExecutionTimeMs:
-        times.length > 0
-          ? Math.round(times.reduce((a, b) => a + b, 0) / times.length)
-          : 0,
-      successRate:
-        exitCodes.length > 0
-          ? Math.round((successCount / exitCodes.length) * 100)
-          : 0,
+      avgExecutionTimeMs: executionTimeState.avg,
+      successRate: successState.rate,
+      _executionTime: executionTimeState,
+      _success: successState,
     };
   }
 }

package/src/strategy.test.ts

@@ -10,7 +10,7 @@ describe("SshHealthCheckStrategy", () => {
       stderr?: string;
       execError?: Error;
       connectError?: Error;
-    } = {}
+    } = {},
   ): SshClient => ({
     connect: mock(() =>
       config.connectError
@@ -23,10 +23,10 @@ describe("SshHealthCheckStrategy", () => {
                     exitCode: config.exitCode ?? 0,
                     stdout: config.stdout ?? "",
                     stderr: config.stderr ?? "",
-                  })
+                  }),
             ),
             end: mock(() => {}),
-          })
+          }),
     ),
   });
 
@@ -51,7 +51,7 @@ describe("SshHealthCheckStrategy", () => {
 
     it("should throw for connection error", async () => {
       const strategy = new SshHealthCheckStrategy(
-        createMockClient({ connectError: new Error("Connection refused") })
+        createMockClient({ connectError: new Error("Connection refused") }),
       );
 
       await expect(
@@ -61,7 +61,7 @@ describe("SshHealthCheckStrategy", () => {
           username: "user",
           password: "secret",
           timeout: 5000,
-        })
+        }),
       ).rejects.toThrow("Connection refused");
     });
   });
@@ -69,7 +69,7 @@ describe("SshHealthCheckStrategy", () => {
   describe("client.exec", () => {
     it("should execute command successfully", async () => {
       const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 0, stdout: "OK" })
+        createMockClient({ exitCode: 0, stdout: "OK" }),
       );
       const connectedClient = await strategy.createClient({
         host: "localhost",
@@ -90,7 +90,7 @@ describe("SshHealthCheckStrategy", () => {
 
     it("should return non-zero exit code for failed command", async () => {
       const strategy = new SshHealthCheckStrategy(
-        createMockClient({ exitCode: 1, stderr: "Error" })
+        createMockClient({ exitCode: 1, stderr: "Error" }),
       );
       const connectedClient = await strategy.createClient({
         host: "localhost",
@@ -109,7 +109,7 @@ describe("SshHealthCheckStrategy", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate averages correctly", () => {
       const strategy = new SshHealthCheckStrategy();
       const runs = [
@@ -139,7 +139,8 @@ describe("SshHealthCheckStrategy", () => {
         },
       ];
 
-      const aggregated = strategy.aggregateResult(runs);
+      let aggregated = strategy.mergeResult(undefined, runs[0]);
+      aggregated = strategy.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgConnectionTime).toBe(75);
       expect(aggregated.successRate).toBe(100);
@@ -148,22 +149,20 @@ describe("SshHealthCheckStrategy", () => {
 
     it("should count errors", () => {
       const strategy = new SshHealthCheckStrategy();
-      const runs = [
-        {
-          id: "1",
-          status: "unhealthy" as const,
-          latencyMs: 100,
-          checkId: "c1",
-          timestamp: new Date(),
-          metadata: {
-            connected: false,
-            connectionTimeMs: 100,
-            error: "Connection refused",
-          },
+      const run = {
+        id: "1",
+        status: "unhealthy" as const,
+        latencyMs: 100,
+        checkId: "c1",
+        timestamp: new Date(),
+        metadata: {
+          connected: false,
+          connectionTimeMs: 100,
+          error: "Connection refused",
         },
-      ];
+      };
 
-      const aggregated = strategy.aggregateResult(runs);
+      const aggregated = strategy.mergeResult(undefined, run);
 
       expect(aggregated.errorCount).toBe(1);
       expect(aggregated.successRate).toBe(0);

package/src/strategy.ts

@@ -7,6 +7,18 @@ import {
   configString,
   configNumber,
   type ConnectedClient,
+  mergeAverage,
+  averageStateSchema,
+  mergeRate,
+  rateStateSchema,
+  mergeCounter,
+  counterStateSchema,
+  mergeMinMax,
+  minMaxStateSchema,
+  type AverageState,
+  type RateState,
+  type CounterState,
+  type MinMaxState,
 } from "@checkstack/backend-api";
 import {
   healthResultBoolean,
@@ -69,7 +81,7 @@ type SshResult = z.infer<typeof sshResultSchema>;
 /**
  * Aggregated metadata for buckets.
  */
-const sshAggregatedSchema = healthResultSchema({
+const sshAggregatedDisplaySchema = healthResultSchema({
   avgConnectionTime: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Connection Time",
@@ -91,6 +103,19 @@ const sshAggregatedSchema = healthResultSchema({
   }),
 });
 
+const sshAggregatedInternalSchema = z.object({
+  _connectionTime: averageStateSchema
+    .optional(),
+  _maxConnectionTime: minMaxStateSchema.optional(),
+  _success: rateStateSchema
+    .optional(),
+  _errors: counterStateSchema.optional(),
+});
+
+const sshAggregatedSchema = sshAggregatedDisplaySchema.merge(
+  sshAggregatedInternalSchema,
+);
+
 type SshAggregatedResult = z.infer<typeof sshAggregatedSchema>;
 
 // ============================================================================
@@ -178,15 +203,12 @@ const defaultSshClient: SshClient = {
 // STRATEGY
 // ============================================================================
 
-export class SshHealthCheckStrategy
-  implements
-    HealthCheckStrategy<
-      SshConfig,
-      SshTransportClient,
-      SshResult,
-      SshAggregatedResult
-    >
-{
+export class SshHealthCheckStrategy implements HealthCheckStrategy<
+  SshConfig,
+  SshTransportClient,
+  SshResult,
+  SshAggregatedResult
+> {
   id = "ssh";
   displayName = "SSH Health Check";
   description = "SSH server connectivity and command execution health check";
@@ -212,48 +234,41 @@ export class SshHealthCheckStrategy
     schema: sshAggregatedSchema,
   });
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<SshResult>[]
+  mergeResult(
+    existing: SshAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<SshResult>,
   ): SshAggregatedResult {
-    const validRuns = runs.filter((r) => r.metadata);
-
-    if (validRuns.length === 0) {
-      return {
-        avgConnectionTime: 0,
-        maxConnectionTime: 0,
-        successRate: 0,
-        errorCount: 0,
-      };
-    }
-
-    const connectionTimes = validRuns
-      .map((r) => r.metadata?.connectionTimeMs)
-      .filter((t): t is number => typeof t === "number");
-
-    const avgConnectionTime =
-      connectionTimes.length > 0
-        ? Math.round(
-            connectionTimes.reduce((a, b) => a + b, 0) / connectionTimes.length
-          )
-        : 0;
-
-    const maxConnectionTime =
-      connectionTimes.length > 0 ? Math.max(...connectionTimes) : 0;
-
-    const successCount = validRuns.filter(
-      (r) => r.metadata?.connected === true
-    ).length;
-    const successRate = Math.round((successCount / validRuns.length) * 100);
-
-    const errorCount = validRuns.filter(
-      (r) => r.metadata?.error !== undefined
-    ).length;
+    const metadata = run.metadata;
+
+    const connectionTimeState = mergeAverage(
+      existing?._connectionTime as AverageState | undefined,
+      metadata?.connectionTimeMs,
+    );
+
+    const maxConnectionTimeState = mergeMinMax(
+      existing?._maxConnectionTime as MinMaxState | undefined,
+      metadata?.connectionTimeMs,
+    );
+
+    const successState = mergeRate(
+      existing?._success as RateState | undefined,
+      metadata?.connected,
+    );
+
+    const errorState = mergeCounter(
+      existing?._errors as CounterState | undefined,
+      metadata?.error !== undefined,
+    );
 
     return {
-      avgConnectionTime,
-      maxConnectionTime,
-      successRate,
-      errorCount,
+      avgConnectionTime: connectionTimeState.avg,
+      maxConnectionTime: maxConnectionTimeState.max,
+      successRate: successState.rate,
+      errorCount: errorState.count,
+      _connectionTime: connectionTimeState,
+      _maxConnectionTime: maxConnectionTimeState,
+      _success: successState,
+      _errors: errorState,
     };
   }
 
@@ -261,7 +276,7 @@ export class SshHealthCheckStrategy
    * Create a connected SSH transport client.
    */
   async createClient(
-    config: SshConfigInput
+    config: SshConfigInput,
   ): Promise<ConnectedClient<SshTransportClient>> {
     const validatedConfig = this.config.validate(config);