@checkstack/healthcheck-backend 1.2.0 → 1.3.0

package/src/queue-executor.test.ts

@@ -72,6 +72,7 @@ const createMockCatalogClient = () => ({
   // Other methods not used in queue-executor
   getEntities: mock(async () => ({ systems: [], groups: [] })),
   getSystems: mock(async () => ({ systems: [] })),
+  getSystem: mock(async () => null),
   getGroups: mock(async () => []),
   createSystem: mock(async () => ({})),
   updateSystem: mock(async () => ({})),
@@ -415,4 +416,140 @@ describe("Queue-Based Health Check Executor", () => {
       expect(mockSignalService.getRecordedSignals()).toHaveLength(0);
     });
   });
+
+  describe("executeHealthCheckJob - collector run-context", () => {
+    it("passes curated run-context to the collector (name falls back to id when configName is null)", async () => {
+      const mockDb = createMockDb();
+      const mockRegistry = createMockRegistry();
+      const mockLogger = createMockLogger();
+      const mockQueueManager = createMockQueueManager();
+      const mockCatalogClient = createMockCatalogClient();
+      const mockMaintenanceClient = createMockMaintenanceClient();
+      const mockIncidentClient = createMockIncidentClient();
+      const mockSignalService = createMockSignalService();
+
+      // Catalog resolves the system name.
+      (mockCatalogClient.getSystem as any) = mock(async () => ({
+        id: "system-1",
+        name: "web-01",
+      }));
+
+      // configName is null -> run-context check.name must fall back to id.
+      let selectCallCount = 0;
+      (mockDb.select as any) = mock(() => {
+        selectCallCount++;
+        if (selectCallCount === 2) {
+          return {
+            from: mock(() => ({
+              innerJoin: mock(() => ({
+                where: mock(() =>
+                  Promise.resolve([
+                    {
+                      configId: "config-1",
+                      configName: null,
+                      strategyId: "test-strategy",
+                      config: { timeout: 5000 },
+                      collectors: [
+                        { id: "col-1", collectorId: "test-collector", config: {} },
+                      ],
+                      interval: 45,
+                      enabled: true,
+                      paused: false,
+                      includeLocal: true,
+                      satelliteIds: [],
+                    },
+                  ]),
+                ),
+              })),
+            })),
+          };
+        }
+        return {
+          from: mock(() => ({
+            innerJoin: mock(() => ({
+              where: mock(() => Promise.resolve([])),
+            })),
+          })),
+        };
+      });
+
+      // Capture the run-context the collector receives.
+      let capturedRunContext: unknown;
+      const collectorExecute = mock(
+        async (params: { runContext?: unknown }) => {
+          capturedRunContext = params.runContext;
+          return { result: {} };
+        },
+      );
+      const mockCollectorRegistry = {
+        register: mock(() => {}),
+        getCollector: mock(() => ({
+          collector: {
+            id: "test-collector",
+            execute: collectorExecute,
+            mergeResult: mock(() => ({})),
+          },
+        })),
+        getCollectors: mock(() => []),
+      };
+
+      const queue =
+        mockQueueManager.getQueue<HealthCheckJobPayload>("health-checks");
+      let capturedHandler:
+        | ((job: { data: HealthCheckJobPayload }) => Promise<void>)
+        | undefined;
+      (queue.consume as any) = mock(
+        async (
+          handler: (job: { data: HealthCheckJobPayload }) => Promise<void>,
+        ) => {
+          capturedHandler = handler;
+        },
+      );
+
+      await setupHealthCheckWorker({
+        db: mockDb as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["db"],
+        registry: mockRegistry,
+        collectorRegistry: mockCollectorRegistry as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["collectorRegistry"],
+        logger: mockLogger,
+        queueManager: mockQueueManager,
+        signalService: mockSignalService,
+        catalogClient: mockCatalogClient as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["catalogClient"],
+        notificationClient: {
+          notifyForSubscription: () => Promise.resolve({ notifiedCount: 0 }),
+        } as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["notificationClient"],
+        maintenanceClient: mockMaintenanceClient as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["maintenanceClient"],
+        incidentClient: mockIncidentClient as unknown as Parameters<
+          typeof setupHealthCheckWorker
+        >[0]["incidentClient"],
+        getEmitHook: () => undefined,
+        cache: passthroughCache,
+      });
+
+      if (capturedHandler) {
+        // The collector runs early in the execution sequence; downstream
+        // aggregation/persistence touches DB surfaces the lightweight mock
+        // doesn't model, so tolerate a later throw — the run-context we
+        // assert on is captured synchronously at collector-execute time.
+        await capturedHandler({
+          data: { configId: "config-1", systemId: "system-1" },
+        }).catch(() => {});
+      }
+
+      expect(collectorExecute).toHaveBeenCalled();
+      expect(capturedRunContext).toEqual({
+        check: { id: "config-1", name: "config-1", intervalSeconds: 45 },
+        system: { id: "system-1", name: "web-01" },
+      });
+    });
+  });
 });

package/src/queue-executor.ts

@@ -8,6 +8,7 @@ import {
   type BaseStrategyConfig,
   type ConnectedClient,
   type TransportClient,
+  type CollectorRunContext,
 } from "@checkstack/backend-api";
 import { QueueManager } from "@checkstack/queue-api";
 import {
@@ -62,8 +63,13 @@ type IncidentClient = InferClient<typeof IncidentApi>;
 type NotificationClient = InferClient<typeof NotificationApi>;
 
 /**
- * Emit the checkCompleted hook if available.
- * Extracted to avoid duplicating the hook emission pattern across success/error paths.
+ * Emit the checkCompleted hook if available, plus the narrower
+ * `checkFailed` hook when the result wasn't `healthy` (so operators
+ * can wire a typed "trigger on failure" automation without having to
+ * filter `checkCompleted` themselves).
+ *
+ * Extracted to avoid duplicating the hook emission pattern across
+ * success/error paths.
  */
 async function emitCheckCompletedHook({
   getEmitHook,
@@ -81,14 +87,26 @@ async function emitCheckCompletedHook({
   result: Record<string, unknown> | undefined;
 }): Promise<void> {
   const emitHook = getEmitHook();
-  if (emitHook) {
-    await emitHook(healthCheckHooks.checkCompleted, {
+  if (!emitHook) return;
+  const timestamp = new Date().toISOString();
+  await emitHook(healthCheckHooks.checkCompleted, {
+    systemId,
+    configurationId,
+    status,
+    latencyMs,
+    result,
+    timestamp,
+  });
+  // Narrow follow-up — informational for automation triggers; the
+  // auto-incident pipeline still runs on its own thresholds.
+  if (status !== "healthy") {
+    await emitHook(healthCheckHooks.checkFailed, {
       systemId,
       configurationId,
       status,
       latencyMs,
       result,
-      timestamp: new Date().toISOString(),
+      timestamp,
     });
   }
 }
@@ -102,9 +120,11 @@ export interface HealthCheckJobPayload {
 }
 
 /**
- * Queue name for health check execution
+ * Queue name for health check execution. Exported so consumers like
+ * the `healthcheck.run_now` automation action can enqueue a one-off
+ * job without re-importing the recurring-job factory.
  */
-const HEALTH_CHECK_QUEUE = "health-checks";
+export const HEALTH_CHECK_QUEUE = "health-checks";
 
 /**
  * Worker group for health check execution (work-queue mode)
@@ -179,6 +199,14 @@ async function maybeOpenAutoIncidentForCheck(props: {
   systemName: string;
   configurationId: string;
   configurationName: string;
+  /**
+   * Same closure-based getter the queue executor uses elsewhere; let
+   * us fire the `flapping_detected` automation hook from inside the
+   * flapping evaluator without re-threading `emitHook` through every
+   * intermediate caller. Optional — when absent, the hook simply
+   * doesn't fire (e.g. in unit tests that don't care about it).
+   */
+  getEmitHook?: () => EmitHookFn | undefined;
   previousState: {
     checkStatuses: Array<{
       configurationId: string;
@@ -202,6 +230,7 @@ async function maybeOpenAutoIncidentForCheck(props: {
     systemName,
     configurationId,
     configurationName,
+    getEmitHook,
     previousState,
     newState,
   } = props;
@@ -287,6 +316,33 @@ async function maybeOpenAutoIncidentForCheck(props: {
         policy,
         recentTransitionCount: count,
       });
+
+      // Fire the informational `flapping_detected` automation hook
+      // independently of the auto-incident decision: an operator may
+      // care about flapping even with the auto-incident pipeline
+      // turned off.
+      if (
+        policy.flappingTrigger.enabled &&
+        count >= policy.flappingTrigger.transitions
+      ) {
+        const emit = getEmitHook?.();
+        if (emit) {
+          try {
+            await emit(healthCheckHooks.flappingDetected, {
+              systemId,
+              configurationId,
+              transitionCount: count,
+              windowMinutes: policy.flappingTrigger.windowMinutes,
+              timestamp: new Date().toISOString(),
+            });
+          } catch (error) {
+            logger.warn(
+              `Failed to emit healthcheck.flapping_detected hook for ${systemId}/${configurationId}:`,
+              error,
+            );
+          }
+        }
+      }
     } catch (error) {
       logger.warn(
         `Failed to record unhealthy transition for ${systemId}/${configurationId}:`,
@@ -612,6 +668,17 @@ async function executeHealthCheckJob(props: {
       logger.debug(`Could not fetch system name for ${systemId}, using ID`);
     }
 
+    // Curated, read-only run-context metadata exposed to collectors.
+    // Metadata only - never secrets or config.
+    const runContext: CollectorRunContext = {
+      check: {
+        id: configId,
+        name: configRow.configName || configId,
+        intervalSeconds: configRow.interval,
+      },
+      system: { id: systemId, name: systemName },
+    };
+
     const strategy = registry.getStrategy(configRow.strategyId);
     if (!strategy) {
       logger.warn(
@@ -662,6 +729,7 @@ async function executeHealthCheckJob(props: {
                 config: collectorEntry.config,
                 client: connectedClient!.client,
                 pluginId: configRow.strategyId,
+                runContext,
               });
 
               // Check for collector-level error
@@ -861,6 +929,7 @@ async function executeHealthCheckJob(props: {
         systemName,
         configurationId: configId,
         configurationName: configRow.configName,
+        getEmitHook,
         previousState,
         newState,
       });
@@ -971,16 +1040,20 @@ async function executeHealthCheckJob(props: {
       // Emit integration hooks for external integrations
       const emitHook = getEmitHook();
       if (emitHook) {
+        const healthyChecks = newState.checkStatuses.filter(
+          (c) => c.status === "healthy",
+        ).length;
+        const totalChecks = newState.checkStatuses.length;
+        const timestamp = new Date().toISOString();
+
         if (newState.status === "healthy" && previousStatus !== "healthy") {
           // Recovery: system became healthy
           await emitHook(healthCheckHooks.systemHealthy, {
             systemId,
             previousStatus,
-            healthyChecks: newState.checkStatuses.filter(
-              (c) => c.status === "healthy",
-            ).length,
-            totalChecks: newState.checkStatuses.length,
-            timestamp: new Date().toISOString(),
+            healthyChecks,
+            totalChecks,
+            timestamp,
           });
           logger.debug(
             `Emitted systemHealthy hook: ${previousStatus} → ${newState.status}`,
@@ -994,16 +1067,28 @@ async function executeHealthCheckJob(props: {
             systemId,
             previousStatus,
             newStatus: newState.status,
-            healthyChecks: newState.checkStatuses.filter(
-              (c) => c.status === "healthy",
-            ).length,
-            totalChecks: newState.checkStatuses.length,
-            timestamp: new Date().toISOString(),
+            healthyChecks,
+            totalChecks,
+            timestamp,
           });
           logger.debug(
             `Emitted systemDegraded hook: ${previousStatus} → ${newState.status}`,
           );
         }
+
+        // Umbrella hook — fires on every transition. Emitted alongside
+        // the directional hooks so existing subscribers stay unchanged
+        // while new automation triggers can react to any change.
+        if (previousStatus !== newState.status) {
+          await emitHook(healthCheckHooks.systemHealthChanged, {
+            systemId,
+            previousStatus,
+            newStatus: newState.status,
+            healthyChecks,
+            totalChecks,
+            timestamp,
+          });
+        }
       }
     }
 
@@ -1018,6 +1103,7 @@ async function executeHealthCheckJob(props: {
       systemName,
       configurationId: configId,
       configurationName: configRow.configName,
+      getEmitHook,
       previousState,
       newState,
     });
@@ -1120,16 +1206,20 @@ async function executeHealthCheckJob(props: {
       // Emit integration hooks for external integrations
       const emitHook = getEmitHook();
       if (emitHook) {
+        const healthyChecks = newState.checkStatuses.filter(
+          (c) => c.status === "healthy",
+        ).length;
+        const totalChecks = newState.checkStatuses.length;
+        const timestamp = new Date().toISOString();
+
         if (newState.status === "healthy" && previousStatus !== "healthy") {
           // Recovery: system became healthy
           await emitHook(healthCheckHooks.systemHealthy, {
             systemId,
             previousStatus,
-            healthyChecks: newState.checkStatuses.filter(
-              (c) => c.status === "healthy",
-            ).length,
-            totalChecks: newState.checkStatuses.length,
-            timestamp: new Date().toISOString(),
+            healthyChecks,
+            totalChecks,
+            timestamp,
           });
           logger.debug(
             `Emitted systemHealthy hook: ${previousStatus} → ${newState.status}`,
@@ -1143,16 +1233,28 @@ async function executeHealthCheckJob(props: {
             systemId,
             previousStatus,
             newStatus: newState.status,
-            healthyChecks: newState.checkStatuses.filter(
-              (c) => c.status === "healthy",
-            ).length,
-            totalChecks: newState.checkStatuses.length,
-            timestamp: new Date().toISOString(),
+            healthyChecks,
+            totalChecks,
+            timestamp,
           });
           logger.debug(
             `Emitted systemDegraded hook: ${previousStatus} → ${newState.status}`,
           );
         }
+
+        // Umbrella hook — fires on every transition. Emitted alongside
+        // the directional hooks so existing subscribers stay unchanged
+        // while new automation triggers can react to any change.
+        if (previousStatus !== newState.status) {
+          await emitHook(healthCheckHooks.systemHealthChanged, {
+            systemId,
+            previousStatus,
+            newStatus: newState.status,
+            healthyChecks,
+            totalChecks,
+            timestamp,
+          });
+        }
       }
     }
 
@@ -1167,6 +1269,7 @@ async function executeHealthCheckJob(props: {
       systemName,
       configurationId: configId,
       configurationName: configName,
+      getEmitHook,
       previousState,
       newState,
     });

package/src/router.test.ts

@@ -68,6 +68,10 @@ describe("HealthCheck Router", () => {
     getRedacted: mock(async () => undefined),
   };
 
+  const mockCatalogClient = {
+    getSystem: mock(async () => null),
+  };
+
   const router = createHealthCheckRouter({
     database: mockDb as never,
     registry: mockRegistry,
@@ -76,6 +80,7 @@ describe("HealthCheck Router", () => {
     getEmitHook: () => undefined,
     cache: passthroughCache,
     configService: mockConfigService as never,
+    catalogClient: mockCatalogClient as never,
   });
 
   it("getStrategies returns strategies from registry", async () => {

package/src/router.ts

@@ -17,6 +17,7 @@ import * as schema from "./schema";
 import { toJsonSchemaWithChartMeta } from "./schema-utils";
 import type { InferClient } from "@checkstack/common";
 import { GitOpsApi } from "@checkstack/gitops-common";
+import { CatalogApi } from "@checkstack/catalog-common";
 import type { HealthCheckCache } from "./cache";
 
 /**
@@ -33,14 +34,24 @@ export const createHealthCheckRouter = (opts: {
   getEmitHook: () => ((hook: { id: string }, payload: Record<string, unknown>) => Promise<void>) | undefined;
   cache: HealthCheckCache;
   configService: ConfigService;
+  catalogClient: InferClient<typeof CatalogApi>;
 }) => {
-  const { database, registry, collectorRegistry, getEmitHook, cache, configService } = opts;
+  const {
+    database,
+    registry,
+    collectorRegistry,
+    getEmitHook,
+    cache,
+    configService,
+    catalogClient,
+  } = opts;
   // Create service instance once - shared across all handlers
   const service = new HealthCheckService(
     database,
     registry,
     collectorRegistry,
     configService,
+    catalogClient,
   );
 
   // Create contract implementer with context type AND auto auth middleware

package/src/service-assignments.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { HealthCheckService } from "./service";
+
+/**
+ * Tests for getAssignmentsForSatellite run-context population:
+ * - assignments carry configName (from the config row's name)
+ * - systemName resolves via the optional catalog client, falling back to
+ *   systemId when no client is wired or the lookup fails.
+ */
+describe("HealthCheckService.getAssignmentsForSatellite", () => {
+  const SATELLITE_ID = "sat-1";
+
+  type Association = {
+    systemId: string;
+    configurationId: string;
+    satelliteIds: string[] | null;
+    enabled: boolean;
+  };
+
+  type Config = {
+    id: string;
+    name: string;
+    strategyId: string;
+    config: Record<string, unknown>;
+    collectors: unknown[] | null;
+    intervalSeconds: number;
+    paused: boolean;
+  };
+
+  let associations: Association[] = [];
+  let configs: Config[] = [];
+
+  /**
+   * Mock db: the method issues two distinct select shapes:
+   * - associations: .select({...}).from(systemHealthChecks)  -> awaited array
+   * - config:        .select().from(...).where(...)           -> awaited array
+   * We disambiguate by call order: the first select() resolves associations,
+   * subsequent select().from().where() resolve a single matching config.
+   */
+  function createMockDb() {
+    let firstSelect = true;
+    return {
+      select: mock(() => {
+        if (firstSelect) {
+          firstSelect = false;
+          return {
+            from: mock(() => Promise.resolve([...associations])),
+          };
+        }
+        return {
+          from: mock(() => ({
+            where: mock(() => {
+              // Return the next unmatched config in order; the loop fetches
+              // one config per matching association.
+              return Promise.resolve(configs.length > 0 ? [configs[0]] : []);
+            }),
+          })),
+        };
+      }),
+    };
+  }
+
+  beforeEach(() => {
+    associations = [];
+    configs = [];
+  });
+
+  it("populates configName and resolves systemName via the catalog client", async () => {
+    associations = [
+      {
+        systemId: "system-1",
+        configurationId: "config-1",
+        satelliteIds: [SATELLITE_ID],
+        enabled: true,
+      },
+    ];
+    configs = [
+      {
+        id: "config-1",
+        name: "API health",
+        strategyId: "http",
+        config: { url: "https://example.com" },
+        collectors: null,
+        intervalSeconds: 60,
+        paused: false,
+      },
+    ];
+
+    const getSystem = mock(() =>
+      Promise.resolve({ id: "system-1", name: "Production API" }),
+    );
+    const catalogClient = { getSystem } as never;
+
+    const mockDb = createMockDb();
+    const service = new HealthCheckService(
+      mockDb as never,
+      {} as never,
+      {} as never,
+      undefined,
+      catalogClient,
+    );
+
+    const result = await service.getAssignmentsForSatellite(SATELLITE_ID);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].configName).toBe("API health");
+    expect(result[0].systemName).toBe("Production API");
+    expect(getSystem).toHaveBeenCalledWith({ systemId: "system-1" });
+  });
+
+  it("falls back to systemId when no catalog client is provided", async () => {
+    associations = [
+      {
+        systemId: "system-1",
+        configurationId: "config-1",
+        satelliteIds: [SATELLITE_ID],
+        enabled: true,
+      },
+    ];
+    configs = [
+      {
+        id: "config-1",
+        name: "API health",
+        strategyId: "http",
+        config: {},
+        collectors: null,
+        intervalSeconds: 30,
+        paused: false,
+      },
+    ];
+
+    const mockDb = createMockDb();
+    const service = new HealthCheckService(
+      mockDb as never,
+      {} as never,
+      {} as never,
+    );
+
+    const result = await service.getAssignmentsForSatellite(SATELLITE_ID);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].configName).toBe("API health");
+    expect(result[0].systemName).toBe("system-1");
+  });
+
+  it("falls back to systemId when the catalog lookup throws", async () => {
+    associations = [
+      {
+        systemId: "system-1",
+        configurationId: "config-1",
+        satelliteIds: [SATELLITE_ID],
+        enabled: true,
+      },
+    ];
+    configs = [
+      {
+        id: "config-1",
+        name: "API health",
+        strategyId: "http",
+        config: {},
+        collectors: null,
+        intervalSeconds: 60,
+        paused: false,
+      },
+    ];
+
+    const getSystem = mock(() => Promise.reject(new Error("catalog down")));
+    const catalogClient = { getSystem } as never;
+
+    const mockDb = createMockDb();
+    const service = new HealthCheckService(
+      mockDb as never,
+      {} as never,
+      {} as never,
+      undefined,
+      catalogClient,
+    );
+
+    const result = await service.getAssignmentsForSatellite(SATELLITE_ID);
+
+    expect(result).toHaveLength(1);
+    expect(result[0].systemName).toBe("system-1");
+  });
+});