@checkstack/satellite-backend 0.2.0

package/src/service.test.ts

@@ -0,0 +1,292 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { SatelliteService } from "./service";
+import { OFFLINE_THRESHOLD_MS } from "@checkstack/satellite-common";
+
+// Cast helper - creates a mock DB that satisfies the service's type requirements
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- test utility for creating mock DB chains
+type MockDb = Record<string, unknown>;
+
+function createServiceWithMockDb(overrides?: {
+  selectResult?: unknown[];
+  insertResult?: unknown[];
+}) {
+  const selectResult = overrides?.selectResult ?? [];
+  const insertResult = overrides?.insertResult ?? [];
+
+  const db = {
+    select: mock(() => ({
+      from: mock(() => ({
+        where: mock(() => Promise.resolve(selectResult)),
+      })),
+    })),
+    insert: mock(() => ({
+      values: mock(() => ({
+        returning: mock(() => Promise.resolve(insertResult)),
+      })),
+    })),
+    update: mock(() => ({
+      set: mock(() => ({
+        where: mock(() => Promise.resolve()),
+      })),
+    })),
+    delete: mock(() => ({
+      where: mock(() => Promise.resolve()),
+    })),
+  } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+  return { service: new SatelliteService(db), db };
+}
+
+/**
+ * Unit tests for SatelliteService.
+ * Uses lightweight mock DB focused on testing business logic.
+ */
+describe("SatelliteService", () => {
+  describe("createSatellite", () => {
+    it("should generate a token with the csat_ prefix", async () => {
+      const mockRow = {
+        id: "test-uuid-1",
+        name: "EU West",
+        region: "eu-west-1",
+        tags: { provider: "aws" },
+        tokenHash: "hashed",
+        lastHeartbeatAt: null,
+        version: null,
+        createdAt: new Date(),
+      };
+
+      const { service } = createServiceWithMockDb({
+        insertResult: [mockRow],
+      });
+
+      const result = await service.createSatellite({
+        name: "EU West",
+        region: "eu-west-1",
+        tags: { provider: "aws" },
+      });
+
+      expect(result.plaintextToken).toMatch(/^csat_/);
+      expect(result.plaintextToken.length).toBeGreaterThan(10);
+      expect(result.satellite.name).toBe("EU West");
+      expect(result.satellite.region).toBe("eu-west-1");
+      expect(result.satellite.status).toBe("offline");
+    });
+
+    it("should generate unique tokens for different satellites", async () => {
+      const makeRow = (name: string) => ({
+        id: `uuid-${name}`,
+        name,
+        region: "us-east-1",
+        tags: {},
+        tokenHash: "hashed",
+        lastHeartbeatAt: null,
+        version: null,
+        createdAt: new Date(),
+      });
+
+      let callCount = 0;
+      const db = {
+        select: mock(() => ({
+          from: mock(() => ({
+            where: mock(() => Promise.resolve([])),
+          })),
+        })),
+        insert: mock(() => ({
+          values: mock(() => ({
+            returning: mock(() => {
+              callCount++;
+              return Promise.resolve([
+                makeRow(callCount === 1 ? "Sat1" : "Sat2"),
+              ]);
+            }),
+          })),
+        })),
+        update: mock(() => ({
+          set: mock(() => ({
+            where: mock(() => Promise.resolve()),
+          })),
+        })),
+        delete: mock(() => ({
+          where: mock(() => Promise.resolve()),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+
+      const result1 = await service.createSatellite({
+        name: "Sat1",
+        region: "us-east-1",
+        tags: {},
+      });
+      const result2 = await service.createSatellite({
+        name: "Sat2",
+        region: "us-east-1",
+        tags: {},
+      });
+
+      expect(result1.plaintextToken).not.toBe(result2.plaintextToken);
+    });
+  });
+
+  describe("validateToken", () => {
+    it("should validate a correct clientId + token pair", async () => {
+      const testToken = "csat_test-token-for-validation";
+      const hash = await Bun.password.hash(testToken, {
+        algorithm: "bcrypt",
+        cost: 10,
+      });
+
+      const { service } = createServiceWithMockDb({
+        selectResult: [
+          {
+            id: "sat-id-1",
+            name: "Test Sat",
+            region: "us-east-1",
+            tags: {},
+            tokenHash: hash,
+            lastHeartbeatAt: null,
+            version: null,
+            createdAt: new Date(),
+          },
+        ],
+      });
+
+      const result = await service.validateToken({
+        clientId: "sat-id-1",
+        token: testToken,
+      });
+
+      expect(result).toBeDefined();
+      expect(result!.id).toBe("sat-id-1");
+      expect(result!.name).toBe("Test Sat");
+    });
+
+    it("should reject an invalid token for a valid clientId", async () => {
+      const hash = await Bun.password.hash("csat_correct-token", {
+        algorithm: "bcrypt",
+        cost: 10,
+      });
+
+      const { service } = createServiceWithMockDb({
+        selectResult: [
+          {
+            id: "sat-id-2",
+            name: "Sat",
+            region: "eu",
+            tags: {},
+            tokenHash: hash,
+            lastHeartbeatAt: null,
+            version: null,
+            createdAt: new Date(),
+          },
+        ],
+      });
+
+      const result = await service.validateToken({
+        clientId: "sat-id-2",
+        token: "csat_wrong-token",
+      });
+
+      expect(result).toBeUndefined();
+    });
+
+    it("should reject a non-existent clientId", async () => {
+      const { service } = createServiceWithMockDb({
+        selectResult: [],
+      });
+
+      const result = await service.validateToken({
+        clientId: "non-existent",
+        token: "csat_any-token",
+      });
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("listSatellites", () => {
+    it("should compute online status from heartbeat timestamp", async () => {
+      const now = new Date();
+      const recentHeartbeat = new Date(now.getTime() - 10_000);
+      const staleHeartbeat = new Date(
+        now.getTime() - OFFLINE_THRESHOLD_MS - 1000,
+      );
+
+      const db = {
+        select: mock(() => ({
+          from: mock(() =>
+            Promise.resolve([
+              {
+                id: "online-sat",
+                name: "Online",
+                region: "us-east-1",
+                tags: {},
+                tokenHash: "hash",
+                lastHeartbeatAt: recentHeartbeat,
+                version: "1.0.0",
+                createdAt: now,
+              },
+              {
+                id: "offline-sat",
+                name: "Offline",
+                region: "eu-west-1",
+                tags: {},
+                tokenHash: "hash",
+                lastHeartbeatAt: staleHeartbeat,
+                version: "1.0.0",
+                createdAt: now,
+              },
+              {
+                id: "never-connected",
+                name: "Never",
+                region: "ap-south-1",
+                tags: {},
+                tokenHash: "hash",
+                lastHeartbeatAt: null,
+                version: null,
+                createdAt: now,
+              },
+            ]),
+          ),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const list = await service.listSatellites();
+
+      expect(list).toHaveLength(3);
+      expect(list[0].status).toBe("online");
+      expect(list[1].status).toBe("offline");
+      expect(list[2].status).toBe("offline");
+    });
+  });
+
+  describe("getOnlineSatelliteIds", () => {
+    it("should only return IDs of satellites with recent heartbeats", async () => {
+      const now = new Date();
+      const recentHeartbeat = new Date(now.getTime() - 5000);
+
+      const db = {
+        select: mock(() => ({
+          from: mock(() =>
+            Promise.resolve([
+              { id: "online-1", lastHeartbeatAt: recentHeartbeat },
+              { id: "offline-1", lastHeartbeatAt: null },
+              {
+                id: "offline-2",
+                lastHeartbeatAt: new Date(
+                  now.getTime() - OFFLINE_THRESHOLD_MS - 1000,
+                ),
+              },
+            ]),
+          ),
+        })),
+      } as unknown as ConstructorParameters<typeof SatelliteService>[0];
+
+      const service = new SatelliteService(db);
+      const ids = await service.getOnlineSatelliteIds();
+
+      expect(ids).toEqual(["online-1"]);
+    });
+  });
+});

package/src/service.ts

@@ -0,0 +1,171 @@
+import { eq } 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";
+
+// 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.
+ */
+export class SatelliteService {
+  constructor(private db: Db) {}
+
+  /**
+   * Create a new satellite.
+   * Generates a cryptographically random token, stores a bcrypt hash,
+   * and returns the plaintext token (shown once to the user).
+   */
+  async createSatellite(props: {
+    name: string;
+    region: string;
+    tags: Record<string, string>;
+  }): Promise<{ satellite: SatelliteWithStatus; plaintextToken: string }> {
+    const { name, region, tags } = props;
+
+    // Generate a cryptographically random token with a recognizable prefix
+    const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+    const tokenBody = Buffer.from(randomBytes).toString("base64url");
+    const plaintextToken = `csat_${tokenBody}`;
+
+    // Hash the token using bcrypt
+    const tokenHash = await Bun.password.hash(plaintextToken, {
+      algorithm: "bcrypt",
+      cost: 10,
+    });
+
+    const [row] = await this.db
+      .insert(satellites)
+      .values({
+        name,
+        region,
+        tags,
+        tokenHash,
+      })
+      .returning();
+
+    const satellite: SatelliteWithStatus = {
+      id: row.id,
+      name: row.name,
+      region: row.region,
+      tags: row.tags,
+      lastHeartbeatAt: row.lastHeartbeatAt ?? undefined,
+      version: row.version ?? undefined,
+      createdAt: row.createdAt,
+      status: "offline",
+    };
+
+    return { satellite, plaintextToken };
+  }
+
+  /**
+   * Delete a satellite by ID.
+   */
+  async deleteSatellite(id: string): Promise<void> {
+    await this.db.delete(satellites).where(eq(satellites.id, id));
+  }
+
+  /**
+   * List all satellites with computed online/offline status.
+   */
+  async listSatellites(): Promise<SatelliteWithStatus[]> {
+    const rows = await this.db.select().from(satellites);
+    return rows.map((row) => this.toSatelliteWithStatus(row));
+  }
+
+  /**
+   * Get a single satellite by ID.
+   */
+  async getSatellite(id: string): Promise<SatelliteWithStatus | undefined> {
+    const [row] = await this.db
+      .select()
+      .from(satellites)
+      .where(eq(satellites.id, id));
+    return row ? this.toSatelliteWithStatus(row) : undefined;
+  }
+
+  /**
+   * Validate a satellite token using clientId for O(1) lookup.
+   * Returns the satellite record if valid, undefined otherwise.
+   */
+  async validateToken(props: {
+    clientId: string;
+    token: string;
+  }): Promise<SatelliteWithStatus | undefined> {
+    const { clientId, token } = props;
+
+    const [row] = await this.db
+      .select()
+      .from(satellites)
+      .where(eq(satellites.id, clientId));
+
+    if (!row) return undefined;
+
+    const isValid = await Bun.password.verify(token, row.tokenHash);
+    if (!isValid) return undefined;
+
+    return this.toSatelliteWithStatus(row);
+  }
+
+  /**
+   * Update heartbeat timestamp and version for a satellite.
+   */
+  async updateHeartbeat(
+    id: string,
+    props: { version?: string },
+  ): Promise<void> {
+    await this.db
+      .update(satellites)
+      .set({
+        lastHeartbeatAt: new Date(),
+        version: props.version ?? undefined,
+      })
+      .where(eq(satellites.id, id));
+  }
+
+  /**
+   * Get IDs of all satellites currently considered online.
+   */
+  async getOnlineSatelliteIds(): Promise<string[]> {
+    const rows = await this.db
+      .select({ id: satellites.id, lastHeartbeatAt: satellites.lastHeartbeatAt })
+      .from(satellites);
+
+    return rows
+      .filter((row) => computeStatus(row.lastHeartbeatAt) === "online")
+      .map((row) => row.id);
+  }
+
+  /**
+   * Map a database row to SatelliteWithStatus (excludes tokenHash).
+   */
+  private toSatelliteWithStatus(
+    row: typeof satellites.$inferSelect,
+  ): SatelliteWithStatus {
+    return {
+      id: row.id,
+      name: row.name,
+      region: row.region,
+      tags: row.tags,
+      lastHeartbeatAt: row.lastHeartbeatAt ?? undefined,
+      version: row.version ?? undefined,
+      createdAt: row.createdAt,
+      status: computeStatus(row.lastHeartbeatAt),
+    };
+  }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}