@checkstack/satellite-backend 0.4.0 → 0.5.0

package/src/service.test.ts

@@ -289,4 +289,278 @@ describe("SatelliteService", () => {
       expect(ids).toEqual(["online-1"]);
     });
   });
+
+  describe("getManyConnectionStates (durable, compute-on-read entity read)", () => {
+    it("computes online status from a recent durable lastHeartbeatAt", async () => {
+      const recent = new Date(Date.now() - 5_000);
+      let whereArg: unknown;
+      const db = {
+        select: mock(() => ({
+          from: mock(() => ({
+            where: mock((arg: unknown) => {
+              whereArg = arg;
+              return Promise.resolve([
+                {
+                  id: "sat-1",
+                  name: "edge-eu",
+                  region: "eu",
+                  lastHeartbeatAt: recent,
+                  lastConnectionEvent: "connected",
+                },
+              ]);
+            }),
+          })),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const out = await service.getManyConnectionStates(["sat-1", "sat-2"]);
+
+      expect(whereArg).toBeDefined();
+      expect(out).toEqual({
+        "sat-1": {
+          status: "online",
+          name: "edge-eu",
+          region: "eu",
+          lastSeenAt: recent.toISOString(),
+          lastEvent: "connected",
+        },
+      });
+      // A satellite absent from the result is simply omitted (prev === null).
+      expect(out["sat-2"]).toBeUndefined();
+    });
+
+    it("self-heals an aged-out row to offline (crashed pod left it 'connected')", async () => {
+      // The horizontal-scale fix: a satellite whose heartbeat aged past the
+      // threshold reads OFFLINE even though its last edge is still `connected`,
+      // because status is computed, never a stuck stored copy.
+      const aged = new Date(Date.now() - OFFLINE_THRESHOLD_MS - 10_000);
+      const db = {
+        select: mock(() => ({
+          from: mock(() => ({
+            where: mock(() =>
+              Promise.resolve([
+                {
+                  id: "sat-1",
+                  name: "edge-eu",
+                  region: "eu",
+                  lastHeartbeatAt: aged,
+                  lastConnectionEvent: "connected",
+                },
+              ]),
+            ),
+          })),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const out = await service.getManyConnectionStates(["sat-1"]);
+      expect(out["sat-1"]!.status).toBe("offline");
+    });
+
+    it("omits never-connected satellites (null lastConnectionEvent)", async () => {
+      const db = {
+        select: mock(() => ({
+          from: mock(() => ({
+            where: mock(() =>
+              Promise.resolve([
+                {
+                  id: "sat-1",
+                  name: "edge-eu",
+                  region: "eu",
+                  lastHeartbeatAt: null,
+                  lastConnectionEvent: null,
+                },
+              ]),
+            ),
+          })),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      expect(await service.getManyConnectionStates(["sat-1"])).toEqual({});
+    });
+
+    it("short-circuits an empty id list without touching the db", async () => {
+      const select = mock(() => ({ from: mock() }));
+      const db = { select } as unknown as ConstructorParameters<
+        typeof SatelliteService
+      >[0];
+      const service = new SatelliteService(db);
+      expect(await service.getManyConnectionStates([])).toEqual({});
+      expect(select).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("applyConnectionState (durable lifecycle write)", () => {
+    it("connect: sets lastHeartbeatAt=now + connected and returns an online view", async () => {
+      const now = new Date(Date.now() - 1_000);
+      let setArg:
+        | { lastConnectionEvent?: string; lastHeartbeatAt?: Date | null }
+        | undefined;
+      const db = {
+        update: mock(() => ({
+          set: mock((arg: typeof setArg) => {
+            setArg = arg;
+            return {
+              where: mock(() => ({
+                returning: mock(() =>
+                  Promise.resolve([
+                    {
+                      id: "sat-1",
+                      name: "edge-eu",
+                      region: "eu",
+                      lastConnectionEvent: "connected",
+                      tags: {},
+                      tokenHash: "h",
+                      lastHeartbeatAt: now,
+                      version: null,
+                      createdAt: new Date(),
+                    },
+                  ]),
+                ),
+              })),
+            };
+          }),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const next = await service.applyConnectionState({
+        satelliteId: "sat-1",
+        lastEvent: "connected",
+        lastHeartbeatAt: now,
+      });
+
+      expect(setArg).toEqual({
+        lastConnectionEvent: "connected",
+        lastHeartbeatAt: now,
+      });
+      expect(next).toEqual({
+        status: "online",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: now.toISOString(),
+        lastEvent: "connected",
+      });
+    });
+
+    it("clean disconnect: clears lastHeartbeatAt (null) so the view is offline immediately", async () => {
+      let setArg:
+        | { lastConnectionEvent?: string; lastHeartbeatAt?: Date | null }
+        | undefined;
+      const db = {
+        update: mock(() => ({
+          set: mock((arg: typeof setArg) => {
+            setArg = arg;
+            return {
+              where: mock(() => ({
+                returning: mock(() =>
+                  Promise.resolve([
+                    {
+                      id: "sat-1",
+                      name: "edge-eu",
+                      region: "eu",
+                      lastConnectionEvent: "disconnected",
+                      tags: {},
+                      tokenHash: "h",
+                      lastHeartbeatAt: null,
+                      version: null,
+                      createdAt: new Date(),
+                    },
+                  ]),
+                ),
+              })),
+            };
+          }),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const next = await service.applyConnectionState({
+        satelliteId: "sat-1",
+        lastEvent: "disconnected",
+        lastHeartbeatAt: null,
+      });
+
+      expect(setArg).toEqual({
+        lastConnectionEvent: "disconnected",
+        lastHeartbeatAt: null,
+      });
+      expect(next).toEqual({
+        status: "offline",
+        name: "edge-eu",
+        region: "eu",
+        lastSeenAt: null,
+        lastEvent: "disconnected",
+      });
+    });
+
+    it("heartbeat_lost: flips ONLY lastConnectionEvent, leaving the aged heartbeat untouched", async () => {
+      const aged = new Date(Date.now() - OFFLINE_THRESHOLD_MS - 10_000);
+      let setArg:
+        | { lastConnectionEvent?: string; lastHeartbeatAt?: Date | null }
+        | undefined;
+      const db = {
+        update: mock(() => ({
+          set: mock((arg: typeof setArg) => {
+            setArg = arg;
+            return {
+              where: mock(() => ({
+                returning: mock(() =>
+                  Promise.resolve([
+                    {
+                      id: "sat-1",
+                      name: "edge-eu",
+                      region: "eu",
+                      lastConnectionEvent: "heartbeat_lost",
+                      tags: {},
+                      tokenHash: "h",
+                      lastHeartbeatAt: aged,
+                      version: null,
+                      createdAt: new Date(),
+                    },
+                  ]),
+                ),
+              })),
+            };
+          }),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const next = await service.applyConnectionState({
+        satelliteId: "sat-1",
+        lastEvent: "heartbeat_lost",
+        // lastHeartbeatAt omitted ⇒ left unchanged.
+      });
+
+      // Only the event column was written — no lastHeartbeatAt key.
+      expect(setArg).toEqual({ lastConnectionEvent: "heartbeat_lost" });
+      expect(next.status).toBe("offline");
+      expect(next.lastEvent).toBe("heartbeat_lost");
+      expect(next.lastSeenAt).toBe(aged.toISOString());
+    });
+
+    it("throws when the satellite no longer exists", async () => {
+      const db = {
+        update: mock(() => ({
+          set: mock(() => ({
+            where: mock(() => ({
+              returning: mock(() => Promise.resolve([])),
+            })),
+          })),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      await expect(
+        service.applyConnectionState({
+          satelliteId: "gone",
+          lastEvent: "connected",
+          lastHeartbeatAt: new Date(),
+        }),
+      ).rejects.toThrow(/not found/);
+    });
+  });
 });

package/src/service.ts

@@ -1,25 +1,18 @@
-import { eq } from "drizzle-orm";
+import { eq, inArray } from "drizzle-orm";
 import { satellites } from "./schema";
 import * as schema from "./schema";
 import type { SafeDatabase } from "@checkstack/backend-api";
-import type {
-  SatelliteWithStatus,
-  SatelliteStatus,
-} from "@checkstack/satellite-common";
-import { OFFLINE_THRESHOLD_MS } from "@checkstack/satellite-common";
+import type { SatelliteWithStatus } from "@checkstack/satellite-common";
+import {
+  toSatelliteConnectionState,
+  type SatelliteConnectionEvent,
+  type SatelliteConnectionState,
+} from "./entity";
+import { computeStatus } from "./status";
 
 // Drizzle type helper
 type Db = SafeDatabase<typeof schema>;
 
-/**
- * Compute satellite status from lastHeartbeatAt timestamp.
- */
-function computeStatus(lastHeartbeatAt: Date | null): SatelliteStatus {
-  if (!lastHeartbeatAt) return "offline";
-  const elapsed = Date.now() - lastHeartbeatAt.getTime();
-  return elapsed <= OFFLINE_THRESHOLD_MS ? "online" : "offline";
-}
-
 /**
  * Service for managing satellite records.
  */
@@ -217,6 +210,131 @@ export class SatelliteService {
       .map((row) => row.id);
   }
 
+  /**
+   * Batched durable read for the `satellite-connection` entity (Model B
+   * plugin-backed `read` accessor). Given satellite ids, return the reactive
+   * `SatelliteConnectionState` for each that exists AND has connected at least
+   * once (missing / never-connected ids omitted). The reactive `status` is
+   * COMPUTED on read from the durable `lastHeartbeatAt` column (the single
+   * liveness source of truth, shared by every pod) — never read from a stored
+   * status copy — so any pod sees the same answer AND a stale row self-heals to
+   * `offline` once the heartbeat ages out, even after a pod crash. Only
+   * `lastConnectionEvent` is read additionally (the deriver's discriminator).
+   * This is the single source of truth `handle.mutate` snapshots `prev` from and
+   * `get` / `getMany` / scope enrichment / `wait_until` re-eval route through.
+   */
+  async getManyConnectionStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<Record<string, SatelliteConnectionState>> {
+    if (ids.length === 0) return {};
+
+    const rows = await this.db
+      .select({
+        id: satellites.id,
+        name: satellites.name,
+        region: satellites.region,
+        lastHeartbeatAt: satellites.lastHeartbeatAt,
+        lastConnectionEvent: satellites.lastConnectionEvent,
+      })
+      .from(satellites)
+      .where(inArray(satellites.id, [...ids]));
+
+    const out: Record<string, SatelliteConnectionState> = {};
+    for (const row of rows) {
+      const state = toSatelliteConnectionState({
+        name: row.name,
+        region: row.region,
+        lastHeartbeatAt: row.lastHeartbeatAt,
+        lastConnectionEvent: row.lastConnectionEvent,
+      });
+      if (state) out[row.id] = state;
+    }
+    return out;
+  }
+
+  /**
+   * Read every satellite's durable liveness inputs `(lastHeartbeatAt,
+   * lastConnectionEvent)`. Used by the heartbeat monitor to detect the
+   * online→offline (heartbeat-lost) edge from DURABLE state alone — no pod-local
+   * baseline — so detection works on ANY pod and is idempotent across pods /
+   * redelivery. The monitor computes status from `lastHeartbeatAt` itself.
+   */
+  async listConnectionLiveness(): Promise<
+    Array<{
+      id: string;
+      name: string;
+      region: string;
+      lastHeartbeatAt: Date | null;
+      lastConnectionEvent: SatelliteConnectionEvent | null;
+    }>
+  > {
+    return this.db
+      .select({
+        id: satellites.id,
+        name: satellites.name,
+        region: satellites.region,
+        lastHeartbeatAt: satellites.lastHeartbeatAt,
+        lastConnectionEvent: satellites.lastConnectionEvent,
+      })
+      .from(satellites);
+  }
+
+  /**
+   * Durable write for a `satellite-connection` lifecycle edge (the `apply`
+   * body of `handle.mutate`). UPDATEs the satellite's liveness columns in the
+   * shared `satellites` table and returns the resulting reactive view (`next`),
+   * whose `status` is COMPUTED from the just-written `lastHeartbeatAt`. The
+   * caller passes the new `lastHeartbeatAt` explicitly so each edge controls
+   * liveness directly:
+   *   - connect / reconnect → `now` (computes online),
+   *   - clean disconnect    → `null` (computes offline immediately),
+   *   - heartbeat-lost      → unchanged (`undefined` leaves the column as the
+   *     already-aged value, which still computes offline) — only
+   *     `lastConnectionEvent` flips, which is what makes monitor detection
+   *     idempotent.
+   * The pod that owns the socket (or any pod, for heartbeat-lost) is the writer;
+   * every other pod reads the new state via {@link getManyConnectionStates}.
+   * Throws when the satellite no longer exists (a write against a deleted
+   * satellite is a no-op caller error).
+   */
+  async applyConnectionState(props: {
+    satelliteId: string;
+    lastEvent: SatelliteConnectionEvent;
+    /** New heartbeat timestamp, or `null` to clear it. Omit to leave unchanged. */
+    lastHeartbeatAt?: Date | null;
+  }): Promise<SatelliteConnectionState> {
+    const { satelliteId, lastEvent, lastHeartbeatAt } = props;
+
+    const updates: Partial<typeof satellites.$inferInsert> = {
+      lastConnectionEvent: lastEvent,
+    };
+    if (lastHeartbeatAt !== undefined) {
+      updates.lastHeartbeatAt = lastHeartbeatAt;
+    }
+
+    const [row] = await this.db
+      .update(satellites)
+      .set(updates)
+      .where(eq(satellites.id, satelliteId))
+      .returning();
+
+    if (!row) {
+      throw new Error(
+        `Cannot apply connection state: satellite ${satelliteId} not found`,
+      );
+    }
+
+    return {
+      status: computeStatus(row.lastHeartbeatAt),
+      name: row.name,
+      region: row.region,
+      lastSeenAt: row.lastHeartbeatAt
+        ? row.lastHeartbeatAt.toISOString()
+        : null,
+      lastEvent,
+    };
+  }
+
   /**
    * Map a database row to SatelliteWithStatus (excludes tokenHash).
    */

package/src/status.ts

@@ -0,0 +1,18 @@
+import type { SatelliteStatus } from "@checkstack/satellite-common";
+import { OFFLINE_THRESHOLD_MS } from "@checkstack/satellite-common";
+
+/**
+ * Compute satellite liveness status from its `lastHeartbeatAt` timestamp — the
+ * SINGLE source of truth for presence. A satellite is `online` only while its
+ * most recent heartbeat is within {@link OFFLINE_THRESHOLD_MS} of now; a missing
+ * timestamp (never connected / cleanly disconnected) or an aged one is
+ * `offline`. Because this reads only durable, globally-shared state and a
+ * wall-clock comparison, every pod computes the SAME answer and a stale row
+ * self-heals to `offline` once the heartbeat ages out — no pod-local baseline,
+ * no status that can get stuck `online` after a pod crash.
+ */
+export function computeStatus(lastHeartbeatAt: Date | null): SatelliteStatus {
+  if (!lastHeartbeatAt) return "offline";
+  const elapsed = Date.now() - lastHeartbeatAt.getTime();
+  return elapsed <= OFFLINE_THRESHOLD_MS ? "online" : "offline";
+}

package/tsconfig.json

@@ -7,6 +7,9 @@
     {
       "path": "../automation-backend"
     },
+    {
+      "path": "../automation-common"
+    },
     {
       "path": "../backend-api"
     },
@@ -31,6 +34,18 @@
     {
       "path": "../satellite-common"
     },
+    {
+      "path": "../script-packages-backend"
+    },
+    {
+      "path": "../script-packages-common"
+    },
+    {
+      "path": "../secrets-backend"
+    },
+    {
+      "path": "../secrets-common"
+    },
     {
       "path": "../signal-common"
     },

package/src/automations.test.ts

@@ -1,54 +0,0 @@
-/**
- * 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);
-  });
-});