@checkstack/satellite-backend 0.3.6 → 0.5.0

package/src/entity.test.ts

@@ -0,0 +1,313 @@
+/**
+ * Unit tests for the satellite-connection reactive-entity mapping (reactive
+ * automation engine §10.6, §9.1). Proves the deriver returns the EXACT
+ * qualified trigger event ids existing automations match — including the
+ * three-way connected / disconnected / heartbeat_lost distinction carried
+ * by the `lastEvent` discriminator.
+ */
+import { describe, expect, it } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import { OFFLINE_THRESHOLD_MS } from "@checkstack/satellite-common";
+import type { EntityChanged } from "@checkstack/automation-common";
+
+import {
+  SATELLITE_CONNECTED_EVENT,
+  SATELLITE_DISCONNECTED_EVENT,
+  SATELLITE_HEARTBEAT_LOST_EVENT,
+  createSatelliteConnectionRead,
+  deriveSatelliteConnectionEvents,
+  satelliteChangeToPayload,
+  satelliteConnectionStateSchema,
+  toSatelliteConnectionState,
+  type SatelliteConnectionState,
+} from "./entity";
+import {
+  satelliteConnectedTrigger,
+  satelliteDisconnectedTrigger,
+  satelliteHeartbeatLostTrigger,
+} from "./automations";
+import type { SatelliteService } from "./service";
+
+function makeChange(over: Partial<EntityChanged>): EntityChanged {
+  return {
+    kind: "satellite-connection",
+    id: "sat-1",
+    prev: null,
+    next: {
+      status: "online",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: "2026-05-31T00:00:00.000Z",
+      lastEvent: "connected",
+    },
+    delta: {},
+    changedFields: [],
+    actor: SYSTEM_ACTOR,
+    occurredAt: "2026-05-31T00:00:00.000Z",
+    ...over,
+  };
+}
+
+describe("satelliteChangeToPayload — payloadSchema parity", () => {
+  it("a connect payload validates against the connected trigger's payloadSchema", () => {
+    const parsed = satelliteConnectedTrigger.payloadSchema.parse(
+      satelliteChangeToPayload(makeChange({})),
+    );
+    expect(parsed.satelliteId).toBe("sat-1");
+    expect(parsed.name).toBe("edge-eu");
+    expect(parsed.region).toBe("eu");
+    expect(parsed.status).toBe("online");
+    expect(parsed.lastSeenAt).toBe("2026-05-31T00:00:00.000Z");
+  });
+
+  it("a disconnect payload validates (lastSeenAt null after clean disconnect)", () => {
+    const change = makeChange({
+      prev: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "connected",
+      },
+      next: {
+        status: "offline",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: null,
+        lastEvent: "disconnected",
+      },
+    });
+    const parsed = satelliteDisconnectedTrigger.payloadSchema.parse(
+      satelliteChangeToPayload(change),
+    );
+    expect(parsed.satelliteId).toBe("sat-1");
+    expect(parsed.status).toBe("offline");
+    expect(parsed.lastSeenAt).toBeNull();
+  });
+
+  it("a heartbeat-lost payload validates against the heartbeat_lost trigger's payloadSchema", () => {
+    const change = makeChange({
+      prev: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "connected",
+      },
+      next: {
+        status: "offline",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "heartbeat_lost",
+      },
+    });
+    const parsed = satelliteHeartbeatLostTrigger.payloadSchema.parse(
+      satelliteChangeToPayload(change),
+    );
+    expect(parsed.satelliteId).toBe("sat-1");
+    expect(parsed.status).toBe("offline");
+  });
+});
+
+describe("deriveSatelliteConnectionEvents", () => {
+  it("maps lastEvent='connected' to satellite.connected", () => {
+    expect(deriveSatelliteConnectionEvents(makeChange({}))).toEqual([
+      SATELLITE_CONNECTED_EVENT,
+    ]);
+  });
+
+  it("maps lastEvent='disconnected' to satellite.disconnected", () => {
+    const change = makeChange({
+      prev: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "connected",
+      },
+      next: {
+        status: "offline",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:01:00.000Z",
+        lastEvent: "disconnected",
+      },
+    });
+    expect(deriveSatelliteConnectionEvents(change)).toEqual([
+      SATELLITE_DISCONNECTED_EVENT,
+    ]);
+  });
+
+  it("maps lastEvent='heartbeat_lost' to satellite.heartbeat_lost (distinct from disconnected)", () => {
+    const change = makeChange({
+      prev: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "connected",
+      },
+      next: {
+        status: "offline",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:05:00.000Z",
+        lastEvent: "heartbeat_lost",
+      },
+    });
+    expect(deriveSatelliteConnectionEvents(change)).toEqual([
+      SATELLITE_HEARTBEAT_LOST_EVENT,
+    ]);
+  });
+
+  it("fires nothing on a tombstone (next === null)", () => {
+    const change = makeChange({
+      prev: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        lastEvent: "connected",
+      },
+      next: null,
+    });
+    expect(deriveSatelliteConnectionEvents(change)).toEqual([]);
+  });
+
+  it("fires nothing when lastEvent is missing/invalid", () => {
+    const change = makeChange({
+      next: {
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: "2026-05-31T00:00:00.000Z",
+        // lastEvent intentionally absent
+      },
+    });
+    expect(deriveSatelliteConnectionEvents(change)).toEqual([]);
+  });
+
+  it("returns event ids that exactly equal the qualified trigger ids", () => {
+    expect(SATELLITE_CONNECTED_EVENT).toBe("satellite.connected");
+    expect(SATELLITE_DISCONNECTED_EVENT).toBe("satellite.disconnected");
+    expect(SATELLITE_HEARTBEAT_LOST_EVENT).toBe("satellite.heartbeat_lost");
+  });
+});
+
+describe("satelliteConnectionStateSchema", () => {
+  it("accepts the canonical state shape", () => {
+    const ok = satelliteConnectionStateSchema.safeParse({
+      status: "offline",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: "2026-05-31T00:00:00.000Z",
+      lastEvent: "heartbeat_lost",
+    });
+    expect(ok.success).toBe(true);
+  });
+
+  it("rejects an unknown status", () => {
+    const bad = satelliteConnectionStateSchema.safeParse({
+      status: "degraded",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: "2026-05-31T00:00:00.000Z",
+      lastEvent: "connected",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+describe("toSatelliteConnectionState", () => {
+  it("computes online status from a recent lastHeartbeatAt", () => {
+    const recent = new Date(Date.now() - 5_000);
+    const state = toSatelliteConnectionState({
+      name: "edge-eu",
+      region: "eu",
+      lastHeartbeatAt: recent,
+      lastConnectionEvent: "connected",
+    });
+    expect(state).toEqual({
+      status: "online",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: recent.toISOString(),
+      lastEvent: "connected",
+    });
+  });
+
+  it("computes offline (self-heals) when lastHeartbeatAt has aged past the threshold", () => {
+    // This is the crash-recovery property: a row left marked `connected` by a
+    // crashed pod reads `offline` purely because its heartbeat aged out — the
+    // status is computed, never a stuck stored copy.
+    const aged = new Date(Date.now() - OFFLINE_THRESHOLD_MS - 10_000);
+    const state = toSatelliteConnectionState({
+      name: "edge-eu",
+      region: "eu",
+      lastHeartbeatAt: aged,
+      lastConnectionEvent: "connected",
+    });
+    expect(state!.status).toBe("offline");
+    expect(state!.lastSeenAt).toBe(aged.toISOString());
+    expect(state!.lastEvent).toBe("connected");
+  });
+
+  it("computes offline with null lastSeenAt after a clean disconnect (lastHeartbeatAt cleared)", () => {
+    const state = toSatelliteConnectionState({
+      name: "edge-eu",
+      region: "eu",
+      lastHeartbeatAt: null,
+      lastConnectionEvent: "disconnected",
+    });
+    expect(state).toEqual({
+      status: "offline",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: null,
+      lastEvent: "disconnected",
+    });
+  });
+
+  it("returns null for a never-connected satellite (no last edge yet)", () => {
+    // A satellite created but never connected has null lastConnectionEvent — it
+    // has no entity state, so the read omits it and the framework sees the first
+    // connect as a create (prev === null).
+    expect(
+      toSatelliteConnectionState({
+        name: "edge-eu",
+        region: "eu",
+        lastHeartbeatAt: null,
+        lastConnectionEvent: null,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("createSatelliteConnectionRead", () => {
+  it("routes the batched read straight to the durable service read", async () => {
+    // Proves the entity `read` resolves from the service (the durable
+    // `satellites` table) — so a fresh service instance, i.e. ANOTHER POD,
+    // sees the SAME state. This is the horizontal-scaling fix.
+    const seen: ReadonlyArray<string>[] = [];
+    const durableState: SatelliteConnectionState = {
+      status: "online",
+      name: "edge-eu",
+      region: "eu",
+      lastSeenAt: "2026-05-31T00:00:00.000Z",
+      lastEvent: "connected",
+    };
+    const service = {
+      async getManyConnectionStates(ids: ReadonlyArray<string>) {
+        seen.push(ids);
+        return { "sat-1": durableState };
+      },
+    } as unknown as SatelliteService;
+
+    const read = createSatelliteConnectionRead(service);
+    const out = await read(["sat-1", "sat-2"]);
+    expect(seen).toEqual([["sat-1", "sat-2"]]);
+    expect(out["sat-1"]).toEqual(durableState);
+    expect(out["sat-2"]).toBeUndefined();
+  });
+});

package/src/entity.ts

@@ -0,0 +1,221 @@
+/**
+ * Satellite connection reactive entity (reactive automation engine §10.6,
+ * §9.1).
+ *
+ * Satellite connection state is genuinely an entity: the WS handler's
+ * connection lifecycle and the heartbeat monitor's online→offline transition
+ * ARE state with diffs. The `satellite-connection` entity is PLUGIN-BACKED
+ * (Model B) and COMPUTE-ON-READ: its `status` is DERIVED on read from the
+ * durable `satellites.lastHeartbeatAt` column (via `computeStatus` /
+ * `OFFLINE_THRESHOLD_MS` — the SAME single liveness source of truth the admin
+ * list uses), so there is no second stored copy of the status to drift, and the
+ * read is globally consistent from any pod AND self-healing: a stale row reads
+ * `offline` once `lastHeartbeatAt` ages past the offline threshold, even if the
+ * pod that owned the socket crashed without writing offline. The only extra
+ * durable column is `lastConnectionEvent` (the deriver's event discriminator).
+ * There is NO framework `entity_state` mirror. This fixes a horizontal-scaling
+ * bug twice over: the original design stored status in a process-local in-memory
+ * map (invisible across pods), and the prior fix's stored `connectionStatus`
+ * still got stuck `online` forever after a pod crash because the heartbeat-lost
+ * EDGE was detected pod-locally. Computing status on read removes both.
+ *
+ * The three lifecycle sites that used to emit the `satellite.connected` /
+ * `.disconnected` / `.heartbeat_lost` hooks now drive `handle.mutate`, whose
+ * `apply` UPDATEs the satellite row's connection columns (the pod that owns the
+ * socket is the writer) and returns the view; the framework still records full
+ * transition HISTORY in `entity_transitions` (durable current state AND durable
+ * platform history). The persisted `satellites.lastHeartbeatAt` column stays as
+ * escape-hatched bookkeeping (declared non-reactive).
+ *
+ * The three hooks are removed; the change-deriver below maps an entity
+ * change back to the SAME qualified trigger event ids existing automations
+ * match. Because `disconnected` (socket drop) and `heartbeat_lost`
+ * (online→offline edge) BOTH move the connection toward "offline", a plain
+ * `status` diff cannot tell them apart. The entity therefore carries an
+ * explicit `lastEvent` discriminator naming the lifecycle edge that
+ * produced the change; the deriver reads it to preserve the three-way
+ * distinction the original triggers had.
+ */
+import { z } from "zod";
+import type { EntityChanged } from "@checkstack/automation-common";
+import type {
+  EntityChangePayloadMapper,
+  EntityRead,
+} from "@checkstack/automation-backend";
+import type { SatelliteService } from "./service";
+import { computeStatus } from "./status";
+
+/** Globally-unique entity kind for a satellite connection. */
+export const SATELLITE_CONNECTION_ENTITY_KIND = "satellite-connection";
+
+/**
+ * Qualified trigger event ids the deriver maps to — `${pluginId}.${triggerId}`
+ * for the (now-removed) connection triggers. Automations reference these
+ * strings in `definition.triggers[].event`, so the deriver MUST return them
+ * verbatim for Stage-1 routing to match.
+ */
+export const SATELLITE_CONNECTED_EVENT = "satellite.connected";
+export const SATELLITE_DISCONNECTED_EVENT = "satellite.disconnected";
+export const SATELLITE_HEARTBEAT_LOST_EVENT = "satellite.heartbeat_lost";
+
+/**
+ * The lifecycle edge that produced a connection-state change. Preserves the
+ * distinction between a socket drop (`disconnected`) and the heartbeat-lost
+ * offline edge (`heartbeat_lost`), which a bare `status` diff cannot encode.
+ */
+export const satelliteConnectionEventEnum = z.enum([
+  "connected",
+  "disconnected",
+  "heartbeat_lost",
+]);
+
+export type SatelliteConnectionEvent = z.infer<
+  typeof satelliteConnectionEventEnum
+>;
+
+/** Reactive state of a satellite connection (reactive automation engine §9.1). */
+export const satelliteConnectionStateSchema = z.object({
+  /**
+   * COMPUTED on read from `lastHeartbeatAt` (the single liveness source of
+   * truth). Never stored — a stale row reads `offline` once the heartbeat ages
+   * past the offline threshold, so presence self-heals after a pod crash.
+   */
+  status: z.enum(["online", "offline"]),
+  name: z.string(),
+  region: z.string(),
+  /**
+   * ISO timestamp the satellite was last seen alive (its `lastHeartbeatAt`), or
+   * `null` after a clean disconnect (when `lastHeartbeatAt` is cleared so the
+   * status flips offline immediately). Derived, not separately stored.
+   */
+  lastSeenAt: z.string().nullable(),
+  /** Which lifecycle edge produced the latest change (see above). */
+  lastEvent: satelliteConnectionEventEnum,
+});
+
+export type SatelliteConnectionState = z.infer<
+  typeof satelliteConnectionStateSchema
+>;
+
+/**
+ * Map a `satellite-connection` entity change to the qualified trigger event
+ * id(s) it should fire (reactive automation engine §7, §10.6). The
+ * `lastEvent` discriminator on the NEW state names the lifecycle edge,
+ * so the mapping is exact and preserves the three-way distinction:
+ *
+ *   - `connected`      → `satellite.connected`
+ *   - `disconnected`   → `satellite.disconnected`
+ *   - `heartbeat_lost` → `satellite.heartbeat_lost`
+ *
+ * A tombstone (`next === null`, e.g. an entity removed when the satellite is
+ * deleted) fires nothing — satellite deletion has its own `satellite.removed`
+ * hook (kept), not a connection-lifecycle event.
+ */
+export function deriveSatelliteConnectionEvents(
+  changed: EntityChanged,
+): ReadonlyArray<string> {
+  if (changed.next === null) return [];
+  const parsed = satelliteConnectionEventEnum.safeParse(
+    changed.next["lastEvent"],
+  );
+  if (!parsed.success) return [];
+  switch (parsed.data) {
+    case "connected": {
+      return [SATELLITE_CONNECTED_EVENT];
+    }
+    case "disconnected": {
+      return [SATELLITE_DISCONNECTED_EVENT];
+    }
+    case "heartbeat_lost": {
+      return [SATELLITE_HEARTBEAT_LOST_EVENT];
+    }
+  }
+}
+
+function readString(
+  state: Record<string, unknown> | null,
+  field: string,
+): string | undefined {
+  if (state === null) return undefined;
+  const value = state[field];
+  return typeof value === "string" ? value : undefined;
+}
+
+/**
+ * Map a `satellite-connection` entity change to the domain-named
+ * `trigger.payload` the connection triggers declare via `payloadSchema`
+ * (`satelliteId`, `name`, `region`, `status`, `lastSeenAt`). Restores the keys
+ * operators read (`trigger.payload.satelliteId`, `.name`, …) that the generic
+ * change shape omits, so an entity-driven connection trigger sees the same
+ * documented payload the four migrated lifecycle domains do.
+ *
+ * `satelliteId` is the entity id; the remaining fields read off `next` (a
+ * tombstone fires no event, so `next` is always present when a trigger fires).
+ * `lastSeenAt` is nullable (`null` after a clean disconnect).
+ */
+export const satelliteChangeToPayload: EntityChangePayloadMapper = (changed) => {
+  const next = changed.next;
+  const lastSeenAt = next === null ? null : next["lastSeenAt"];
+  return {
+    satelliteId: changed.id,
+    name: readString(next, "name"),
+    region: readString(next, "region"),
+    status: readString(next, "status"),
+    lastSeenAt: typeof lastSeenAt === "string" ? lastSeenAt : null,
+  };
+};
+
+/**
+ * The durable connection columns of a satellite row, as read from the shared
+ * `satellites` table. This is the raw shape the service returns for the entity
+ * `read` accessor; {@link toSatelliteConnectionState} projects it onto the
+ * reactive view by COMPUTING `status` from `lastHeartbeatAt`. A satellite that
+ * has never connected has `lastConnectionEvent === null` (no recorded edge yet).
+ */
+export interface SatelliteConnectionRow {
+  name: string;
+  region: string;
+  /** The single durable liveness source of truth; `status` is computed from it. */
+  lastHeartbeatAt: Date | null;
+  lastConnectionEvent: SatelliteConnectionEvent | null;
+}
+
+/**
+ * Project a durable `satellites` connection row onto the reactive
+ * `SatelliteConnectionState` view (the exact shape the deriver + change events
+ * consume). `status` is COMPUTED on read from `lastHeartbeatAt` via
+ * {@link computeStatus} — never read from a stored copy — so it is globally
+ * consistent and self-heals to `offline` once the heartbeat ages out. A
+ * satellite with no recorded lifecycle edge yet (never connected,
+ * `lastConnectionEvent === null`) has no entity state, so this returns `null`
+ * and the `read` accessor omits the id — exactly the `prev === null` (create)
+ * signal the framework needs on the first connect.
+ */
+export function toSatelliteConnectionState(
+  row: SatelliteConnectionRow,
+): SatelliteConnectionState | null {
+  if (row.lastConnectionEvent === null) {
+    return null;
+  }
+  return {
+    status: computeStatus(row.lastHeartbeatAt),
+    name: row.name,
+    region: row.region,
+    lastSeenAt: row.lastHeartbeatAt ? row.lastHeartbeatAt.toISOString() : null,
+    lastEvent: row.lastConnectionEvent,
+  };
+}
+
+/**
+ * Build the PLUGIN-BACKED `read` accessor for the `satellite-connection`
+ * entity. Routes straight to the service's batched durable read of the
+ * `satellites` connection columns (no framework storage), so the current state
+ * is the SAME for every pod — this is what makes the entity globally consistent
+ * and is the single source of truth `handle.mutate` snapshots `prev` from and
+ * `get` / `getMany` / scope enrichment / `wait_until` re-eval route through.
+ */
+export function createSatelliteConnectionRead(
+  service: SatelliteService,
+): EntityRead<SatelliteConnectionState> {
+  return (ids) => service.getManyConnectionStates(ids);
+}