@checkstack/incident-backend 1.2.0 → 1.4.0

package/src/service.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { IncidentService } from "./service";
+import {
+  incidents,
+  incidentSystems,
+  incidentUpdates,
+  incidentLinks,
+} from "./schema";
 
 /**
  * Programmable mock DB that records each `select(...).from(...).where(...)`
@@ -124,3 +130,196 @@ describe("IncidentService.hasActiveIncidentWithSuppression", () => {
     expect(dbHelper.getCallCount()).toBe(1);
   });
 });
+
+describe("IncidentService.getManyEntityStates (plugin-backed entity read)", () => {
+  it("returns {} for an empty id set without querying", async () => {
+    const dbHelper = createProgrammableSelectDb([]);
+    const service = new IncidentService(dbHelper.db as never);
+    expect(await service.getManyEntityStates([])).toEqual({});
+    expect(dbHelper.getCallCount()).toBe(0);
+  });
+
+  it("projects { status, severity, systemIds } from incidents + junction", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      // 1st query: incidents rows for the requested ids.
+      [
+        { id: "inc-1", status: "investigating", severity: "major" },
+        { id: "inc-2", status: "resolved", severity: "minor" },
+      ],
+      // 2nd query: incident_systems junction rows for the present ids.
+      [
+        { incidentId: "inc-1", systemId: "sys-a" },
+        { incidentId: "inc-1", systemId: "sys-b" },
+        { incidentId: "inc-2", systemId: "sys-c" },
+      ],
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    const out = await service.getManyEntityStates(["inc-1", "inc-2", "inc-x"]);
+    expect(out).toEqual({
+      "inc-1": {
+        status: "investigating",
+        severity: "major",
+        systemIds: ["sys-a", "sys-b"],
+      },
+      "inc-2": { status: "resolved", severity: "minor", systemIds: ["sys-c"] },
+    });
+    // Missing ids are omitted (never a null/undefined entry).
+    expect("inc-x" in out).toBe(false);
+  });
+
+  it("returns {} when none of the ids exist (no junction query)", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      // incidents query returns nothing → no second query.
+      [],
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    expect(await service.getManyEntityStates(["ghost"])).toEqual({});
+    expect(dbHelper.getCallCount()).toBe(1);
+  });
+
+  it("yields an empty systemIds array for an incident with no systems", async () => {
+    const dbHelper = createProgrammableSelectDb([
+      [{ id: "inc-1", status: "monitoring", severity: "critical" }],
+      [], // no junction rows
+    ]);
+    const service = new IncidentService(dbHelper.db as never);
+    const out = await service.getManyEntityStates(["inc-1"]);
+    expect(out["inc-1"]).toEqual({
+      status: "monitoring",
+      severity: "critical",
+      systemIds: [],
+    });
+  });
+});
+
+/**
+ * Table-backed fake `db` for the dedup-create path. Models just enough of
+ * the Drizzle surface the service touches (select/insert by TABLE IDENTITY,
+ * `.from`/`.where`/`.limit`, and a serializing `transaction`).
+ *
+ * Crucially `transaction(fn)` models `pg_advisory_xact_lock`: it serializes
+ * callers on the lock key seen in the `tx.execute(...)` SQL, so concurrent
+ * dedup-creates run their find-then-create one-at-a-time — exactly the
+ * guarantee M3 needs. Because the test confines data to a single system,
+ * the (ignored) WHERE clauses don't change which rows match.
+ */
+function createDedupFakeDb() {
+  const store = {
+    incidents: [] as Array<Record<string, unknown>>,
+    incidentSystems: [] as Array<Record<string, unknown>>,
+    incidentUpdates: [] as Array<Record<string, unknown>>,
+    incidentLinks: [] as Array<Record<string, unknown>>,
+  };
+
+  const tableKey = (
+    table: unknown,
+  ): keyof typeof store | undefined => {
+    if (table === incidents) return "incidents";
+    if (table === incidentSystems) return "incidentSystems";
+    if (table === incidentUpdates) return "incidentUpdates";
+    if (table === incidentLinks) return "incidentLinks";
+    return undefined;
+  };
+
+  // Per-key serialization (the xact-lock model).
+  const tails = new Map<string, Promise<unknown>>();
+
+  function buildSelect() {
+    return (projection?: Record<string, unknown>) => {
+      const project = (
+        list: Array<Record<string, unknown>>,
+      ): Array<Record<string, unknown>> => {
+        if (!projection) return list;
+        const keys = Object.keys(projection);
+        return list.map((r) => {
+          const out: Record<string, unknown> = {};
+          for (const k of keys) out[k] = r[k];
+          return out;
+        });
+      };
+      const from = (table: unknown) => {
+        const key = tableKey(table);
+        const rows = key ? project([...store[key]]) : [];
+        const limit = (n: number) => Promise.resolve(rows.slice(0, n));
+        const where = () =>
+          Object.assign(Promise.resolve(rows), { limit });
+        return Object.assign(Promise.resolve(rows), { where, limit });
+      };
+      return { from };
+    };
+  }
+
+  function buildInsert() {
+    return (table: unknown) => ({
+      values: (vals: Record<string, unknown>) => {
+        const key = tableKey(table);
+        if (key) store[key].push({ ...vals });
+        return Promise.resolve();
+      },
+    });
+  }
+
+  const db = {
+    select: buildSelect(),
+    insert: buildInsert(),
+    async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+      // The lock key is embedded in the SQL the helper runs via tx.execute.
+      let lockKey = "default";
+      const tx = {
+        execute: async (sqlObj: unknown) => {
+          // Drizzle sql`` carries the interpolated key in its params; the
+          // helper interpolates exactly one param (the lock key).
+          const params = (sqlObj as { queryChunks?: unknown[] }).queryChunks;
+          const found = JSON.stringify(params ?? sqlObj).match(
+            /incident\.dedupe-open-for-system:[^"\\]+/,
+          );
+          if (found) lockKey = found[0];
+          return { rows: [] };
+        },
+      };
+      // Serialize on the lock key: chain after the current tail.
+      const prior = tails.get(lockKey) ?? Promise.resolve();
+      let resolveTail!: () => void;
+      const myTail = new Promise<void>((r) => (resolveTail = r));
+      tails.set(
+        lockKey,
+        prior.then(() => myTail),
+      );
+      await prior;
+      try {
+        return await fn(tx);
+      } finally {
+        resolveTail();
+      }
+    },
+  };
+
+  return { db: db as unknown, store };
+}
+
+describe("IncidentService.createIncidentDedupedForSystem (M3)", () => {
+  it("two concurrent dedupe creates for one system open exactly ONE incident", async () => {
+    const { db, store } = createDedupFakeDb();
+    const service = new IncidentService(db as never);
+
+    const input = {
+      title: "Down",
+      severity: "critical" as const,
+      systemIds: ["sys-1"],
+      suppressNotifications: false,
+    };
+
+    // Sustained + flapping fire concurrently for the same system. Without
+    // the per-system lock both would find no open incident and both create.
+    const [a, b] = await Promise.all([
+      service.createIncidentDedupedForSystem(input, "sys-1"),
+      service.createIncidentDedupedForSystem(input, "sys-1"),
+    ]);
+
+    // Exactly one incident row created.
+    expect(store.incidents).toHaveLength(1);
+    // One created, one reused — both return the same incident id.
+    expect(a.incident.id).toBe(b.incident.id);
+    expect([a.reused, b.reused].filter(Boolean)).toHaveLength(1);
+  });
+});

package/src/service.ts

@@ -1,5 +1,5 @@
 import { eq, and, inArray, ne } from "drizzle-orm";
-import type { SafeDatabase } from "@checkstack/backend-api";
+import { withXactLock, type SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import {
   incidents,
@@ -17,6 +17,7 @@ import type {
   UpdateIncidentInput,
   AddIncidentUpdateInput,
   IncidentStatus,
+  IncidentSeverity,
 } from "@checkstack/incident-common";
 
 type Db = SafeDatabase<typeof schema>;
@@ -125,6 +126,62 @@ export class IncidentService {
     };
   }
 
+  /**
+   * Batched reactive-state read for the `incident` entity (Model B
+   * plugin-backed `read` accessor). Given incident ids, return the reactive
+   * subset `{ status, severity, systemIds }` for each that exists (missing
+   * ids omitted). Reads the AUTHORITATIVE `incidents` + `incident_systems`
+   * tables — no framework `entity_state` storage. This is the single source
+   * of truth `handle.mutate` snapshots `prev` from and `get`/`getMany`/scope
+   * enrichment route through.
+   */
+  async getManyEntityStates(
+    ids: ReadonlyArray<string>,
+  ): Promise<
+    Record<string, { status: IncidentStatus; severity: IncidentSeverity; systemIds: string[] }>
+  > {
+    if (ids.length === 0) return {};
+
+    const rows = await this.db
+      .select({
+        id: incidents.id,
+        status: incidents.status,
+        severity: incidents.severity,
+      })
+      .from(incidents)
+      .where(inArray(incidents.id, [...ids]));
+    if (rows.length === 0) return {};
+
+    const presentIds = rows.map((r) => r.id);
+    const systemRows = await this.db
+      .select({
+        incidentId: incidentSystems.incidentId,
+        systemId: incidentSystems.systemId,
+      })
+      .from(incidentSystems)
+      .where(inArray(incidentSystems.incidentId, presentIds));
+
+    const systemsByIncident = new Map<string, string[]>();
+    for (const r of systemRows) {
+      const list = systemsByIncident.get(r.incidentId);
+      if (list) list.push(r.systemId);
+      else systemsByIncident.set(r.incidentId, [r.systemId]);
+    }
+
+    const out: Record<
+      string,
+      { status: IncidentStatus; severity: IncidentSeverity; systemIds: string[] }
+    > = {};
+    for (const row of rows) {
+      out[row.id] = {
+        status: row.status,
+        severity: row.severity,
+        systemIds: systemsByIncident.get(row.id) ?? [],
+      };
+    }
+    return out;
+  }
+
   /**
    * Get active incidents for a system
    */
@@ -165,13 +222,18 @@ export class IncidentService {
   }
 
   /**
-   * Create a new incident
+   * Create a new incident.
+   *
+   * `id` may be supplied by the caller so the reactive `incident` entity can
+   * be keyed on a known id BEFORE the insert runs (the create's `prev`
+   * snapshot must read the not-yet-existing row as absent — see §10.1). When
+   * omitted, a fresh id is generated. The id is server-owned either way.
    */
   async createIncident(
     input: CreateIncidentInput,
     userId?: string,
+    id: string = generateId(),
   ): Promise<IncidentWithSystems> {
-    const id = generateId();
 
     await this.db.insert(incidents).values({
       id,
@@ -407,4 +469,86 @@ export class IncidentService {
 
     return !!match;
   }
+
+  /**
+   * Find a single OPEN (not-resolved) incident affecting `systemId`, if
+   * any. Returns the incident with its systems, mirroring the old
+   * auto-incident `findActiveAutoIncident(systemId)` dedup semantic. Used
+   * by `incident.create`'s opt-in `dedupe_open_for_system` flag so a
+   * second trigger for an already-incidented system reuses the open
+   * incident rather than opening a duplicate.
+   */
+  async findActiveIncidentForSystem(
+    systemId: string,
+  ): Promise<IncidentWithSystems | undefined> {
+    const systemIncidents = await this.db
+      .select({ incidentId: incidentSystems.incidentId })
+      .from(incidentSystems)
+      .where(eq(incidentSystems.systemId, systemId));
+
+    const ids = systemIncidents.map((r) => r.incidentId);
+    if (ids.length === 0) return undefined;
+
+    const [match] = await this.db
+      .select({ id: incidents.id })
+      .from(incidents)
+      .where(and(inArray(incidents.id, ids), ne(incidents.status, "resolved")))
+      .limit(1);
+
+    if (!match) return undefined;
+    return this.getIncident(match.id);
+  }
+
+  /**
+   * Dedup-aware create for a single system, used by the `incident.create`
+   * automation action when `dedupe_open_for_system` is set. Serializes the
+   * check-then-create per system with a transaction-scoped advisory lock so
+   * two concurrent triggers for the same system (e.g. sustained + flapping)
+   * can't both observe "no open incident" and both create one. The critical
+   * section is short (a find + an insert), so a transaction-scoped lock is
+   * the right primitive (it auto-releases at COMMIT, no leak possible).
+   *
+   * Returns `{ incident, reused }` — `reused` is true when an already-open
+   * incident for the system was found and returned instead of creating.
+   */
+  async createIncidentDedupedForSystem(
+    input: CreateIncidentInput,
+    dedupeSystemId: string,
+    userId?: string,
+    newId?: string,
+    /**
+     * Optional create wrapper (§10.1, 6(a)). When the dedup decides to CREATE,
+     * the actual create runs through this wrapper INSIDE the advisory lock, so
+     * the reactive `incident` entity write (which snapshots `prev` before the
+     * insert) is serialized with the dedup check. The wrapper receives the
+     * bound create thunk and MUST call it exactly once, returning its result.
+     * Defaults to calling the create directly (non-reactive).
+     */
+    onCreate: (
+      create: () => Promise<IncidentWithSystems>,
+    ) => Promise<IncidentWithSystems> = (create) => create(),
+  ): Promise<{ incident: IncidentWithSystems; reused: boolean }> {
+    return withXactLock({
+      db: this.db,
+      key: `incident.dedupe-open-for-system:${dedupeSystemId}`,
+      // The find + create run on `this.db` (the pool), NOT on `tx`. That is
+      // safe here because `pg_advisory_xact_lock` BLOCKS every other holder
+      // of this key until this transaction commits: a racing caller waits
+      // at lock-acquire, so its find can't observe "no open incident" until
+      // ours has already committed the insert. The critical section is thus
+      // serialized by the lock window even though it doesn't ride `tx`.
+      fn: async () => {
+        const existing = await this.findActiveIncidentForSystem(dedupeSystemId);
+        if (existing) {
+          return { incident: existing, reused: true };
+        }
+        // Create through the caller's wrapper (reactive entity write) so the
+        // `incident.created` emit is serialized inside the dedup lock.
+        const incident = await onCreate(() =>
+          this.createIncident(input, userId, newId),
+        );
+        return { incident, reused: false };
+      },
+    });
+  }
 }

package/tsconfig.json

@@ -7,6 +7,12 @@
     {
       "path": "../auth-common"
     },
+    {
+      "path": "../automation-backend"
+    },
+    {
+      "path": "../automation-common"
+    },
     {
       "path": "../backend-api"
     },