@checkstack/satellite-backend 0.2.0

package/src/router.ts

@@ -0,0 +1,83 @@
+import { implement } from "@orpc/server";
+import {
+  satelliteContract,
+  SATELLITE_STATUS_CHANGED,
+  SATELLITE_CONFIG_CHANGED,
+} from "@checkstack/satellite-common";
+import {
+  autoAuthMiddleware,
+  type RpcContext,
+  type Logger,
+} from "@checkstack/backend-api";
+import type { SignalService } from "@checkstack/signal-common";
+import type { SatelliteService } from "./service";
+
+/**
+ * RPC router for satellite management.
+ * Implements the satelliteContract from satellite-common using oRPC's
+ * implement pattern with autoAuthMiddleware.
+ */
+export function createSatelliteRouter(props: {
+  service: SatelliteService;
+  signalService: SignalService;
+  logger: Logger;
+}) {
+  const { service, signalService, logger } = props;
+
+  const os = implement(satelliteContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
+
+  return os.router({
+    listSatellites: os.listSatellites.handler(async () => {
+      const satellites = await service.listSatellites();
+      return { satellites };
+    }),
+
+    getSatellite: os.getSatellite.handler(async ({ input }) => {
+      const satellite = await service.getSatellite(input.id);
+      // eslint-disable-next-line unicorn/no-null -- oRPC contract uses nullable()
+      return satellite ?? null;
+    }),
+
+    createSatellite: os.createSatellite.handler(async ({ input }) => {
+      const { satellite, plaintextToken } =
+        await service.createSatellite(input);
+
+      logger.info(
+        `Satellite created: ${satellite.name} (${satellite.region})`,
+      );
+
+      // Signal config change so UI refreshes
+      await signalService.broadcast(SATELLITE_CONFIG_CHANGED, {
+        satelliteId: satellite.id,
+      });
+
+      return { satellite, token: plaintextToken };
+    }),
+
+    deleteSatellite: os.deleteSatellite.handler(async ({ input }) => {
+      const satellite = await service.getSatellite(input.id);
+      if (!satellite) return;
+
+      await service.deleteSatellite(input.id);
+
+      logger.info(
+        `Satellite deleted: ${satellite.name} (${satellite.region})`,
+      );
+
+      // Signal status change (satellite gone)
+      await signalService.broadcast(SATELLITE_STATUS_CHANGED, {
+        satelliteId: input.id,
+        status: "offline",
+        name: satellite.name,
+        region: satellite.region,
+      });
+    }),
+
+    getOnlineSatelliteIds: os.getOnlineSatelliteIds.handler(async () => {
+      const satelliteIds = await service.getOnlineSatelliteIds();
+      return { satelliteIds };
+    }),
+  });
+}

package/src/satellite-ws-handler.test.ts

@@ -0,0 +1,265 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import {
+  SatelliteWsHandler,
+  type SatelliteResultHandler,
+} from "./satellite-ws-handler";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+import type { SatelliteService } from "./service";
+import type { ConfigRelay } from "./config-relay";
+import type { SatelliteWithStatus } from "@checkstack/satellite-common";
+
+const MOCK_SATELLITE: SatelliteWithStatus = {
+  id: "sat-1",
+  name: "EU West",
+  region: "eu-west-1",
+  tags: {},
+  status: "online",
+  createdAt: new Date(),
+};
+
+const MOCK_ASSIGNMENTS = [
+  {
+    configId: "config-1",
+    systemId: "system-1",
+    strategyId: "http",
+    config: { url: "https://example.com" },
+    intervalSeconds: 60,
+  },
+];
+
+function createMockService(
+  validSatellite?: SatelliteWithStatus,
+): SatelliteService {
+  return {
+    validateToken: mock(async (props: { clientId: string; token: string }) => {
+      if (
+        validSatellite &&
+        props.clientId === validSatellite.id &&
+        props.token === "csat_valid-token"
+      ) {
+        return validSatellite;
+      }
+      return undefined;
+    }),
+    updateHeartbeat: mock(async () => {}),
+  } as unknown as SatelliteService;
+}
+
+function createMockConfigRelay(): ConfigRelay {
+  return {
+    getAssignmentsForSatellite: mock(async () => MOCK_ASSIGNMENTS),
+  } as unknown as ConfigRelay;
+}
+
+function createMockResultHandler(): SatelliteResultHandler {
+  return {
+    handleResult: mock(async () => {}),
+  };
+}
+
+function createMockWs() {
+  const messages: string[] = [];
+  return {
+    send: mock((data: string) => messages.push(data)),
+    close: mock(() => {}),
+    messages,
+  };
+}
+
+describe("SatelliteWsHandler", () => {
+  let handler: SatelliteWsHandler;
+  let service: ReturnType<typeof createMockService>;
+  let configRelay: ReturnType<typeof createMockConfigRelay>;
+  let resultHandler: SatelliteResultHandler;
+  let logger: ReturnType<typeof createMockLogger>;
+
+  beforeEach(() => {
+    service = createMockService(MOCK_SATELLITE);
+    configRelay = createMockConfigRelay();
+    resultHandler = createMockResultHandler();
+    logger = createMockLogger();
+    handler = new SatelliteWsHandler(
+      service,
+      configRelay,
+      resultHandler,
+      logger,
+    );
+  });
+
+  describe("authentication", () => {
+    it("should authenticate with valid clientId and token", async () => {
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+
+      expect(ws.close).not.toHaveBeenCalled();
+      expect(ws.messages).toHaveLength(1);
+
+      const response = JSON.parse(ws.messages[0]);
+      expect(response.type).toBe("authenticated");
+      expect(response.satelliteId).toBe("sat-1");
+      expect(response.assignments).toEqual(MOCK_ASSIGNMENTS);
+    });
+
+    it("should reject invalid credentials", async () => {
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_invalid-token",
+        }),
+      );
+
+      expect(ws.close).toHaveBeenCalled();
+      expect(ws.messages).toHaveLength(1);
+      const response = JSON.parse(ws.messages[0]);
+      expect(response.type).toBe("auth_failed");
+    });
+
+    it("should reject non-authenticate messages before auth", async () => {
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+
+      await onMessage(
+        JSON.stringify({
+          type: "heartbeat",
+          version: "1.0.0",
+          uptimeSeconds: 60,
+        }),
+      );
+
+      expect(ws.close).toHaveBeenCalled();
+      const response = JSON.parse(ws.messages[0]);
+      expect(response.type).toBe("auth_failed");
+      expect(response.reason).toBe("Must authenticate first");
+    });
+  });
+
+  describe("post-authentication", () => {
+    async function authenticateWs() {
+      const ws = createMockWs();
+      const { onMessage, onClose } = handler.onConnection(ws);
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      // Clear the authenticated message from history
+      ws.messages.length = 0;
+      return { ws, onMessage, onClose };
+    }
+
+    it("should handle heartbeat messages", async () => {
+      const { onMessage } = await authenticateWs();
+
+      await onMessage(
+        JSON.stringify({
+          type: "heartbeat",
+          version: "1.2.3",
+          uptimeSeconds: 120,
+        }),
+      );
+
+      expect(service.updateHeartbeat).toHaveBeenCalledWith("sat-1", {
+        version: "1.2.3",
+      });
+    });
+
+    it("should handle result messages", async () => {
+      const { onMessage } = await authenticateWs();
+
+      const resultMsg = {
+        type: "result",
+        configId: "config-1",
+        systemId: "system-1",
+        status: "healthy",
+        latencyMs: 42,
+        result: {
+          status: "healthy",
+          latencyMs: 42,
+          metadata: {
+            connected: true,
+            connectionTimeMs: 40,
+          },
+        },
+        executedAt: new Date().toISOString(),
+      };
+
+      await onMessage(JSON.stringify(resultMsg));
+
+      expect(resultHandler.handleResult).toHaveBeenCalledWith({
+        satelliteId: "sat-1",
+        sourceLabel: "EU West (eu-west-1)",
+        result: expect.objectContaining({
+          type: "result",
+          configId: "config-1",
+          systemId: "system-1",
+          status: "healthy",
+        }),
+      });
+    });
+
+    it("should log strategy errors", async () => {
+      const { onMessage } = await authenticateWs();
+
+      await onMessage(
+        JSON.stringify({
+          type: "strategy_error",
+          strategyId: "grpc",
+          message: "Strategy not available",
+        }),
+      );
+
+      expect(logger.warn).toHaveBeenCalled();
+    });
+
+    it("should clean up connection on close", async () => {
+      const { onClose } = await authenticateWs();
+      onClose();
+
+      expect(handler.getConnectedSatelliteIds()).not.toContain("sat-1");
+    });
+  });
+
+  describe("pushConfigUpdate", () => {
+    it("should send config update to connected satellites", async () => {
+      const ws = createMockWs();
+      const { onMessage } = handler.onConnection(ws);
+
+      // Authenticate
+      await onMessage(
+        JSON.stringify({
+          type: "authenticate",
+          clientId: "sat-1",
+          token: "csat_valid-token",
+        }),
+      );
+      ws.messages.length = 0;
+
+      // Push config update
+      await handler.pushConfigUpdate("sat-1");
+
+      expect(ws.messages).toHaveLength(1);
+      const update = JSON.parse(ws.messages[0]);
+      expect(update.type).toBe("config_updated");
+      expect(update.assignments).toEqual(MOCK_ASSIGNMENTS);
+    });
+
+    it("should silently skip disconnected satellites", async () => {
+      // No satellite connected — should not throw
+      await handler.pushConfigUpdate("non-existent");
+    });
+  });
+});

package/src/satellite-ws-handler.ts

@@ -0,0 +1,222 @@
+import type { Logger } from "@checkstack/backend-api";
+import type {
+  WebSocketRouteHandler,
+  WsConnection,
+  WsConnectionHandlers,
+} from "@checkstack/backend-api";
+import type { SatelliteService } from "./service";
+import type { ConfigRelay } from "./config-relay";
+import {
+  SatelliteToCoreMessageSchema,
+  type CoreToSatelliteMessage,
+  type ResultMessage,
+  type SatelliteWithStatus,
+} from "@checkstack/satellite-common";
+
+/**
+ * Callback for handling health check results received from satellites.
+ */
+export interface SatelliteResultHandler {
+  handleResult(props: {
+    satelliteId: string;
+    sourceLabel: string;
+    result: ResultMessage;
+  }): Promise<void>;
+}
+
+/**
+ * Active satellite connection tracking.
+ */
+interface SatelliteConnection {
+  satellite: SatelliteWithStatus;
+  ws: WsConnection;
+}
+
+/**
+ * WebSocket handler for satellite connections.
+ * Manages authentication, heartbeats, result ingestion, and config pushes.
+ */
+export class SatelliteWsHandler implements WebSocketRouteHandler {
+  /** Map of satelliteId → active WebSocket connection */
+  private connections = new Map<string, SatelliteConnection>();
+
+  constructor(
+    private service: SatelliteService,
+    private configRelay: ConfigRelay,
+    private resultHandler: SatelliteResultHandler,
+    private logger: Logger,
+  ) {}
+
+  /**
+   * Handle a new WebSocket connection (pre-authentication).
+   * The satellite must send an `authenticate` message as its first message.
+   * Implements WebSocketRouteHandler.onConnection.
+   */
+  onConnection(ws: WsConnection): WsConnectionHandlers {
+    let authenticatedSatellite: SatelliteWithStatus | undefined;
+
+    const onMessage = async (message: string) => {
+      let parsed: ReturnType<typeof SatelliteToCoreMessageSchema.parse>;
+      try {
+        parsed = SatelliteToCoreMessageSchema.parse(JSON.parse(message));
+      } catch {
+        this.logger.warn("Invalid satellite message received");
+        return;
+      }
+
+      // Pre-authentication: only accept `authenticate`
+      if (!authenticatedSatellite) {
+        if (parsed.type !== "authenticate") {
+          this.sendMessage(ws, {
+            type: "auth_failed",
+            reason: "Must authenticate first",
+          });
+          ws.close();
+          return;
+        }
+
+        const satellite = await this.service.validateToken({
+          clientId: parsed.clientId,
+          token: parsed.token,
+        });
+
+        if (!satellite) {
+          this.sendMessage(ws, {
+            type: "auth_failed",
+            reason: "Invalid client ID or token",
+          });
+          ws.close();
+          return;
+        }
+
+        authenticatedSatellite = satellite;
+
+        // Track connection
+        this.connections.set(satellite.id, { satellite, ws });
+
+        // Update heartbeat on connect
+        await this.service.updateHeartbeat(satellite.id, {});
+
+        // Send authenticated response with full config
+        const assignments =
+          await this.configRelay.getAssignmentsForSatellite(satellite.id);
+
+        this.sendMessage(ws, {
+          type: "authenticated",
+          satelliteId: satellite.id,
+          assignments,
+        });
+
+        this.logger.info(
+          `Satellite authenticated: ${satellite.name} (${satellite.region})`,
+        );
+        return;
+      }
+
+      // Post-authentication: handle all message types
+      switch (parsed.type) {
+        case "heartbeat": {
+          await this.service.updateHeartbeat(authenticatedSatellite.id, {
+            version: parsed.version,
+          });
+          break;
+        }
+        case "result": {
+          await this.resultHandler.handleResult({
+            satelliteId: authenticatedSatellite.id,
+            sourceLabel: `${authenticatedSatellite.name} (${authenticatedSatellite.region})`,
+            result: parsed,
+          });
+          break;
+        }
+        case "strategy_error": {
+          this.logger.warn(
+            `Satellite ${authenticatedSatellite.name} reports strategy error: ${parsed.strategyId} - ${parsed.message}`,
+          );
+          break;
+        }
+        case "authenticate": {
+          // Already authenticated, ignore duplicate auth attempts
+          this.logger.debug(
+            `Satellite ${authenticatedSatellite.name} sent duplicate authenticate`,
+          );
+          break;
+        }
+      }
+    };
+
+    const onClose = () => {
+      if (authenticatedSatellite) {
+        this.connections.delete(authenticatedSatellite.id);
+        this.logger.info(
+          `Satellite disconnected: ${authenticatedSatellite.name} (${authenticatedSatellite.region})`,
+        );
+      }
+    };
+
+    return { onMessage, onClose };
+  }
+
+  /**
+   * Push a config update to a specific satellite.
+   */
+  async pushConfigUpdate(satelliteId: string): Promise<void> {
+    const conn = this.connections.get(satelliteId);
+    if (!conn) return;
+
+    const assignments =
+      await this.configRelay.getAssignmentsForSatellite(satelliteId);
+
+    this.sendMessage(conn.ws, {
+      type: "config_updated",
+      assignments,
+    });
+
+    this.logger.debug(
+      `Pushed config update to satellite ${conn.satellite.name}: ${assignments.length} assignments`,
+    );
+  }
+
+  /**
+   * Send a shutdown message to a specific satellite (e.g., on token revocation).
+   */
+  sendShutdown(satelliteId: string, reason: string): void {
+    const conn = this.connections.get(satelliteId);
+    if (!conn) return;
+
+    this.sendMessage(conn.ws, { type: "shutdown", reason });
+    conn.ws.close();
+    this.connections.delete(satelliteId);
+  }
+
+  /**
+   * Push config updates to ALL currently connected satellites.
+   * Called after association changes to ensure live satellites get updated assignments.
+   */
+  async pushConfigUpdateToAll(): Promise<void> {
+    const connectedIds = this.getConnectedSatelliteIds();
+    if (connectedIds.length === 0) return;
+
+    this.logger.debug(
+      `Pushing config updates to ${connectedIds.length} connected satellite(s)`,
+    );
+
+    await Promise.all(
+      connectedIds.map((id) => this.pushConfigUpdate(id)),
+    );
+  }
+
+  /**
+   * Get the IDs of all currently connected satellites.
+   */
+  getConnectedSatelliteIds(): string[] {
+    return [...this.connections.keys()];
+  }
+
+  private sendMessage(
+    ws: WsConnection,
+    message: CoreToSatelliteMessage,
+  ): void {
+    ws.send(JSON.stringify(message));
+  }
+}

package/src/schema.ts

@@ -0,0 +1,27 @@
+import {
+  pgTable,
+  text,
+  jsonb,
+  uuid,
+  timestamp,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Satellites table — each record represents a registered satellite node.
+ * tokenHash stores a bcrypt hash of the pre-shared API token.
+ * The satellite's UUID (id) serves as the clientId for authentication.
+ */
+export const satellites = pgTable("satellites", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: text("name").notNull(),
+  region: text("region").notNull(),
+  /** Key-value tags for flexible grouping and filtering */
+  tags: jsonb("tags").$type<Record<string, string>>().default({}).notNull(),
+  /** Bcrypt hash of the satellite's API token */
+  tokenHash: text("token_hash").notNull(),
+  /** Last heartbeat timestamp — null means never connected */
+  lastHeartbeatAt: timestamp("last_heartbeat_at"),
+  /** Satellite version reported on connect/heartbeat */
+  version: text("version"),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+});