@checkstack/healthcheck-backend 0.0.2

package/src/aggregation.test.ts

@@ -0,0 +1,373 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { HealthCheckService } from "./service";
+
+describe("HealthCheckService.getAggregatedHistory", () => {
+  // Mock database and registry
+  let mockDb: ReturnType<typeof createMockDb>;
+  let mockRegistry: ReturnType<typeof createMockRegistry>;
+  let service: HealthCheckService;
+
+  function createMockDb() {
+    return {
+      select: mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve([])),
+          })),
+        })),
+      })),
+      query: {
+        healthCheckConfigurations: {
+          findFirst: mock(() => Promise.resolve(null)) as ReturnType<
+            typeof mock<
+              () => Promise<{ id: string; strategyId: string } | null>
+            >
+          >,
+        },
+      },
+    };
+  }
+
+  function createMockRegistry() {
+    return {
+      register: mock(),
+      getStrategies: mock(() => []),
+      getStrategy: mock(() => ({
+        id: "http",
+        displayName: "HTTP",
+        config: { version: 1, schema: {} },
+        aggregatedResult: { version: 1, schema: {} },
+        execute: mock(),
+        aggregateResult: mock((runs: unknown[]) => ({
+          totalRuns: runs.length,
+          customMetric: "aggregated",
+        })),
+      })),
+    };
+  }
+
+  beforeEach(() => {
+    mockDb = createMockDb();
+    mockRegistry = createMockRegistry();
+    service = new HealthCheckService(mockDb as never, mockRegistry as never);
+  });
+
+  describe("bucket size selection", () => {
+    it("auto-selects hourly for ranges <= 7 days", async () => {
+      const startDate = new Date("2024-01-01T00:00:00Z");
+      const endDate = new Date("2024-01-07T00:00:00Z");
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          bucketSize: "auto",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      expect(result.buckets).toEqual([]);
+    });
+
+    it("auto-selects daily for ranges > 7 days", async () => {
+      const startDate = new Date("2024-01-01T00:00:00Z");
+      const endDate = new Date("2024-01-15T00:00:00Z");
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate,
+          endDate,
+          bucketSize: "auto",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      expect(result.buckets).toEqual([]);
+    });
+  });
+
+  describe("bucketing and metrics calculation", () => {
+    it("groups runs into hourly buckets and calculates metrics", async () => {
+      const runs = [
+        {
+          id: "run-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: { statusCode: 200 },
+          timestamp: new Date("2024-01-01T10:15:00Z"),
+        },
+        {
+          id: "run-2",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 150,
+          result: { statusCode: 200 },
+          timestamp: new Date("2024-01-01T10:30:00Z"),
+        },
+        {
+          id: "run-3",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "unhealthy" as const,
+          latencyMs: 300,
+          result: { statusCode: 500 },
+          timestamp: new Date("2024-01-01T11:00:00Z"),
+        },
+      ];
+
+      // Setup mock to return runs
+      mockDb.select = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve(runs)),
+          })),
+        })),
+      }));
+
+      mockDb.query.healthCheckConfigurations.findFirst = mock(() =>
+        Promise.resolve({ id: "config-1", strategyId: "http" })
+      );
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate: new Date("2024-01-01T00:00:00Z"),
+          endDate: new Date("2024-01-01T23:59:59Z"),
+          bucketSize: "hourly",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      expect(result.buckets).toHaveLength(2);
+
+      // First bucket (10:00)
+      const bucket10 = result.buckets.find(
+        (b) => b.bucketStart.getHours() === 10
+      );
+      expect(bucket10).toBeDefined();
+      expect(bucket10!.runCount).toBe(2);
+      expect(bucket10!.healthyCount).toBe(2);
+      expect(bucket10!.unhealthyCount).toBe(0);
+      expect(bucket10!.successRate).toBe(1);
+      expect(bucket10!.avgLatencyMs).toBe(125);
+
+      // Second bucket (11:00)
+      const bucket11 = result.buckets.find(
+        (b) => b.bucketStart.getHours() === 11
+      );
+      expect(bucket11).toBeDefined();
+      expect(bucket11!.runCount).toBe(1);
+      expect(bucket11!.healthyCount).toBe(0);
+      expect(bucket11!.unhealthyCount).toBe(1);
+      expect(bucket11!.successRate).toBe(0);
+    });
+
+    it("calculates p95 latency correctly", async () => {
+      // Create 20 runs with latencies 100-200 (step 5)
+      const runs = Array.from({ length: 20 }, (_, i) => ({
+        id: `run-${i}`,
+        systemId: "sys-1",
+        configurationId: "config-1",
+        status: "healthy" as const,
+        latencyMs: 100 + i * 5,
+        result: {},
+        timestamp: new Date("2024-01-01T10:00:00Z"),
+      }));
+
+      mockDb.select = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve(runs)),
+          })),
+        })),
+      }));
+
+      mockDb.query.healthCheckConfigurations.findFirst = mock(() =>
+        Promise.resolve({ id: "config-1", strategyId: "http" })
+      );
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate: new Date("2024-01-01T00:00:00Z"),
+          endDate: new Date("2024-01-01T23:59:59Z"),
+          bucketSize: "hourly",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      expect(result.buckets).toHaveLength(1);
+      expect(result.buckets[0].p95LatencyMs).toBe(190); // 95th percentile of 100-195
+    });
+  });
+
+  describe("strategy metadata aggregation", () => {
+    it("calls strategy.aggregateResult for each bucket", async () => {
+      const runs = [
+        {
+          id: "run-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: { statusCode: 200 },
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+        },
+      ];
+
+      mockDb.select = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve(runs)),
+          })),
+        })),
+      }));
+
+      mockDb.query.healthCheckConfigurations.findFirst = mock(() =>
+        Promise.resolve({ id: "config-1", strategyId: "http" })
+      );
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate: new Date("2024-01-01T00:00:00Z"),
+          endDate: new Date("2024-01-01T23:59:59Z"),
+          bucketSize: "hourly",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      const bucket = result.buckets[0];
+      expect("aggregatedResult" in bucket && bucket.aggregatedResult).toEqual({
+        totalRuns: 1,
+        customMetric: "aggregated",
+      });
+
+      // Verify getStrategy was called to look up the strategy
+      expect(mockRegistry.getStrategy).toHaveBeenCalled();
+    });
+
+    it("returns undefined aggregatedResult when no strategy found", async () => {
+      const runs = [
+        {
+          id: "run-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: {},
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+        },
+      ];
+
+      mockDb.select = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve(runs)),
+          })),
+        })),
+      }));
+
+      // No config found means no strategy
+      mockDb.query.healthCheckConfigurations.findFirst = mock(() =>
+        Promise.resolve(null)
+      );
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate: new Date("2024-01-01T00:00:00Z"),
+          endDate: new Date("2024-01-01T23:59:59Z"),
+          bucketSize: "hourly",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      const bucket = result.buckets[0];
+      expect(
+        "aggregatedResult" in bucket ? bucket.aggregatedResult : undefined
+      ).toBeUndefined();
+    });
+  });
+
+  describe("daily bucketing", () => {
+    it("groups runs into daily buckets", async () => {
+      const runs = [
+        {
+          id: "run-1",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          result: {},
+          timestamp: new Date("2024-01-01T10:00:00Z"),
+        },
+        {
+          id: "run-2",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "healthy" as const,
+          latencyMs: 150,
+          result: {},
+          timestamp: new Date("2024-01-01T22:00:00Z"),
+        },
+        {
+          id: "run-3",
+          systemId: "sys-1",
+          configurationId: "config-1",
+          status: "unhealthy" as const,
+          latencyMs: 200,
+          result: {},
+          timestamp: new Date("2024-01-02T05:00:00Z"),
+        },
+      ];
+
+      mockDb.select = mock(() => ({
+        from: mock(() => ({
+          where: mock(() => ({
+            orderBy: mock(() => Promise.resolve(runs)),
+          })),
+        })),
+      }));
+
+      mockDb.query.healthCheckConfigurations.findFirst = mock(() =>
+        Promise.resolve({ id: "config-1", strategyId: "http" })
+      );
+
+      const result = await service.getAggregatedHistory(
+        {
+          systemId: "sys-1",
+          configurationId: "config-1",
+          startDate: new Date("2024-01-01T00:00:00Z"),
+          endDate: new Date("2024-01-03T00:00:00Z"),
+          bucketSize: "daily",
+        },
+        { includeAggregatedResult: true }
+      );
+
+      expect(result.buckets).toHaveLength(2);
+
+      // Jan 1 bucket
+      const jan1 = result.buckets.find((b) => b.bucketStart.getDate() === 1);
+      expect(jan1).toBeDefined();
+      expect(jan1!.runCount).toBe(2);
+      expect(jan1!.bucketSize).toBe("daily");
+
+      // Jan 2 bucket
+      const jan2 = result.buckets.find((b) => b.bucketStart.getDate() === 2);
+      expect(jan2).toBeDefined();
+      expect(jan2!.runCount).toBe(1);
+    });
+  });
+});

package/src/hooks.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from "bun:test";
+import { healthCheckHooks } from "./hooks";
+
+describe("Health Check Hooks", () => {
+  it("should have systemDegraded hook with correct ID", () => {
+    expect(healthCheckHooks.systemDegraded.id).toBe(
+      "healthcheck.system.degraded"
+    );
+  });
+
+  it("should have systemHealthy hook with correct ID", () => {
+    expect(healthCheckHooks.systemHealthy.id).toBe(
+      "healthcheck.system.healthy"
+    );
+  });
+});

package/src/hooks.ts

@@ -0,0 +1,35 @@
+import { createHook } from "@checkstack/backend-api";
+
+/**
+ * Health check hooks for cross-plugin communication and external integrations.
+ * These hooks are registered as integration events for webhook subscriptions.
+ */
+export const healthCheckHooks = {
+  /**
+   * Emitted when a system's aggregated health status degrades.
+   * This fires when status changes from healthy to degraded/unhealthy,
+   * or from degraded to unhealthy.
+   */
+  systemDegraded: createHook<{
+    systemId: string;
+    systemName?: string;
+    previousStatus: string;
+    newStatus: string;
+    healthyChecks: number;
+    totalChecks: number;
+    timestamp: string;
+  }>("healthcheck.system.degraded"),
+
+  /**
+   * Emitted when a system's aggregated health status recovers to healthy.
+   * This fires when status changes from degraded/unhealthy to healthy.
+   */
+  systemHealthy: createHook<{
+    systemId: string;
+    systemName?: string;
+    previousStatus: string;
+    healthyChecks: number;
+    totalChecks: number;
+    timestamp: string;
+  }>("healthcheck.system.healthy"),
+} as const;

package/src/index.ts

@@ -0,0 +1,195 @@
+import {
+  setupHealthCheckWorker,
+  bootstrapHealthChecks,
+} from "./queue-executor";
+import * as schema from "./schema";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import {
+  permissionList,
+  pluginMetadata,
+  healthCheckContract,
+  healthcheckRoutes,
+  permissions,
+} from "@checkstack/healthcheck-common";
+import {
+  createBackendPlugin,
+  coreServices,
+  type EmitHookFn,
+} from "@checkstack/backend-api";
+import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import { z } from "zod";
+import { createHealthCheckRouter } from "./router";
+import { HealthCheckService } from "./service";
+import { catalogHooks } from "@checkstack/catalog-backend";
+import { CatalogApi } from "@checkstack/catalog-common";
+import { healthCheckHooks } from "./hooks";
+import { registerSearchProvider } from "@checkstack/command-backend";
+import { resolveRoute } from "@checkstack/common";
+
+// =============================================================================
+// Integration Event Payload Schemas
+// =============================================================================
+
+const systemDegradedPayloadSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string().optional(),
+  previousStatus: z.string(),
+  newStatus: z.string(),
+  healthyChecks: z.number(),
+  totalChecks: z.number(),
+  timestamp: z.string(),
+});
+
+const systemHealthyPayloadSchema = z.object({
+  systemId: z.string(),
+  systemName: z.string().optional(),
+  previousStatus: z.string(),
+  healthyChecks: z.number(),
+  totalChecks: z.number(),
+  timestamp: z.string(),
+});
+
+// Store emitHook reference for use during Phase 2 init
+let storedEmitHook: EmitHookFn | undefined;
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerPermissions(permissionList);
+
+    // Register hooks as integration events
+    const integrationEvents = env.getExtensionPoint(
+      integrationEventExtensionPoint
+    );
+
+    integrationEvents.registerEvent(
+      {
+        hook: healthCheckHooks.systemDegraded,
+        displayName: "System Health Degraded",
+        description:
+          "Fired when a system's health status transitions from healthy to degraded/unhealthy",
+        category: "Health",
+        payloadSchema: systemDegradedPayloadSchema,
+      },
+      pluginMetadata
+    );
+
+    integrationEvents.registerEvent(
+      {
+        hook: healthCheckHooks.systemHealthy,
+        displayName: "System Health Restored",
+        description: "Fired when a system's health status recovers to healthy",
+        category: "Health",
+        payloadSchema: systemHealthyPayloadSchema,
+      },
+      pluginMetadata
+    );
+
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+        healthCheckRegistry: coreServices.healthCheckRegistry,
+        rpc: coreServices.rpc,
+        rpcClient: coreServices.rpcClient,
+        queueManager: coreServices.queueManager,
+        signalService: coreServices.signalService,
+      },
+      // Phase 2: Register router and setup worker
+      init: async ({
+        logger,
+        database,
+        healthCheckRegistry,
+        rpc,
+        rpcClient,
+        queueManager,
+        signalService,
+      }) => {
+        logger.debug("🏥 Initializing Health Check Backend...");
+
+        // Create catalog client for notification delegation
+        const catalogClient = rpcClient.forPlugin(CatalogApi);
+
+        // Setup queue-based health check worker
+        await setupHealthCheckWorker({
+          db: database,
+          registry: healthCheckRegistry,
+          logger,
+          queueManager,
+          signalService,
+          catalogClient,
+          getEmitHook: () => storedEmitHook,
+        });
+
+        const healthCheckRouter = createHealthCheckRouter(
+          database as NodePgDatabase<typeof schema>,
+          healthCheckRegistry
+        );
+        rpc.registerRouter(healthCheckRouter, healthCheckContract);
+
+        // Register command palette commands
+        registerSearchProvider({
+          pluginMetadata,
+          commands: [
+            {
+              id: "create",
+              title: "Create Health Check",
+              subtitle: "Create a new health check configuration",
+              iconName: "HeartPulse",
+              route:
+                resolveRoute(healthcheckRoutes.routes.config) +
+                "?action=create",
+              requiredPermissions: [permissions.healthCheckManage],
+            },
+            {
+              id: "manage",
+              title: "Manage Health Checks",
+              subtitle: "Manage health check configurations",
+              iconName: "HeartPulse",
+              shortcuts: ["meta+shift+h", "ctrl+shift+h"],
+              route: resolveRoute(healthcheckRoutes.routes.config),
+              requiredPermissions: [permissions.healthCheckManage],
+            },
+          ],
+        });
+
+        logger.debug("✅ Health Check Backend initialized.");
+      },
+      afterPluginsReady: async ({
+        database,
+        queueManager,
+        logger,
+        onHook,
+        emitHook,
+        healthCheckRegistry,
+      }) => {
+        // Store emitHook for the queue worker (Closure-based Hook Getter pattern)
+        storedEmitHook = emitHook;
+        // Bootstrap all enabled health checks
+        await bootstrapHealthChecks({
+          db: database,
+          queueManager,
+          logger,
+        });
+
+        // Subscribe to catalog system deletion to clean up associations
+        const service = new HealthCheckService(database, healthCheckRegistry);
+        onHook(
+          catalogHooks.systemDeleted,
+          async (payload) => {
+            logger.debug(
+              `Cleaning up health check associations for deleted system: ${payload.systemId}`
+            );
+            await service.removeAllSystemAssociations(payload.systemId);
+          },
+          { mode: "work-queue", workerGroup: "system-cleanup" }
+        );
+
+        logger.debug("✅ Health Check Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});
+
+// Re-export hooks for other plugins to use
+export { healthCheckHooks } from "./hooks";