@checkstack/satellite-backend 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @checkstack/satellite-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 41c77f4: feat(satellite): Phase 9 — connection lifecycle triggers
+
+  - New hooks `satelliteHooks.connected`, `satelliteHooks.disconnected`,
+    and `satelliteHooks.heartbeatLost`. `connected` and `disconnected`
+    fire from the WS handler at auth completion and `onClose`
+    respectively; `heartbeatLost` fires from the heartbeat monitor on
+    the `online → offline` edge only (the opposite edge is observable
+    via `connected`).
+  - Triggers `satellite.connected`, `satellite.disconnected`,
+    `satellite.heartbeat_lost` registered against the Automation
+    Platform. All carry `contextKey: (p) => p.satelliteId` so a
+    long-running automation can resume on the same satellite.
+  - No mutation actions in this chunk — connection lifecycle is
+    observed only, not commanded.
+
+  Plumbing: `SatelliteWsHandler` and `HeartbeatMonitor` both take an
+  optional hook sink in their constructor. The sink is provided from
+  `afterPluginsReady` where `emitHook` is available; until then, the
+  classes behave exactly as before (no hooks fired, no behavioural
+  change).
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/healthcheck-backend@1.3.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/healthcheck-common@1.3.0
+  - @checkstack/satellite-common@0.6.0
+  - @checkstack/gitops-backend@0.3.7
+  - @checkstack/gitops-common@0.4.2
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/queue-api@0.3.6
+
 ## 0.3.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite-backend",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -11,18 +11,20 @@
     "typecheck": "tsgo -b",
     "generate": "drizzle-kit generate",
     "lint": "bun run lint:code",
-    "lint:code": "eslint . --max-warnings 0"
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.17.0",
-    "@checkstack/satellite-common": "0.5.2",
-    "@checkstack/healthcheck-common": "1.1.2",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/automation-backend": "0.1.0",
+    "@checkstack/satellite-common": "0.5.3",
+    "@checkstack/healthcheck-common": "1.2.0",
     "@checkstack/signal-common": "0.2.4",
-    "@checkstack/healthcheck-backend": "1.1.4",
-    "@checkstack/gitops-backend": "0.3.5",
+    "@checkstack/healthcheck-backend": "1.2.0",
+    "@checkstack/gitops-backend": "0.3.6",
     "@checkstack/gitops-common": "0.4.1",
     "@checkstack/common": "0.11.0",
-    "@checkstack/queue-api": "0.3.4",
+    "@checkstack/queue-api": "0.3.5",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
@@ -30,7 +32,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
     "@checkstack/scripts": "0.3.3",
-    "@checkstack/test-utils-backend": "0.1.29",
+    "@checkstack/test-utils-backend": "0.1.30",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "drizzle-kit": "^0.31.10",

package/src/automations.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Behaviour tests for the satellite automation triggers.
+ * No mutation actions in this chunk — connection lifecycle is observed
+ * only, not commanded.
+ */
+import { describe, expect, it } from "bun:test";
+
+import {
+  satelliteConnectedTrigger,
+  satelliteDisconnectedTrigger,
+  satelliteHeartbeatLostTrigger,
+  satelliteTriggers,
+} from "./automations";
+import { satelliteHooks } from "./hooks";
+
+describe("satellite triggers", () => {
+  it("exposes three triggers in a stable order", () => {
+    expect(satelliteTriggers).toHaveLength(3);
+    expect(satelliteTriggers[0]).toBe(
+      satelliteConnectedTrigger as (typeof satelliteTriggers)[number],
+    );
+    expect(satelliteTriggers[1]).toBe(
+      satelliteDisconnectedTrigger as (typeof satelliteTriggers)[number],
+    );
+    expect(satelliteTriggers[2]).toBe(
+      satelliteHeartbeatLostTrigger as (typeof satelliteTriggers)[number],
+    );
+  });
+
+  it("binds each trigger to the matching hook", () => {
+    expect(satelliteConnectedTrigger.hook).toBe(satelliteHooks.connected);
+    expect(satelliteDisconnectedTrigger.hook).toBe(satelliteHooks.disconnected);
+    expect(satelliteHeartbeatLostTrigger.hook).toBe(satelliteHooks.heartbeatLost);
+  });
+
+  it("extracts satelliteId as the contextKey on all three", () => {
+    const payload = {
+      satelliteId: "sat-1",
+      name: "EU-Central",
+      region: "eu-central-1",
+      timestamp: "2026-05-29T11:00:00Z",
+    };
+    expect(satelliteConnectedTrigger.contextKey?.(payload)).toBe("sat-1");
+    expect(satelliteDisconnectedTrigger.contextKey?.(payload)).toBe("sat-1");
+    expect(satelliteHeartbeatLostTrigger.contextKey?.(payload)).toBe("sat-1");
+  });
+
+  it("rejects payloads missing required fields", () => {
+    const bad = satelliteConnectedTrigger.payloadSchema.safeParse({
+      satelliteId: "sat-1",
+    });
+    expect(bad.success).toBe(false);
+  });
+});

package/src/automations.ts

@@ -0,0 +1,66 @@
+/**
+ * Satellite triggers registered with the Automation Platform.
+ *
+ * The plan calls for `satellite.connected`, `satellite.disconnected`,
+ * and `satellite.heartbeat_lost` — all three were added as new hooks
+ * in `./hooks.ts` and emitted from the WS handler (connect/disconnect)
+ * and heartbeat monitor (online → offline). No mutation actions for
+ * satellite in this phase.
+ */
+import { z } from "zod";
+import type { TriggerDefinition } from "@checkstack/automation-backend";
+
+import { satelliteHooks } from "./hooks";
+
+const satelliteEventPayloadSchema = z.object({
+  satelliteId: z.string(),
+  name: z.string(),
+  region: z.string(),
+  timestamp: z.string(),
+});
+
+export const satelliteConnectedTrigger: TriggerDefinition<
+  z.infer<typeof satelliteEventPayloadSchema>
+> = {
+  id: "connected",
+  displayName: "Satellite Connected",
+  description: "Fires when a satellite WebSocket completes authentication",
+  category: "Satellites",
+  icon: "Satellite",
+  payloadSchema: satelliteEventPayloadSchema,
+  hook: satelliteHooks.connected,
+  contextKey: (p) => p.satelliteId,
+};
+
+export const satelliteDisconnectedTrigger: TriggerDefinition<
+  z.infer<typeof satelliteEventPayloadSchema>
+> = {
+  id: "disconnected",
+  displayName: "Satellite Disconnected",
+  description: "Fires when a satellite's WebSocket closes",
+  category: "Satellites",
+  icon: "Satellite",
+  payloadSchema: satelliteEventPayloadSchema,
+  hook: satelliteHooks.disconnected,
+  contextKey: (p) => p.satelliteId,
+};
+
+export const satelliteHeartbeatLostTrigger: TriggerDefinition<
+  z.infer<typeof satelliteEventPayloadSchema>
+> = {
+  id: "heartbeat_lost",
+  displayName: "Satellite Heartbeat Lost",
+  description:
+    "Fires when a satellite transitions online → offline (no heartbeat within threshold)",
+  category: "Satellites",
+  icon: "Satellite",
+  payloadSchema: satelliteEventPayloadSchema,
+  hook: satelliteHooks.heartbeatLost,
+  contextKey: (p) => p.satelliteId,
+};
+
+export const satelliteTriggers: TriggerDefinition<unknown>[] = [
+  satelliteConnectedTrigger as TriggerDefinition<unknown>,
+  satelliteDisconnectedTrigger as TriggerDefinition<unknown>,
+  satelliteHeartbeatLostTrigger as TriggerDefinition<unknown>,
+];

package/src/heartbeat-monitor.ts

@@ -1,4 +1,4 @@
-import type { Logger } from "@checkstack/backend-api";
+import type { Hook, Logger } from "@checkstack/backend-api";
 import type { SignalService } from "@checkstack/signal-common";
 import type { SatelliteService } from "./service";
 import {
@@ -6,6 +6,22 @@ import {
   OFFLINE_THRESHOLD_MS,
 } from "@checkstack/satellite-common";
 
+/**
+ * Optional plug-point for firing the automation
+ * `satellite.heartbeat_lost` trigger when the monitor observes a
+ * satellite transitioning `online` → `offline`. Bound from
+ * `afterPluginsReady`; when not provided, no hook fires.
+ */
+export interface SatelliteHeartbeatHookSink {
+  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+  heartbeatLostHook: Hook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>;
+}
+
 /**
  * Monitors satellite heartbeats and broadcasts status change signals.
  * Tracks previous state in-memory to detect transitions (online → offline, offline → online).
@@ -21,6 +37,7 @@ export class HeartbeatMonitor {
     private service: SatelliteService,
     private signalService: SignalService,
     private logger: Logger,
+    private hookSink?: SatelliteHeartbeatHookSink,
   ) {}
 
   /**
@@ -46,6 +63,29 @@ export class HeartbeatMonitor {
           name: satellite.name,
           region: satellite.region,
         });
+
+        // Fire the automation `heartbeat_lost` hook only on the
+        // online → offline edge. The opposite transition is observable
+        // via the `satellite.connected` hook fired by the WS handler.
+        if (
+          previousStatus === "online" &&
+          currentStatus === "offline" &&
+          this.hookSink
+        ) {
+          try {
+            await this.hookSink.emitHook(this.hookSink.heartbeatLostHook, {
+              satelliteId: satellite.id,
+              name: satellite.name,
+              region: satellite.region,
+              timestamp: new Date().toISOString(),
+            });
+          } catch (error) {
+            this.logger.error(
+              `Failed to emit satellite.heartbeat_lost hook for ${satellite.name}:`,
+              error,
+            );
+          }
+        }
       }
 
       this.previousStatuses.set(satellite.id, currentStatus);

package/src/hooks.ts

@@ -14,4 +14,41 @@ export const satelliteHooks = {
   satelliteRemoved: createHook<{
     satelliteId: string;
   }>("satellite.removed"),
+
+  /**
+   * Emitted when a satellite WebSocket completes authentication and
+   * registers itself in the in-memory connection map.
+   */
+  connected: createHook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>("satellite.connected"),
+
+  /**
+   * Emitted when a previously-connected satellite's WebSocket closes
+   * (graceful or otherwise). Distinct from `heartbeatLost`: this fires
+   * the moment the socket drops, regardless of whether the satellite
+   * comes back within the heartbeat window.
+   */
+  disconnected: createHook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>("satellite.disconnected"),
+
+  /**
+   * Emitted by the heartbeat monitor when a satellite's status
+   * transitions from `online` to `offline` — i.e. no heartbeat for
+   * longer than `OFFLINE_THRESHOLD_MS`. Used by automations that
+   * page on stale satellites.
+   */
+  heartbeatLost: createHook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>("satellite.heartbeat_lost"),
 } as const;

package/src/index.ts

@@ -16,6 +16,9 @@ import { SatelliteWsHandler } from "./satellite-ws-handler";
 import { ConfigRelay } from "./config-relay";
 import { entityKindExtensionPoint } from "@checkstack/gitops-backend";
 import { registerSatelliteGitOpsKinds } from "./satellite-gitops-kinds";
+import { automationTriggerExtensionPoint } from "@checkstack/automation-backend";
+import { satelliteTriggers } from "./automations";
+import { satelliteHooks } from "./hooks";
 
 // Queue and job constants
 const HEARTBEAT_QUEUE = "satellite-heartbeat";
@@ -27,6 +30,14 @@ export default createBackendPlugin({
   register(env) {
     env.registerAccessRules(satelliteAccessRules);
 
+    // ─── Automation Platform: triggers ───────────────────────────────
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of satelliteTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+
     // ─── GitOps Entity Kind Registration ─────────────────────────────
     let gitopsService: SatelliteService | undefined;
     const kindRegistry = env.getExtensionPoint(entityKindExtensionPoint);
@@ -73,6 +84,7 @@ export default createBackendPlugin({
         wsRegistry,
         rpcClient,
         onHook,
+        emitHook,
       }) => {
         const service = new SatelliteService(
           database as SafeDatabase<typeof schema>,
@@ -112,6 +124,11 @@ export default createBackendPlugin({
             },
           },
           logger,
+          {
+            emitHook,
+            connectedHook: satelliteHooks.connected,
+            disconnectedHook: satelliteHooks.disconnected,
+          },
         );
 
         // Register satellite WebSocket endpoint via the scoped WS registry
@@ -124,6 +141,10 @@ export default createBackendPlugin({
           service,
           signalService,
           logger,
+          {
+            emitHook,
+            heartbeatLostHook: satelliteHooks.heartbeatLost,
+          },
         );
 
         const queue = queueManager.getQueue<Record<string, never>>(

package/src/satellite-ws-handler.ts

@@ -1,4 +1,4 @@
-import type { Logger } from "@checkstack/backend-api";
+import type { Hook, Logger } from "@checkstack/backend-api";
 import type {
   WebSocketRouteHandler,
   WsConnection,
@@ -13,6 +13,27 @@ import {
   type SatelliteWithStatus,
 } from "@checkstack/satellite-common";
 
+/**
+ * Optional plug-point for firing automation triggers when a satellite
+ * connects or disconnects. Bound from `afterPluginsReady` where
+ * `emitHook` is available — when not provided, no hook fires.
+ */
+export interface SatelliteConnectionHookSink {
+  emitHook: <T>(hook: Hook<T>, payload: T) => Promise<void>;
+  connectedHook: Hook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>;
+  disconnectedHook: Hook<{
+    satelliteId: string;
+    name: string;
+    region: string;
+    timestamp: string;
+  }>;
+}
+
 /**
  * Callback for handling health check results received from satellites.
  */
@@ -45,6 +66,13 @@ export class SatelliteWsHandler implements WebSocketRouteHandler {
     private configRelay: ConfigRelay,
     private resultHandler: SatelliteResultHandler,
     private logger: Logger,
+    /**
+     * Optional. When set, the handler fires `connected` / `disconnected`
+     * hooks at the same lifecycle points it logs. Wired by
+     * `afterPluginsReady` so the action graph stays decoupled from
+     * `emitHook` availability.
+     */
+    private connectionHookSink?: SatelliteConnectionHookSink,
   ) {}
 
   /**
@@ -94,6 +122,27 @@ export class SatelliteWsHandler implements WebSocketRouteHandler {
         // Track connection
         this.connections.set(satellite.id, { satellite, ws });
 
+        // Fire the automation `connected` hook (best-effort — never
+        // block the auth handshake on a hook subscriber failure).
+        if (this.connectionHookSink) {
+          try {
+            await this.connectionHookSink.emitHook(
+              this.connectionHookSink.connectedHook,
+              {
+                satelliteId: satellite.id,
+                name: satellite.name,
+                region: satellite.region,
+                timestamp: new Date().toISOString(),
+              },
+            );
+          } catch (error) {
+            this.logger.error(
+              `Failed to emit satellite.connected hook for ${satellite.name}:`,
+              error,
+            );
+          }
+        }
+
         // Update heartbeat on connect
         await this.service.updateHeartbeat(satellite.id, {});
 
@@ -147,10 +196,28 @@ export class SatelliteWsHandler implements WebSocketRouteHandler {
 
     const onClose = () => {
       if (authenticatedSatellite) {
-        this.connections.delete(authenticatedSatellite.id);
+        const closedSatellite = authenticatedSatellite;
+        this.connections.delete(closedSatellite.id);
         this.logger.info(
-          `Satellite disconnected: ${authenticatedSatellite.name} (${authenticatedSatellite.region})`,
+          `Satellite disconnected: ${closedSatellite.name} (${closedSatellite.region})`,
         );
+        if (this.connectionHookSink) {
+          // Fire-and-forget — `onClose` is sync, so don't await; we
+          // don't have a place to surface a rejection anyway.
+          void this.connectionHookSink
+            .emitHook(this.connectionHookSink.disconnectedHook, {
+              satelliteId: closedSatellite.id,
+              name: closedSatellite.name,
+              region: closedSatellite.region,
+              timestamp: new Date().toISOString(),
+            })
+            .catch((error: unknown) => {
+              this.logger.error(
+                `Failed to emit satellite.disconnected hook for ${closedSatellite.name}:`,
+                error,
+              );
+            });
+        }
       }
     };
 

package/tsconfig.json

@@ -4,6 +4,9 @@
     "src"
   ],
   "references": [
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },