@checkstack/healthcheck-backend 1.1.4 → 1.3.0

package/src/router.ts

@@ -7,6 +7,7 @@ import {
   type HealthCheckRegistry,
   type SafeDatabase,
   type CollectorRegistry,
+  type ConfigService,
 } from "@checkstack/backend-api";
 import { healthCheckContract } from "@checkstack/healthcheck-common";
 import type { StrategyCategory } from "@checkstack/healthcheck-common";
@@ -16,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";
 
 /**
@@ -31,10 +33,26 @@ export const createHealthCheckRouter = (opts: {
   gitOpsClient: InferClient<typeof GitOpsApi>;
   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 } = 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);
+  const service = new HealthCheckService(
+    database,
+    registry,
+    collectorRegistry,
+    configService,
+    catalogClient,
+  );
 
   // Create contract implementer with context type AND auto auth middleware
   const os = implement(healthCheckContract)
@@ -222,6 +240,16 @@ export const createHealthCheckRouter = (opts: {
       }
     }),
 
+    getPlatformNotificationDefaults:
+      os.getPlatformNotificationDefaults.handler(async () => {
+        return service.getPlatformNotificationDefaults();
+      }),
+
+    setPlatformNotificationDefaults:
+      os.setPlatformNotificationDefaults.handler(async ({ input }) => {
+        await service.setPlatformNotificationDefaults(input);
+      }),
+
     getRetentionConfig: os.getRetentionConfig.handler(async ({ input }) => {
       return service.getRetentionConfig(input.systemId, input.configurationId);
     }),

package/src/schema.ts

@@ -9,10 +9,12 @@ import {
   timestamp,
   primaryKey,
   unique,
+  index,
 } from "drizzle-orm/pg-core";
 import type {
   StateThresholds,
   CollectorConfigEntry,
+  NotificationPolicy,
 } from "@checkstack/healthcheck-common";
 import type { VersionedRecord } from "@checkstack/backend-api";
 
@@ -100,6 +102,12 @@ export const systemHealthChecks = pgTable(
      * Defaults to true. Only relevant when satelliteIds is set.
      */
     includeLocal: boolean("include_local").default(true).notNull(),
+    /**
+     * Per-association notification policy. Null falls back to platform
+     * defaults (no suppression).
+     */
+    notificationPolicy:
+      jsonb("notification_policy").$type<NotificationPolicy>(),
     createdAt: timestamp("created_at").defaultNow().notNull(),
     updatedAt: timestamp("updated_at").defaultNow().notNull(),
   },
@@ -108,6 +116,74 @@ export const systemHealthChecks = pgTable(
   }),
 );
 
+/**
+ * Records each time a check's *evaluated* state transitions from
+ * non-unhealthy to unhealthy. Used to decide whether the per-check
+ * incident threshold (N transitions in M minutes) has been met.
+ * Pruned by the retention job alongside raw runs.
+ */
+export const healthCheckUnhealthyTransitions = pgTable(
+  "health_check_unhealthy_transitions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    configurationId: uuid("configuration_id")
+      .notNull()
+      .references(() => healthCheckConfigurations.id, { onDelete: "cascade" }),
+    systemId: text("system_id").notNull(),
+    transitionedAt: timestamp("transitioned_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    // Powers the threshold count query
+    // (WHERE config_id = ? AND system_id = ? AND transitioned_at > ?).
+    lookupIdx: index(
+      "health_check_unhealthy_transitions_lookup_idx",
+    ).on(t.configurationId, t.systemId, t.transitionedAt),
+  }),
+);
+
+/**
+ * Mapping of auto-opened incidents back to the system + check that
+ * triggered them. `closedAt` stays null while the incident is active;
+ * the auto-close worker sets it once the linked system has been
+ * steadily healthy for the cooldown.
+ *
+ * No FK to the incident table — that lives in another plugin's schema
+ * and we treat it as a soft reference (incident deletes are handled
+ * by the auto-close worker, which tolerates missing rows).
+ */
+export const healthCheckAutoIncidents = pgTable(
+  "health_check_auto_incidents",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    incidentId: uuid("incident_id").notNull(),
+    systemId: text("system_id").notNull(),
+    configurationId: uuid("configuration_id")
+      .notNull()
+      .references(() => healthCheckConfigurations.id, { onDelete: "cascade" }),
+    openedAt: timestamp("opened_at").defaultNow().notNull(),
+    closedAt: timestamp("closed_at"),
+    /**
+     * Auto-close cooldown snapshot taken when the incident was opened.
+     * `null` means "never auto-close" — the worker leaves this
+     * incident alone and an operator must resolve it manually. Stored
+     * per-row so a later policy change doesn't retroactively alter
+     * the close behaviour of incidents already in flight.
+     */
+    cooldownMinutes: integer("cooldown_minutes"),
+  },
+  (t) => ({
+    // Powers "is there an active auto-incident for this system?" check.
+    activeBySystemIdx: index(
+      "health_check_auto_incidents_active_by_system_idx",
+    ).on(t.systemId, t.closedAt),
+    // Powers "find the most recent close for this assignment" lookup
+    // used by the require-recovery-before-reopen check.
+    lastCloseByAssignmentIdx: index(
+      "health_check_auto_incidents_last_close_idx",
+    ).on(t.configurationId, t.systemId, t.closedAt),
+  }),
+);
+
 export const healthCheckRuns = pgTable("health_check_runs", {
   id: uuid("id").primaryKey().defaultRandom(),
   configurationId: uuid("configuration_id")

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

package/src/service-notification-policy.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, mock } from "bun:test";
+import { HealthCheckService } from "./service";
+import { createMockDb } from "@checkstack/test-utils-backend";
+import {
+  DEFAULT_NOTIFICATION_POLICY,
+  type NotificationPolicy,
+} from "@checkstack/healthcheck-common";
+
+/**
+ * Build a service whose only DB interaction is the chain used by
+ * `getAssignmentNotificationPolicy`. The chain ends in `.limit(1)` and
+ * returns the supplied rows verbatim. An optional in-memory platform
+ * default stands in for the ConfigService.
+ */
+function buildServiceWithRows(
+  rows: unknown[],
+  platformDefault?: NotificationPolicy,
+): HealthCheckService {
+  const mockDb = createMockDb();
+  const limitChain = mock(async () => rows);
+  const whereChain = mock(() => ({ limit: limitChain }));
+  const fromChain = mock(() => ({ where: whereChain }));
+  const selectChain = mock(() => ({ from: fromChain }));
+  (mockDb as { select: unknown }).select = selectChain;
+
+  const configService =
+    platformDefault === undefined
+      ? undefined
+      : ({
+          get: mock(async () => platformDefault),
+          set: mock(async () => {}),
+        } as never);
+
+  return new HealthCheckService(
+    mockDb as never,
+    {} as never,
+    {} as never,
+    configService,
+  );
+}
+
+describe("HealthCheckService.getAssignmentNotificationPolicy", () => {
+  it("falls back to compile-time defaults when no association and no platform defaults", async () => {
+    const service = buildServiceWithRows([]);
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy).toEqual(DEFAULT_NOTIFICATION_POLICY);
+  });
+
+  it("falls back to platform defaults when association exists but notificationPolicy is null", async () => {
+    const customPlatformDefault: NotificationPolicy = {
+      ...DEFAULT_NOTIFICATION_POLICY,
+      autoCloseAfterMinutes: 120,
+      sustainedUnhealthyTrigger: { enabled: true, durationMinutes: 15 },
+    };
+    const service = buildServiceWithRows(
+      [{ notificationPolicy: null }],
+      customPlatformDefault,
+    );
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy.autoCloseAfterMinutes).toBe(120);
+    expect(policy.sustainedUnhealthyTrigger.durationMinutes).toBe(15);
+  });
+
+  it("falls back to platform defaults when no association exists", async () => {
+    const customPlatformDefault: NotificationPolicy = {
+      ...DEFAULT_NOTIFICATION_POLICY,
+      flappingTrigger: { enabled: true, transitions: 10, windowMinutes: 30 },
+    };
+    const service = buildServiceWithRows([], customPlatformDefault);
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy.flappingTrigger).toEqual({
+      enabled: true,
+      transitions: 10,
+      windowMinutes: 30,
+    });
+  });
+
+  it("prefers per-assignment override over platform defaults", async () => {
+    const platformDefault: NotificationPolicy = {
+      ...DEFAULT_NOTIFICATION_POLICY,
+      autoOpenIncidentOnUnhealthy: false,
+    };
+    const assignmentOverride = {
+      suppressDeEscalations: true,
+      autoOpenIncidentOnUnhealthy: true, // overrides platform default
+      useNotificationSuppression: true,
+      skipDuringMaintenance: true,
+      sustainedUnhealthyTrigger: { enabled: true, durationMinutes: 30 },
+      flappingTrigger: { enabled: true, transitions: 3, windowMinutes: 60 },
+      autoCloseAfterMinutes: 30,
+    };
+    const service = buildServiceWithRows(
+      [{ notificationPolicy: assignmentOverride }],
+      platformDefault,
+    );
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy.autoOpenIncidentOnUnhealthy).toBe(true);
+    expect(policy.suppressDeEscalations).toBe(true);
+  });
+
+  it("fills in defaults for partial stored policies", async () => {
+    // Older rows may have only `suppressDeEscalations` set from the
+    // first migration. All other fields must default in.
+    const service = buildServiceWithRows([
+      { notificationPolicy: { suppressDeEscalations: true } },
+    ]);
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy.suppressDeEscalations).toBe(true);
+    expect(policy.autoOpenIncidentOnUnhealthy).toBe(true);
+    expect(policy.useNotificationSuppression).toBe(true);
+    expect(policy.skipDuringMaintenance).toBe(true);
+    expect(policy.sustainedUnhealthyTrigger).toEqual({
+      enabled: true,
+      durationMinutes: 30,
+    });
+    expect(policy.flappingTrigger).toEqual({
+      enabled: true,
+      transitions: 3,
+      windowMinutes: 60,
+    });
+    expect(policy.autoCloseAfterMinutes).toBe(30);
+  });
+
+  it("returns explicit values exactly when fully specified", async () => {
+    const service = buildServiceWithRows([
+      {
+        notificationPolicy: {
+          suppressDeEscalations: false,
+          autoOpenIncidentOnUnhealthy: false,
+          useNotificationSuppression: false,
+          skipDuringMaintenance: false,
+          sustainedUnhealthyTrigger: { enabled: false, durationMinutes: 15 },
+          flappingTrigger: {
+            enabled: true,
+            transitions: 5,
+            windowMinutes: 30,
+          },
+          autoCloseAfterMinutes: null,
+        },
+      },
+    ]);
+    const policy = await service.getAssignmentNotificationPolicy({
+      systemId: "sys-1",
+      configurationId: "cfg-1",
+    });
+    expect(policy.autoOpenIncidentOnUnhealthy).toBe(false);
+    expect(policy.skipDuringMaintenance).toBe(false);
+    expect(policy.sustainedUnhealthyTrigger).toEqual({
+      enabled: false,
+      durationMinutes: 15,
+    });
+    expect(policy.flappingTrigger).toEqual({
+      enabled: true,
+      transitions: 5,
+      windowMinutes: 30,
+    });
+    expect(policy.autoCloseAfterMinutes).toBeNull();
+  });
+});