@checkstack/satellite-backend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @checkstack/satellite-backend
+
+## 0.2.0
+
+### Minor Changes
+
+- 26d8bae: Distributed satellite health checks and Assignment IDE page
+
+  **Satellite System**
+
+  - New `satellite-backend`, `satellite-common`, `satellite-frontend`, and `satellite` agent packages for distributed health check execution
+  - WebSocket-based satellite connectivity with authentication, heartbeats, and live configuration push
+  - Satellite management UI with create dialog, status badges, and list page
+
+  **Live Configuration Updates**
+
+  - Added `assignmentChanged` hook to `healthcheck-backend` for cross-plugin communication
+  - `satellite-backend` subscribes to assignment changes and pushes config updates to connected satellites in real-time
+
+  **Assignment IDE Page**
+
+  - Replaced the 1028-line modal-based `SystemHealthCheckAssignment` component with a full-page IDE layout
+  - New modular components: `AssignmentTree`, `GeneralPanel`, `ThresholdsPanel`, `RetentionPanel`, `ExecutionPanel`
+  - Added unassign capability and sorted assignment lists for stable ordering
+
+  **Shared IDE Primitives**
+
+  - Extracted `IDETreeNode`, `IDETreeSection`, `IDEStatusBar`, `IDELayout` to `@checkstack/ui` for cross-plugin reuse
+  - Migrated existing health check IDE editor to use shared primitives
+
+  **Infrastructure**
+
+  - Added `Dockerfile.satellite` for containerized satellite deployment
+  - WebSocket route registry in `@checkstack/backend` and `@checkstack/backend-api`
+
+### Patch Changes
+
+- Updated dependencies [26d8bae]
+- Updated dependencies [26d8bae]
+  - @checkstack/healthcheck-common@0.11.0
+  - @checkstack/healthcheck-backend@0.13.0
+  - @checkstack/satellite-common@0.2.0
+  - @checkstack/backend-api@0.12.0
+  - @checkstack/queue-api@0.2.13

package/drizzle/0000_melted_gargoyle.sql

@@ -0,0 +1,10 @@
+CREATE TABLE "satellites" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"name" text NOT NULL,
+	"region" text NOT NULL,
+	"tags" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"token_hash" text NOT NULL,
+	"last_heartbeat_at" timestamp,
+	"version" text,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,83 @@
+{
+  "id": "8c89df94-7c41-44ec-9197-02edea2f23f2",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.satellites": {
+      "name": "satellites",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "region": {
+          "name": "region",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "tags": {
+          "name": "tags",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "token_hash": {
+          "name": "token_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_heartbeat_at": {
+          "name": "last_heartbeat_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "version": {
+          "name": "version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1776590977685,
+      "tag": "0000_melted_gargoyle",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  schema: "./src/schema.ts",
+  out: "./drizzle",
+  dialect: "postgresql",
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@checkstack/satellite-backend",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "checkstack": {
+    "type": "backend"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "generate": "drizzle-kit generate",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "0.11.1",
+    "@checkstack/satellite-common": "0.1.0",
+    "@checkstack/healthcheck-common": "0.10.1",
+    "@checkstack/signal-common": "0.1.9",
+    "@checkstack/healthcheck-backend": "0.12.1",
+    "@checkstack/common": "0.6.5",
+    "@checkstack/queue-api": "0.2.12",
+    "drizzle-orm": "^0.45.0",
+    "zod": "^4.2.1",
+    "@orpc/server": "^1.13.2"
+  },
+  "devDependencies": {
+    "@checkstack/drizzle-helper": "0.0.4",
+    "@checkstack/scripts": "0.1.2",
+    "@checkstack/test-utils-backend": "0.1.18",
+    "@checkstack/tsconfig": "0.0.5",
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/config-relay.ts

@@ -0,0 +1,31 @@
+import type { SatelliteAssignment } from "@checkstack/satellite-common";
+
+/**
+ * Builds the full configuration payload for a satellite.
+ * Queries systemHealthChecks for associations that reference this satellite's ID,
+ * then joins with healthCheckConfigurations to build the full assignment list.
+ */
+export class ConfigRelay {
+  constructor(
+    /**
+     * The healthcheck database connection.
+     * This is passed in from the healthcheck-backend's schema context.
+     */
+    private getHealthcheckDb: () => Promise<{
+      getAssignmentsForSatellite: (
+        satelliteId: string,
+      ) => Promise<SatelliteAssignment[]>;
+    }>,
+  ) {}
+
+  /**
+   * Get all health check assignments for a specific satellite.
+   * Returns the full configuration payload needed for the satellite to execute checks.
+   */
+  async getAssignmentsForSatellite(
+    satelliteId: string,
+  ): Promise<SatelliteAssignment[]> {
+    const db = await this.getHealthcheckDb();
+    return db.getAssignmentsForSatellite(satelliteId);
+  }
+}

package/src/heartbeat-monitor.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { HeartbeatMonitor } from "./heartbeat-monitor";
+import {
+  createMockLogger,
+  createMockSignalService,
+  type MockSignalService,
+} from "@checkstack/test-utils-backend";
+import { SATELLITE_STATUS_CHANGED } from "@checkstack/satellite-common";
+import type { SatelliteService } from "./service";
+import type { SatelliteWithStatus } from "@checkstack/satellite-common";
+
+const createMockSatelliteService = (
+  satellites: SatelliteWithStatus[],
+): SatelliteService =>
+  ({
+    listSatellites: mock(async () => satellites),
+  }) as unknown as SatelliteService;
+
+describe("HeartbeatMonitor", () => {
+  let signalService: MockSignalService;
+  let logger: ReturnType<typeof createMockLogger>;
+
+  beforeEach(() => {
+    signalService = createMockSignalService();
+    logger = createMockLogger();
+  });
+
+  it("should not broadcast signals on first check (initialization)", async () => {
+    const service = createMockSatelliteService([
+      {
+        id: "sat-1",
+        name: "eu-west",
+        region: "eu-west-1",
+        tags: {},
+        status: "online",
+        createdAt: new Date(),
+      },
+    ]);
+
+    const monitor = new HeartbeatMonitor(service, signalService, logger);
+    await monitor.checkHeartbeats();
+
+    // First check should NOT broadcast — it only initializes state
+    expect(signalService.getRecordedSignals()).toHaveLength(0);
+  });
+
+  it("should broadcast when a satellite goes offline", async () => {
+    const satellites: SatelliteWithStatus[] = [
+      {
+        id: "sat-1",
+        name: "eu-west",
+        region: "eu-west-1",
+        tags: {},
+        status: "online",
+        createdAt: new Date(),
+      },
+    ];
+    const service = createMockSatelliteService(satellites);
+    const monitor = new HeartbeatMonitor(service, signalService, logger);
+
+    // First check: initialize state
+    await monitor.checkHeartbeats();
+
+    // Simulate satellite going offline
+    satellites[0] = { ...satellites[0], status: "offline" };
+    await monitor.checkHeartbeats();
+
+    expect(
+      signalService.wasSignalEmitted(SATELLITE_STATUS_CHANGED.id),
+    ).toBe(true);
+
+    const recorded = signalService.getRecordedSignalsById(
+      SATELLITE_STATUS_CHANGED.id,
+    );
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].payload).toEqual({
+      satelliteId: "sat-1",
+      status: "offline",
+      name: "eu-west",
+      region: "eu-west-1",
+    });
+  });
+
+  it("should broadcast when a satellite comes back online", async () => {
+    const satellites: SatelliteWithStatus[] = [
+      {
+        id: "sat-1",
+        name: "eu-west",
+        region: "eu-west-1",
+        tags: {},
+        status: "offline",
+        createdAt: new Date(),
+      },
+    ];
+    const service = createMockSatelliteService(satellites);
+    const monitor = new HeartbeatMonitor(service, signalService, logger);
+
+    // First check: initialize state
+    await monitor.checkHeartbeats();
+
+    // Simulate satellite coming online
+    satellites[0] = { ...satellites[0], status: "online" };
+    await monitor.checkHeartbeats();
+
+    const recorded = signalService.getRecordedSignalsById(
+      SATELLITE_STATUS_CHANGED.id,
+    );
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].payload).toEqual({
+      satelliteId: "sat-1",
+      status: "online",
+      name: "eu-west",
+      region: "eu-west-1",
+    });
+  });
+
+  it("should not broadcast if status stays the same", async () => {
+    const satellites: SatelliteWithStatus[] = [
+      {
+        id: "sat-1",
+        name: "eu-west",
+        region: "eu-west-1",
+        tags: {},
+        status: "online",
+        createdAt: new Date(),
+      },
+    ];
+    const service = createMockSatelliteService(satellites);
+    const monitor = new HeartbeatMonitor(service, signalService, logger);
+
+    // First check: initialize
+    await monitor.checkHeartbeats();
+    // Second check: same status
+    await monitor.checkHeartbeats();
+
+    expect(signalService.getRecordedSignals()).toHaveLength(0);
+  });
+
+  it("should clean up tracked state for deleted satellites", async () => {
+    const satellites: SatelliteWithStatus[] = [
+      {
+        id: "sat-1",
+        name: "eu-west",
+        region: "eu-west-1",
+        tags: {},
+        status: "online",
+        createdAt: new Date(),
+      },
+    ];
+    const service = createMockSatelliteService(satellites);
+    const monitor = new HeartbeatMonitor(service, signalService, logger);
+
+    // First check
+    await monitor.checkHeartbeats();
+
+    // Satellite removed (empty list returned)
+    satellites.length = 0;
+    await monitor.checkHeartbeats();
+
+    // Adding it back should not trigger a transition
+    // (it's treated as a new satellite on first check)
+    satellites.push({
+      id: "sat-1",
+      name: "eu-west",
+      region: "eu-west-1",
+      tags: {},
+      status: "online",
+      createdAt: new Date(),
+    });
+    await monitor.checkHeartbeats();
+
+    // No transition signal should have been emitted for the re-add
+    expect(signalService.getRecordedSignals()).toHaveLength(0);
+  });
+});

package/src/heartbeat-monitor.ts

@@ -0,0 +1,70 @@
+import type { Logger } from "@checkstack/backend-api";
+import type { SignalService } from "@checkstack/signal-common";
+import type { SatelliteService } from "./service";
+import {
+  SATELLITE_STATUS_CHANGED,
+  OFFLINE_THRESHOLD_MS,
+} from "@checkstack/satellite-common";
+
+/**
+ * Monitors satellite heartbeats and broadcasts status change signals.
+ * Tracks previous state in-memory to detect transitions (online → offline, offline → online).
+ */
+export class HeartbeatMonitor {
+  /**
+   * In-memory tracking of each satellite's last known status.
+   * Used to detect transitions and avoid redundant signal broadcasts.
+   */
+  private previousStatuses = new Map<string, "online" | "offline">();
+
+  constructor(
+    private service: SatelliteService,
+    private signalService: SignalService,
+    private logger: Logger,
+  ) {}
+
+  /**
+   * Check all satellites and broadcast status change signals for any transitions.
+   * Called periodically by a recurring queue job.
+   */
+  async checkHeartbeats(): Promise<void> {
+    const allSatellites = await this.service.listSatellites();
+
+    for (const satellite of allSatellites) {
+      const previousStatus = this.previousStatuses.get(satellite.id);
+      const currentStatus = satellite.status;
+
+      // Detect transition
+      if (previousStatus !== undefined && previousStatus !== currentStatus) {
+        this.logger.info(
+          `Satellite ${satellite.name} (${satellite.region}) status: ${previousStatus} → ${currentStatus}`,
+        );
+
+        await this.signalService.broadcast(SATELLITE_STATUS_CHANGED, {
+          satelliteId: satellite.id,
+          status: currentStatus,
+          name: satellite.name,
+          region: satellite.region,
+        });
+      }
+
+      this.previousStatuses.set(satellite.id, currentStatus);
+    }
+
+    // Clean up tracked satellites that no longer exist
+    const currentIds = new Set(allSatellites.map((s) => s.id));
+    for (const trackedId of this.previousStatuses.keys()) {
+      if (!currentIds.has(trackedId)) {
+        this.previousStatuses.delete(trackedId);
+      }
+    }
+  }
+
+  /**
+   * Get the offline threshold in milliseconds.
+   * Exposed for testing.
+   */
+  static get OFFLINE_THRESHOLD_MS(): number {
+    return OFFLINE_THRESHOLD_MS;
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,17 @@
+import { createHook } from "@checkstack/backend-api";
+
+/**
+ * Satellite hooks for cross-plugin communication.
+ * Other plugins (e.g., healthcheck-backend) can subscribe to clean up
+ * when a satellite is removed.
+ */
+export const satelliteHooks = {
+  /**
+   * Emitted when a satellite is deleted.
+   * Healthcheck-backend subscribes to scrub this satellite's ID
+   * from all systemHealthChecks.satelliteIds arrays.
+   */
+  satelliteRemoved: createHook<{
+    satelliteId: string;
+  }>("satellite.removed"),
+} as const;

package/src/index.ts

@@ -0,0 +1,159 @@
+import * as schema from "./schema";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import {
+  satelliteAccessRules,
+  satelliteContract,
+  pluginMetadata,
+  HEARTBEAT_INTERVAL_MS,
+} from "@checkstack/satellite-common";
+import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import { healthCheckHooks } from "@checkstack/healthcheck-backend";
+import { SatelliteService } from "./service";
+import { createSatelliteRouter } from "./router";
+import { HeartbeatMonitor } from "./heartbeat-monitor";
+import { SatelliteWsHandler } from "./satellite-ws-handler";
+import { ConfigRelay } from "./config-relay";
+
+// Queue and job constants
+const HEARTBEAT_QUEUE = "satellite-heartbeat";
+const HEARTBEAT_JOB_ID = "satellite-heartbeat-check";
+const HEARTBEAT_WORKER_GROUP = "satellite-heartbeat-worker";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerAccessRules(satelliteAccessRules);
+
+    env.registerInit({
+      schema,
+      deps: {
+        logger: coreServices.logger,
+        rpc: coreServices.rpc,
+        rpcClient: coreServices.rpcClient,
+        signalService: coreServices.signalService,
+        queueManager: coreServices.queueManager,
+        wsRegistry: coreServices.wsRegistry,
+      },
+      init: async ({ logger, database, rpc, signalService }) => {
+        logger.debug("🛰️ Initializing Satellite Backend...");
+
+        const service = new SatelliteService(
+          database as SafeDatabase<typeof schema>,
+        );
+
+        const router = createSatelliteRouter({
+          service,
+          signalService,
+          logger,
+        });
+        rpc.registerRouter(router, satelliteContract);
+
+        logger.debug("✅ Satellite Backend initialized.");
+      },
+      afterPluginsReady: async ({
+        database,
+        queueManager,
+        logger,
+        signalService,
+        wsRegistry,
+        rpcClient,
+        onHook,
+      }) => {
+        const service = new SatelliteService(
+          database as SafeDatabase<typeof schema>,
+        );
+
+        // Wire ConfigRelay via RPC loopback to healthcheck-backend
+        const configRelay = new ConfigRelay(async () => {
+          const hcClient = rpcClient.forPlugin(HealthCheckApi);
+          return {
+            getAssignmentsForSatellite: async (satelliteId: string) => {
+              return hcClient.getAssignmentsForSatellite({ satelliteId });
+            },
+          };
+        });
+
+        // Wire result handler — ingests satellite results into healthcheck-backend
+        const wsHandler = new SatelliteWsHandler(
+          service,
+          configRelay,
+          {
+            handleResult: async ({ satelliteId, sourceLabel, result }) => {
+              const hcClient = rpcClient.forPlugin(HealthCheckApi);
+              await hcClient.ingestSatelliteResult({
+                configId: result.configId,
+                systemId: result.systemId,
+                status: result.status,
+                latencyMs: result.latencyMs,
+                result: result.result,
+                executedAt: result.executedAt,
+                sourceId: satelliteId,
+                sourceLabel,
+              });
+              logger.debug(
+                `Ingested result from satellite ${satelliteId} (${sourceLabel}): ` +
+                  `config=${result.configId} status=${result.status}`,
+              );
+            },
+          },
+          logger,
+        );
+
+        // Register satellite WebSocket endpoint via the scoped WS registry
+        // pluginId "satellite" is auto-prefixed → available at /api/ws/satellite
+        wsRegistry.register("/", wsHandler);
+        logger.debug("✅ Satellite WebSocket endpoint registered at /api/ws/satellite");
+
+        // Setup heartbeat monitor
+        const heartbeatMonitor = new HeartbeatMonitor(
+          service,
+          signalService,
+          logger,
+        );
+
+        const queue = queueManager.getQueue<Record<string, never>>(
+          HEARTBEAT_QUEUE,
+        );
+
+        // Subscribe to heartbeat check jobs
+        await queue.consume(
+          async () => {
+            await heartbeatMonitor.checkHeartbeats();
+          },
+          {
+            consumerGroup: HEARTBEAT_WORKER_GROUP,
+            maxRetries: 0,
+          },
+        );
+
+        // Schedule heartbeat check at the same interval as the heartbeat itself
+        const intervalSeconds = Math.round(HEARTBEAT_INTERVAL_MS / 1000);
+        await queue.scheduleRecurring(
+          {},
+          {
+            jobId: HEARTBEAT_JOB_ID,
+            intervalSeconds,
+          },
+        );
+
+        logger.debug(
+          `✅ Satellite heartbeat monitor scheduled (every ${intervalSeconds}s).`,
+        );
+
+        // Subscribe to assignment changes to push config to connected satellites
+        onHook(
+          healthCheckHooks.assignmentChanged,
+          async () => {
+            await wsHandler.pushConfigUpdateToAll();
+          },
+        );
+
+        logger.debug("✅ Satellite Backend afterPluginsReady complete.");
+      },
+    });
+  },
+});
+
+// Re-export hooks for other plugins to use
+export { satelliteHooks } from "./hooks";