@checkstack/healthcheck-backend 0.0.2

package/src/state-evaluator.test.ts

@@ -0,0 +1,237 @@
+import { describe, expect, test } from "bun:test";
+import { evaluateHealthStatus } from "./state-evaluator";
+import type {
+  HealthCheckStatus,
+  ConsecutiveThresholds,
+  WindowThresholds,
+} from "@checkstack/healthcheck-common";
+
+// Helper to create runs with timestamps
+function createRuns(
+  statuses: HealthCheckStatus[]
+): { status: HealthCheckStatus; timestamp: Date }[] {
+  const now = Date.now();
+  return statuses.map((status, i) => ({
+    status,
+    timestamp: new Date(now - i * 60000), // 1 minute apart, newest first
+  }));
+}
+
+describe("evaluateHealthStatus", () => {
+  describe("with no runs", () => {
+    test("returns healthy when no runs exist", () => {
+      const result = evaluateHealthStatus({ runs: [] });
+      expect(result).toBe("healthy");
+    });
+  });
+
+  describe("consecutive mode", () => {
+    const thresholds: ConsecutiveThresholds = {
+      mode: "consecutive",
+      healthy: { minSuccessCount: 2 },
+      degraded: { minFailureCount: 2 },
+      unhealthy: { minFailureCount: 4 },
+    };
+
+    test("returns healthy after minSuccessCount consecutive successes", () => {
+      const runs = createRuns(["healthy", "healthy", "unhealthy"]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+
+    test("returns healthy with exactly minSuccessCount successes", () => {
+      const runs = createRuns(["healthy", "healthy"]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+
+    test("returns degraded after minFailureCount consecutive failures", () => {
+      const runs = createRuns(["unhealthy", "degraded", "healthy"]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("degraded");
+    });
+
+    test("returns unhealthy after higher minFailureCount", () => {
+      const runs = createRuns([
+        "unhealthy",
+        "unhealthy",
+        "degraded",
+        "unhealthy",
+        "healthy",
+      ]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("unhealthy");
+    });
+
+    test("returns latest status when not enough history", () => {
+      const runs = createRuns(["healthy"]); // Only 1 run, needs 2 for healthy
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+
+    test("handles mix of degraded and unhealthy as failures", () => {
+      const runs = createRuns(["degraded", "unhealthy"]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("degraded");
+    });
+
+    test("resets count when streak breaks", () => {
+      // Latest: 1 healthy, then failures - should use latest status
+      const runs = createRuns(["healthy", "unhealthy", "unhealthy"]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+  });
+
+  describe("window mode", () => {
+    const thresholds: WindowThresholds = {
+      mode: "window",
+      windowSize: 5,
+      degraded: { minFailureCount: 2 },
+      unhealthy: { minFailureCount: 4 },
+    };
+
+    test("returns healthy when failures below threshold", () => {
+      const runs = createRuns([
+        "healthy",
+        "unhealthy",
+        "healthy",
+        "healthy",
+        "healthy",
+      ]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+
+    test("returns degraded when failures at degraded threshold", () => {
+      const runs = createRuns([
+        "unhealthy",
+        "unhealthy",
+        "healthy",
+        "healthy",
+        "healthy",
+      ]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("degraded");
+    });
+
+    test("returns unhealthy when failures at unhealthy threshold", () => {
+      const runs = createRuns([
+        "unhealthy",
+        "degraded",
+        "unhealthy",
+        "unhealthy",
+        "healthy",
+      ]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("unhealthy");
+    });
+
+    test("only considers runs within window size", () => {
+      // Window is 5, so old failures outside window don't count
+      const runs = createRuns([
+        "healthy",
+        "healthy",
+        "healthy",
+        "healthy",
+        "healthy",
+        "unhealthy", // Outside window
+        "unhealthy",
+        "unhealthy",
+        "unhealthy",
+      ]);
+      expect(evaluateHealthStatus({ runs, thresholds })).toBe("healthy");
+    });
+
+    test("handles window smaller than run count", () => {
+      const smallWindowThresholds: WindowThresholds = {
+        mode: "window",
+        windowSize: 3,
+        degraded: { minFailureCount: 2 },
+        unhealthy: { minFailureCount: 3 },
+      };
+      const runs = createRuns([
+        "unhealthy",
+        "unhealthy",
+        "healthy",
+        "unhealthy",
+      ]);
+      expect(
+        evaluateHealthStatus({ runs, thresholds: smallWindowThresholds })
+      ).toBe("degraded");
+    });
+  });
+
+  describe("default thresholds", () => {
+    test("uses default consecutive mode when thresholds not provided", () => {
+      // Default: healthy after 1 success, degraded after 2 failures, unhealthy after 5
+      const runs = createRuns(["healthy"]);
+      expect(evaluateHealthStatus({ runs })).toBe("healthy");
+    });
+
+    test("default degraded after 2 consecutive failures", () => {
+      const runs = createRuns(["unhealthy", "unhealthy"]);
+      expect(evaluateHealthStatus({ runs })).toBe("degraded");
+    });
+
+    test("default unhealthy after 5 consecutive failures", () => {
+      const runs = createRuns([
+        "unhealthy",
+        "unhealthy",
+        "unhealthy",
+        "unhealthy",
+        "unhealthy",
+      ]);
+      expect(evaluateHealthStatus({ runs })).toBe("unhealthy");
+    });
+  });
+
+  describe("flickering scenarios", () => {
+    test("window mode handles flickering better than consecutive", () => {
+      // System that is mostly failing but occasionally succeeds
+      const runs = createRuns([
+        "unhealthy",
+        "healthy", // Flicker
+        "unhealthy",
+        "unhealthy",
+        "unhealthy",
+      ]);
+
+      const consecutiveThresholds: ConsecutiveThresholds = {
+        mode: "consecutive",
+        healthy: { minSuccessCount: 1 },
+        degraded: { minFailureCount: 2 },
+        unhealthy: { minFailureCount: 3 },
+      };
+
+      const windowThresholds: WindowThresholds = {
+        mode: "window",
+        windowSize: 5,
+        degraded: { minFailureCount: 2 },
+        unhealthy: { minFailureCount: 4 },
+      };
+
+      // Consecutive: sees only 1 failure at start, returns unhealthy (just the first)
+      expect(
+        evaluateHealthStatus({ runs, thresholds: consecutiveThresholds })
+      ).toBe("unhealthy");
+
+      // Window: sees 4 failures in window of 5, returns unhealthy
+      expect(evaluateHealthStatus({ runs, thresholds: windowThresholds })).toBe(
+        "unhealthy"
+      );
+    });
+
+    test("window mode shows recovery when mostly healthy", () => {
+      const runs = createRuns([
+        "healthy",
+        "unhealthy", // Flicker
+        "healthy",
+        "healthy",
+        "healthy",
+      ]);
+
+      const windowThresholds: WindowThresholds = {
+        mode: "window",
+        windowSize: 5,
+        degraded: { minFailureCount: 2 },
+        unhealthy: { minFailureCount: 4 },
+      };
+
+      // Only 1 failure in window - still healthy
+      expect(evaluateHealthStatus({ runs, thresholds: windowThresholds })).toBe(
+        "healthy"
+      );
+    });
+  });
+});

package/src/state-evaluator.ts

@@ -0,0 +1,105 @@
+import type {
+  StateThresholds,
+  ConsecutiveThresholds,
+  WindowThresholds,
+  HealthCheckStatus,
+} from "@checkstack/healthcheck-common";
+import { DEFAULT_STATE_THRESHOLDS } from "@checkstack/healthcheck-common";
+
+interface RunForEvaluation {
+  status: HealthCheckStatus;
+  timestamp: Date;
+}
+
+/**
+ * Evaluates the current health status based on recent runs and configured thresholds.
+ * Returns the evaluated status based on the threshold mode.
+ *
+ * @param runs - Recent health check runs, sorted by timestamp descending (newest first)
+ * @param thresholds - State threshold configuration (uses defaults if not provided)
+ */
+export function evaluateHealthStatus(props: {
+  runs: RunForEvaluation[];
+  thresholds?: StateThresholds;
+}): HealthCheckStatus {
+  const { runs, thresholds = DEFAULT_STATE_THRESHOLDS } = props;
+
+  if (runs.length === 0) {
+    // No runs yet - assume healthy (matches current behavior)
+    return "healthy";
+  }
+
+  return thresholds.mode === "consecutive"
+    ? evaluateConsecutive({ runs, thresholds })
+    : evaluateWindow({ runs, thresholds });
+}
+
+/**
+ * Consecutive mode: evaluates based on sequential identical results from most recent.
+ */
+function evaluateConsecutive(props: {
+  runs: RunForEvaluation[];
+  thresholds: ConsecutiveThresholds;
+}): HealthCheckStatus {
+  const { runs, thresholds } = props;
+
+  // Count consecutive identical results from most recent
+  let consecutiveFailures = 0;
+  let consecutiveSuccesses = 0;
+
+  for (const run of runs) {
+    if (run.status === "healthy") {
+      if (consecutiveFailures === 0) {
+        consecutiveSuccesses++;
+      } else {
+        break; // Streak ended
+      }
+    } else {
+      // degraded or unhealthy both count as failures for threshold purposes
+      if (consecutiveSuccesses === 0) {
+        consecutiveFailures++;
+      } else {
+        break; // Streak ended
+      }
+    }
+  }
+
+  // Evaluate thresholds (unhealthy > degraded > healthy)
+  if (consecutiveFailures >= thresholds.unhealthy.minFailureCount) {
+    return "unhealthy";
+  }
+  if (consecutiveFailures >= thresholds.degraded.minFailureCount) {
+    return "degraded";
+  }
+  if (consecutiveSuccesses >= thresholds.healthy.minSuccessCount) {
+    return "healthy";
+  }
+
+  // Edge case: not enough history to determine - use latest individual status
+  return runs[0].status;
+}
+
+/**
+ * Window mode: evaluates based on failure count within a sliding window.
+ * Better for flickering systems where failures are intermittent.
+ */
+function evaluateWindow(props: {
+  runs: RunForEvaluation[];
+  thresholds: WindowThresholds;
+}): HealthCheckStatus {
+  const { runs, thresholds } = props;
+
+  // Take only the window size worth of runs
+  const windowRuns = runs.slice(0, thresholds.windowSize);
+  const failureCount = windowRuns.filter((r) => r.status !== "healthy").length;
+
+  // Evaluate thresholds (unhealthy > degraded > healthy)
+  if (failureCount >= thresholds.unhealthy.minFailureCount) {
+    return "unhealthy";
+  }
+  if (failureCount >= thresholds.degraded.minFailureCount) {
+    return "degraded";
+  }
+
+  return "healthy";
+}

package/src/state-thresholds-migrations.ts

@@ -0,0 +1,15 @@
+import { Versioned } from "@checkstack/backend-api";
+import {
+  StateThresholdsSchema,
+  type StateThresholds,
+} from "@checkstack/healthcheck-common";
+
+/**
+ * Versioned handler for state thresholds.
+ * Provides parsing, validation, and migration capabilities.
+ */
+export const stateThresholds = new Versioned<StateThresholds>({
+  version: 1,
+  schema: StateThresholdsSchema,
+  migrations: [],
+});

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}