@checkstack/healthcheck-backend 0.12.0 → 0.13.0

package/src/index.ts

@@ -22,6 +22,7 @@ import { z } from "zod";
 import { createHealthCheckRouter } from "./router";
 import { HealthCheckService } from "./service";
 import { catalogHooks } from "@checkstack/catalog-backend";
+import { satelliteHooks } from "@checkstack/satellite-backend";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
 import { IncidentApi } from "@checkstack/incident-common";
@@ -142,11 +143,12 @@ export default createBackendPlugin({
           queueManager,
         });
 
-        const healthCheckRouter = createHealthCheckRouter(
-          database as SafeDatabase<typeof schema>,
-          healthCheckRegistry,
+        const healthCheckRouter = createHealthCheckRouter({
+          database: database as SafeDatabase<typeof schema>,
+          registry: healthCheckRegistry,
           collectorRegistry,
-        );
+          getEmitHook: () => storedEmitHook,
+        });
         rpc.registerRouter(healthCheckRouter, healthCheckContract);
 
         // Register command palette commands
@@ -212,6 +214,18 @@ export default createBackendPlugin({
           { mode: "work-queue", workerGroup: "system-cleanup" },
         );
 
+        // Subscribe to satellite deletion to scrub satellite IDs from associations
+        onHook(
+          satelliteHooks.satelliteRemoved,
+          async (payload) => {
+            logger.debug(
+              `Scrubbing satellite ${payload.satelliteId} from health check associations`,
+            );
+            await service.scrubSatelliteFromAssociations(payload.satelliteId);
+          },
+          { mode: "work-queue", workerGroup: "satellite-cleanup" },
+        );
+
         logger.debug("✅ Health Check Backend afterPluginsReady complete.");
       },
     });

package/src/queue-executor.ts

@@ -27,7 +27,7 @@ import {
 import { CatalogApi, catalogRoutes } from "@checkstack/catalog-common";
 import { MaintenanceApi } from "@checkstack/maintenance-common";
 import { IncidentApi } from "@checkstack/incident-common";
-import { resolveRoute, type InferClient } from "@checkstack/common";
+import { resolveRoute, type InferClient, extractErrorMessage} from "@checkstack/common";
 import { HealthCheckService } from "./service";
 import { healthCheckHooks } from "./hooks";
 import { incrementHourlyAggregate } from "./realtime-aggregation";
@@ -259,6 +259,8 @@ async function executeHealthCheckJob(props: {
         interval: healthCheckConfigurations.intervalSeconds,
         enabled: systemHealthChecks.enabled,
         paused: healthCheckConfigurations.paused,
+        includeLocal: systemHealthChecks.includeLocal,
+        satelliteIds: systemHealthChecks.satelliteIds,
       })
       .from(systemHealthChecks)
       .innerJoin(
@@ -289,6 +291,19 @@ async function executeHealthCheckJob(props: {
       return;
     }
 
+    // If includeLocal is false and satellites are assigned, skip local execution
+    // (satellites handle execution, local core doesn't run this check)
+    if (
+      !configRow.includeLocal &&
+      configRow.satelliteIds &&
+      configRow.satelliteIds.length > 0
+    ) {
+      logger.debug(
+        `Health check ${configId} for system ${systemId} is satellite-only, skipping local execution`,
+      );
+      return;
+    }
+
     // Fetch system name for signal payload
     let systemName = systemId;
     try {
@@ -400,7 +415,7 @@ async function executeHealthCheckJob(props: {
               };
             } catch (error) {
               const errorStr =
-                error instanceof Error ? error.message : String(error);
+                extractErrorMessage(error);
               logger.debug(`Collector ${storageKey} failed: ${errorStr}`);
               return {
                 storageKey,
@@ -465,7 +480,7 @@ async function executeHealthCheckJob(props: {
     } catch (error) {
       const latencyMs = Math.round(performance.now() - start);
       const caughtError =
-        error instanceof Error ? error.message : String(error);
+        extractErrorMessage(error);
 
       // Use a specific error message if available, otherwise use the caught error
       const finalError = errorMessage || caughtError;
@@ -486,6 +501,8 @@ async function executeHealthCheckJob(props: {
         status: result.status,
         latencyMs: result.latencyMs,
         result: { ...result } as Record<string, unknown>,
+        sourceId: undefined,
+        sourceLabel: "Local",
       });
 
       await incrementHourlyAggregate({
@@ -497,6 +514,7 @@ async function executeHealthCheckJob(props: {
         runTimestamp: new Date(),
         result: { ...result } as Record<string, unknown>,
         collectorRegistry,
+        sourceLabel: "Local",
       });
 
       logger.debug(
@@ -560,6 +578,8 @@ async function executeHealthCheckJob(props: {
       status: result.status,
       latencyMs: result.latencyMs,
       result: { ...result } as Record<string, unknown>,
+      sourceId: undefined,
+      sourceLabel: "Local",
     });
 
     // Trigger incremental hourly aggregation
@@ -572,6 +592,7 @@ async function executeHealthCheckJob(props: {
       runTimestamp: new Date(),
       result: { ...result } as Record<string, unknown>,
       collectorRegistry,
+      sourceLabel: "Local",
     });
 
     logger.debug(
@@ -660,6 +681,8 @@ async function executeHealthCheckJob(props: {
       systemId,
       status: "unhealthy",
       result: { error: String(error) } as Record<string, unknown>,
+      sourceId: undefined,
+      sourceLabel: "Local",
     });
 
     // Trigger incremental hourly aggregation
@@ -672,6 +695,7 @@ async function executeHealthCheckJob(props: {
       runTimestamp: new Date(),
       // No collector data for error cases
       collectorRegistry,
+      sourceLabel: "Local",
     });
 
     // Try to fetch names for the enriched signal (best-effort)

package/src/realtime-aggregation.ts

@@ -67,6 +67,10 @@ interface IncrementHourlyAggregateParams {
   result?: Record<string, unknown>;
   /** Collector registry for aggregating collector data via mergeResult */
   collectorRegistry?: CollectorRegistry;
+  /** Source identifier: undefined = local core, string = satellite ID */
+  sourceId?: string;
+  /** Human-readable source label for display */
+  sourceLabel?: string;
 }
 
 /**
@@ -88,6 +92,8 @@ export async function incrementHourlyAggregate(
     runTimestamp,
     result,
     collectorRegistry,
+    sourceId,
+    sourceLabel,
   } = params;
 
   const bucketStart = getHourBucketStart(runTimestamp);
@@ -107,6 +113,9 @@ export async function incrementHourlyAggregate(
         eq(healthCheckAggregates.configurationId, configurationId),
         eq(healthCheckAggregates.bucketStart, bucketStart),
         eq(healthCheckAggregates.bucketSize, "hourly"),
+        sourceId
+          ? eq(healthCheckAggregates.sourceId, sourceId)
+          : sql`${healthCheckAggregates.sourceId} IS NULL`,
       ),
     )
     .limit(1);
@@ -181,6 +190,8 @@ export async function incrementHourlyAggregate(
       p95LatencyMs: latencyUpdate?.p95,
       tdigestState: latencyUpdate?.tdigestState,
       aggregatedResult,
+      sourceId: sourceId ?? undefined,
+      sourceLabel: sourceLabel ?? undefined,
     })
     .onConflictDoUpdate({
       target: [
@@ -188,6 +199,7 @@ export async function incrementHourlyAggregate(
         healthCheckAggregates.systemId,
         healthCheckAggregates.bucketStart,
         healthCheckAggregates.bucketSize,
+        healthCheckAggregates.sourceId,
       ],
       set: {
         runCount: sql`${healthCheckAggregates.runCount} + 1`,

package/src/router.test.ts

@@ -50,11 +50,12 @@ describe("HealthCheck Router", () => {
     getCollectorsForPlugin: mock(() => []),
   };
 
-  const router = createHealthCheckRouter(
-    mockDb as never,
-    mockRegistry,
-    mockCollectorRegistry as never,
-  );
+  const router = createHealthCheckRouter({
+    database: mockDb as never,
+    registry: mockRegistry,
+    collectorRegistry: mockCollectorRegistry as never,
+    getEmitHook: () => undefined,
+  });
 
   it("getStrategies returns strategies from registry", async () => {
     const context = createMockRpcContext({

package/src/router.ts

@@ -10,6 +10,7 @@ import {
 import { healthCheckContract } from "@checkstack/healthcheck-common";
 import type { StrategyCategory } from "@checkstack/healthcheck-common";
 import { HealthCheckService } from "./service";
+import { healthCheckHooks } from "./hooks";
 import * as schema from "./schema";
 import { toJsonSchemaWithChartMeta } from "./schema-utils";
 
@@ -19,11 +20,13 @@ import { toJsonSchemaWithChartMeta } from "./schema-utils";
  * Auth and access rules are automatically enforced via autoAuthMiddleware
  * based on the contract's meta.userType and meta.access.
  */
-export const createHealthCheckRouter = (
-  database: SafeDatabase<typeof schema>,
-  registry: HealthCheckRegistry,
-  collectorRegistry: CollectorRegistry,
-) => {
+export const createHealthCheckRouter = (opts: {
+  database: SafeDatabase<typeof schema>;
+  registry: HealthCheckRegistry;
+  collectorRegistry: CollectorRegistry;
+  getEmitHook: () => ((hook: { id: string }, payload: Record<string, unknown>) => Promise<void>) | undefined;
+}) => {
+  const { database, registry, collectorRegistry, getEmitHook } = opts;
   // Create service instance once - shared across all handlers
   const service = new HealthCheckService(database, registry, collectorRegistry);
 
@@ -137,6 +140,8 @@ export const createHealthCheckRouter = (
         configurationId: input.body.configurationId,
         enabled: input.body.enabled,
         stateThresholds: input.body.stateThresholds,
+        satelliteIds: input.body.satelliteIds,
+        includeLocal: input.body.includeLocal,
       });
 
       // If enabling the health check, schedule it immediately
@@ -156,10 +161,28 @@ export const createHealthCheckRouter = (
           });
         }
       }
+
+      // Notify subscribers (e.g., satellite-backend) that assignments changed
+      const emitHook = getEmitHook();
+      if (emitHook) {
+        await emitHook(healthCheckHooks.assignmentChanged, {
+          systemId: input.systemId,
+          configurationId: input.body.configurationId,
+        });
+      }
     }),
 
     disassociateSystem: os.disassociateSystem.handler(async ({ input }) => {
       await service.disassociateSystem(input.systemId, input.configId);
+
+      // Notify subscribers that assignments changed
+      const emitHook = getEmitHook();
+      if (emitHook) {
+        await emitHook(healthCheckHooks.assignmentChanged, {
+          systemId: input.systemId,
+          configurationId: input.configId,
+        });
+      }
     }),
 
     getRetentionConfig: os.getRetentionConfig.handler(async ({ input }) => {
@@ -231,9 +254,21 @@ export const createHealthCheckRouter = (
       },
     ),
 
-    getAvailabilityStats: os.getAvailabilityStats.handler(async ({ input }) => {
-      return service.getAvailabilityStats(input);
-    }),
+    // ========================================================================
+    // SERVICE INTERFACE (S2S — satellite-backend)
+    // ========================================================================
+
+    getAssignmentsForSatellite: os.getAssignmentsForSatellite.handler(
+      async ({ input }) => {
+        return service.getAssignmentsForSatellite(input.satelliteId);
+      },
+    ),
+
+    ingestSatelliteResult: os.ingestSatelliteResult.handler(
+      async ({ input }) => {
+        await service.ingestSatelliteResult(input);
+      },
+    ),
   });
 };
 

package/src/schema.ts

@@ -90,6 +90,16 @@ export const systemHealthChecks = pgTable(
      * Null means use default retention settings.
      */
     retentionConfig: jsonb("retention_config").$type<RetentionConfig>(),
+    /**
+     * IDs of satellites assigned to execute this health check.
+     * When set, the check runs on these satellite nodes in addition to (or instead of) the core.
+     */
+    satelliteIds: jsonb("satellite_ids").$type<string[]>(),
+    /**
+     * Whether to also run this check locally on the core instance.
+     * Defaults to true. Only relevant when satelliteIds is set.
+     */
+    includeLocal: boolean("include_local").default(true).notNull(),
     createdAt: timestamp("created_at").defaultNow().notNull(),
     updatedAt: timestamp("updated_at").defaultNow().notNull(),
   },
@@ -108,6 +118,16 @@ export const healthCheckRuns = pgTable("health_check_runs", {
   /** Execution duration in milliseconds */
   latencyMs: integer("latency_ms"),
   result: jsonb("result").$type<Record<string, unknown>>(),
+  /**
+   * Source identifier for result attribution.
+   * null = local core execution, UUID = satellite ID.
+   */
+  sourceId: text("source_id"),
+  /**
+   * Human-readable source label for UI display.
+   * e.g. "Local" or "EU West (eu-west-1)".
+   */
+  sourceLabel: text("source_label"),
   timestamp: timestamp("timestamp").defaultNow().notNull(),
 });
 
@@ -151,14 +171,24 @@ export const healthCheckAggregates = pgTable(
       jsonb("aggregated_result").$type<Record<string, unknown>>(),
     /** Serialized t-digest state for incremental p95 calculation */
     tdigestState: jsonb("tdigest_state").$type<number[]>(),
+    /**
+     * Source identifier for per-region aggregation.
+     * null = local core execution, UUID = satellite ID.
+     */
+    sourceId: text("source_id"),
+    /**
+     * Human-readable source label for UI display.
+     */
+    sourceLabel: text("source_label"),
   },
   (t) => ({
-    // Unique constraint for upsert operations
+    // Unique constraint includes sourceId for per-region aggregation
     bucketUnique: uniqueIndex("health_check_aggregates_bucket_unique").on(
       t.configurationId,
       t.systemId,
       t.bucketStart,
       t.bucketSize,
+      t.sourceId,
     ),
   }),
 );