@checkstack/healthcheck-backend 1.2.0 → 1.4.0

package/src/index.ts

@@ -3,7 +3,6 @@ import {
   bootstrapHealthChecks,
 } from "./queue-executor";
 import { setupRetentionJob } from "./retention-job";
-import { setupAutoIncidentCloseJob } from "./auto-incident-close-job";
 import * as schema from "./schema";
 import {
   healthCheckAccessRules,
@@ -27,52 +26,59 @@ import {
   type CollectorRegistry,
 } from "@checkstack/backend-api";
 import type { QueueManager } from "@checkstack/queue-api";
-import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+  entityExtensionPoint,
+  type EntityHandle,
+} from "@checkstack/automation-backend";
+import {
+  HEALTH_ENTITY_KIND,
+  HealthEntityStateSchema,
+  createHealthEntityRead,
+  deriveHealthTriggerEvents,
+  healthChangeToPayload,
+  type HealthEntityState,
+} from "./health-entity";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
-import { z } from "zod";
+import { secretResolverRef } from "@checkstack/secrets-backend";
 import { createHealthCheckRouter } from "./router";
 import { HealthCheckService } from "./service";
+import {
+  assignmentArtifactType,
+  createHealthCheckActions,
+  healthCheckTriggers,
+} from "./automations";
 import { registerHealthcheckGitOpsKinds, registerHealthcheckGitOpsDocumentation } from "./healthcheck-gitops-kinds";
-import { catalogHooks } from "@checkstack/catalog-backend";
+import { CATALOG_SYSTEM_ENTITY_KIND } from "@checkstack/catalog-backend";
 import { satelliteHooks } from "@checkstack/satellite-backend";
-import { incidentHooks } from "@checkstack/incident-backend";
-import { eq, and, isNull } from "drizzle-orm";
-import { healthCheckAutoIncidents } from "./schema";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
 import { IncidentApi } from "@checkstack/incident-common";
 import { GitOpsApi } from "@checkstack/gitops-common";
-import { healthCheckHooks } from "./hooks";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { resolveRoute } from "@checkstack/common";
 import { createHealthCheckCache } from "./cache";
 
-// =============================================================================
-// 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;
 
+// The reactive `health` entity handle (§10.3). Defined in register() via
+// the entity extension point (buffered until automation-backend registers
+// the impl); mutations only fire from init() onward once the read accessor
+// has its db + service.
+let healthEntity: EntityHandle<HealthEntityState> | undefined;
+
+// PLUGIN-BACKED + COMPUTED kind: the `health` aggregate has no domain table and
+// no framework `entity_state` row — its current state is COMPUTED on read from
+// the durable `health_check_runs` (via `getSystemHealthStatus`). The db +
+// service are only available in init(), but the entity `read` accessor must be
+// supplied at `defineEntity` time in register(). These holders bridge the two;
+// init() sets them before any mutation runs (the queue worker — the only
+// mutation site — is set up in init() after these are bound).
+let healthEntityService: HealthCheckService | undefined;
+
 export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
@@ -82,33 +88,60 @@ export default createBackendPlugin({
       healthcheckGroupSubscription,
     ]);
 
-    // Register hooks as integration events
-    const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint,
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    // Buffered behind the extension point until automation-backend's
+    // register() runs. Actions are wired in afterPluginsReady where
+    // `emitHook` becomes available.
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
     );
+    for (const trigger of healthCheckTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .getExtensionPoint(automationArtifactTypeExtensionPoint)
+      .registerArtifactType(assignmentArtifactType, pluginMetadata);
 
-    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,
+    // ─── Reactive `health` entity (§10.3) ──────────────────────────────
+    // PLUGIN-BACKED + COMPUTED kind (Model B): the per-system aggregate has no
+    // domain table and NO framework `entity_state` row. `read` COMPUTES each
+    // system's `{ status, healthyChecks, totalChecks }` on demand from the same
+    // durable `health_check_runs` the rest of the plugin reads (via
+    // `getSystemHealthStatus`), gated on the system having at least one ENABLED
+    // check association — see `createHealthEntityRead`. A system with an enabled
+    // check but no runs yet resolves to the default-`healthy` baseline so a
+    // first-ever unhealthy run is a real `healthy → degraded` diff. The service
+    // is resolved in init() and bridged via the holder. The change →
+    // trigger-event deriver keeps the
+    // existing `healthcheck.system.degraded` / `.healthy` / `.health_changed`
+    // automations firing off the computed state.
+    const entityPoint = env.getExtensionPoint(entityExtensionPoint);
+    healthEntity = entityPoint.defineEntity<HealthEntityState>({
+      kind: HEALTH_ENTITY_KIND,
+      state: HealthEntityStateSchema,
+      read: (ids) => {
+        const service = healthEntityService;
+        if (!service) {
+          throw new Error(
+            "health entity read before init: service not yet resolved",
+          );
+        }
+        return createHealthEntityRead({ service })(ids);
       },
-      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,
-    );
+    });
+    entityPoint.registerChangeDeriver({
+      kind: HEALTH_ENTITY_KIND,
+      derive: deriveHealthTriggerEvents,
+      toPayload: healthChangeToPayload,
+    });
+    // Raw per-check samples + cursors are intentionally NON-reactive (§5):
+    // a firehose of individual runs would melt the wake-index; the
+    // aggregate is the entity.
+    entityPoint.declareNonReactiveState({
+      table: "health_check_runs",
+      reason: "raw-sample",
+      note: "High-frequency individual check executions. The per-system aggregate is the `health` entity; raw runs stay a numeric_state wake source only.",
+    });
 
     // ─── GitOps Entity Kind Registration ───────────────────────────────
     // Mutable refs — populated during init(), consumed by reconcile closures.
@@ -164,6 +197,7 @@ export default createBackendPlugin({
         signalService: coreServices.signalService,
         cacheManager: coreServices.cacheManager,
         config: coreServices.config,
+        secretResolver: secretResolverRef,
       },
       // Phase 2: Register router and setup worker
       init: async ({
@@ -177,6 +211,7 @@ export default createBackendPlugin({
         signalService,
         cacheManager,
         config,
+        secretResolver,
       }) => {
         logger.debug("🏥 Initializing Health Check Backend...");
 
@@ -186,6 +221,17 @@ export default createBackendPlugin({
         gitopsCollectorRegistry = collectorRegistry;
         gitopsQueueManager = queueManager;
 
+        // Bind the COMPUTE-ON-READ accessor's db + service for the `health`
+        // entity (defined in register()). From here onward the entity `read`
+        // computes each system's aggregate from durable `health_check_runs`,
+        // and the queue worker (set up just below — the only mutation site)
+        // drives writes through `handle.mutate`.
+        healthEntityService = new HealthCheckService(
+          database,
+          healthCheckRegistry,
+          collectorRegistry,
+        );
+
         // Create catalog client for notification delegation
         const catalogClient = rpcClient.forPlugin(CatalogApi);
 
@@ -221,7 +267,9 @@ export default createBackendPlugin({
           maintenanceClient,
           incidentClient,
           getEmitHook: () => storedEmitHook,
+          getHealthEntity: () => healthEntity,
           cache,
+          secretResolver,
         });
 
         // Setup retention job for tiered storage (daily aggregation)
@@ -231,15 +279,12 @@ export default createBackendPlugin({
           queueManager,
         });
 
-        // Setup auto-incident close worker (ticks every 60s, closes
-        // auto-opened incidents whose systems have been steady-healthy
-        // for the cooldown).
-        await setupAutoIncidentCloseJob({
-          db: database,
-          logger,
-          queueManager,
-          incidentClient,
-        });
+        // The hardcoded auto-incident open/close path was removed — auto-
+        // incident behaviour is now built entirely by user automations
+        // (e.g. `healthcheck.system_degraded` + `for:` → `incident.create`).
+        // Flapping is detected by the automation engine's windowed-count gate
+        // on the `system_health_changed` trigger — healthcheck emits only the
+        // raw aggregated-health change (via the reactive `health` entity).
 
         const healthCheckRouter = createHealthCheckRouter({
           database: database as SafeDatabase<typeof schema>,
@@ -249,6 +294,9 @@ export default createBackendPlugin({
           getEmitHook: () => storedEmitHook,
           cache,
           configService: config,
+          catalogClient,
+          maintenanceClient,
+          logger,
         });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);
 
@@ -325,17 +373,37 @@ export default createBackendPlugin({
           healthCheckRegistry,
           collectorRegistry,
         );
-        onHook(
-          catalogHooks.systemDeleted,
-          async (payload) => {
+
+        // Register automation actions now that `emitHook` + `queueManager`
+        // are both available.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createHealthCheckActions({
+          service,
+          queueManager,
+          emitHook,
+        })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
+        // React to catalog system deletion (tombstone) via the reactive
+        // `catalog-system` entity instead of the (removed) `system.deleted`
+        // hook (§10.4). `work-queue` delivery preserved: association cleanup
+        // must run once per cluster, not per-instance.
+        entityPoint.onEntityChanged({
+          kind: CATALOG_SYSTEM_ENTITY_KIND,
+          handler: async (change) => {
+            if (change.next !== null) return; // tombstone only
+            const systemId = change.id;
             logger.debug(
-              `Cleaning up health check associations for deleted system: ${payload.systemId}`,
+              `Cleaning up health check associations for deleted system: ${systemId}`,
             );
-            await service.removeAllSystemAssociations(payload.systemId);
-            await healthCheckCache?.invalidateSystem(payload.systemId);
+            await service.removeAllSystemAssociations(systemId);
+            await healthCheckCache?.invalidateSystem(systemId);
           },
-          { mode: "work-queue", workerGroup: "system-cleanup" },
-        );
+          delivery: { mode: "work-queue", workerGroup: "system-cleanup" },
+        });
 
         // Subscribe to satellite deletion to scrub satellite IDs from associations
         onHook(
@@ -352,32 +420,6 @@ export default createBackendPlugin({
           { mode: "work-queue", workerGroup: "satellite-cleanup" },
         );
 
-        // Sync our auto-incident mapping when an incident is resolved.
-        // Without this, a manually-closed incident would still appear
-        // "active" in our mapping, blocking the require-recovery rule
-        // from re-evaluating fresh transitions.
-        onHook(
-          incidentHooks.incidentResolved,
-          async ({ incidentId }) => {
-            const updated = await database
-              .update(healthCheckAutoIncidents)
-              .set({ closedAt: new Date() })
-              .where(
-                and(
-                  eq(healthCheckAutoIncidents.incidentId, incidentId),
-                  isNull(healthCheckAutoIncidents.closedAt),
-                ),
-              )
-              .returning({ id: healthCheckAutoIncidents.id });
-            if (updated.length > 0) {
-              logger.debug(
-                `Marked auto-incident mapping closed for resolved incident ${incidentId}`,
-              );
-            }
-          },
-          { mode: "work-queue", workerGroup: "auto-incident-sync" },
-        );
-
         logger.debug("✅ Health Check Backend afterPluginsReady complete.");
       },
     });
@@ -386,3 +428,13 @@ export default createBackendPlugin({
 
 // Re-export hooks for other plugins to use
 export { healthCheckHooks } from "./hooks";
+
+// Re-export the reactive `health` entity surface so cross-plugin consumers
+// (slo, dependency) can subscribe via onEntityChanged + classify changes
+// without duplicating the kind id / transition predicate (§10.3).
+export {
+  HEALTH_ENTITY_KIND,
+  classifyHealthChange,
+  type HealthChangeClassification,
+  type HealthEntityState,
+} from "./health-entity";

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" },
+      });
+    });
+  });
 });