@checkstack/automation-backend 0.2.0 → 0.3.0

package/src/dispatch/window-gate.test.ts

@@ -0,0 +1,513 @@
+import { describe, it, expect } from "bun:test";
+import { SYSTEM_ACTOR } from "@checkstack/common";
+import {
+  AutomationDefinitionSchema,
+  type Automation,
+  type Trigger,
+} from "@checkstack/automation-common";
+
+import type { AutomationStore } from "../automation-store";
+import { handleTriggerFiring } from "./trigger-subscriber";
+import { makeDispatchDeps, makeRecordingAction, testPlugin } from "./test-fixtures";
+import { createActionRegistry } from "../action-registry";
+import type { LoadedAutomation } from "./types";
+
+const EVENT = "healthcheck.system_health_changed";
+
+function buildAutomation(opts: {
+  id?: string;
+  trigger: Partial<Trigger> & { event: string };
+}): Automation {
+  const definition = AutomationDefinitionSchema.parse({
+    name: "Window test",
+    triggers: [opts.trigger],
+    conditions: [],
+    actions: [{ action: "test.record", config: { value: "fired" } }],
+    mode: "parallel",
+    max_runs: 100,
+  });
+  return {
+    id: opts.id ?? "auto-1",
+    name: "Window test",
+    status: "enabled",
+    definition,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function makeAutomationStore(automations: Automation[]): AutomationStore {
+  const byId = new Map(automations.map((a) => [a.id, a]));
+  const loaded = (a: Automation): LoadedAutomation => ({
+    id: a.id,
+    name: a.name,
+    status: a.status,
+    definition: a.definition,
+  });
+  return {
+    create: async () => {
+      throw new Error("not used");
+    },
+    update: async () => {
+      throw new Error("not used");
+    },
+    delete: async () => {},
+    toggle: async () => {
+      throw new Error("not used");
+    },
+    getById: async (id) => byId.get(id),
+    list: async () => ({ items: [...byId.values()], total: byId.size }),
+    listGroups: async () => [],
+    findEnabledByTriggerEvent: async (eventId) =>
+      [...byId.values()]
+        .filter(
+          (a) =>
+            a.status === "enabled" &&
+            a.definition.triggers.some((t) => t.event === eventId),
+        )
+        .map(loaded),
+    listEnabled: async () =>
+      [...byId.values()].filter((a) => a.status === "enabled").map(loaded),
+  };
+}
+
+function setup() {
+  const actionsReg = createActionRegistry();
+  const rec = makeRecordingAction();
+  actionsReg.register(rec.definition, testPlugin);
+  const { deps, runs, windows } = makeDispatchDeps({ actions: actionsReg });
+  return { deps, runs, windows, rec };
+}
+
+/** Fire the trigger N times for one system; return how many runs started. */
+async function fireN(opts: {
+  deps: ReturnType<typeof setup>["deps"];
+  store: AutomationStore;
+  runs: ReturnType<typeof setup>["runs"];
+  systemId: string;
+  newStatus: string;
+  times: number;
+}): Promise<number> {
+  const before = opts.runs.runs.size;
+  for (let i = 0; i < opts.times; i++) {
+    await handleTriggerFiring({
+      deps: opts.deps,
+      automationStore: opts.store,
+      qualifiedEventId: EVENT,
+      triggerPayload: {
+        systemId: opts.systemId,
+        newStatus: opts.newStatus,
+        previousStatus: "healthy",
+      },
+      actor: SYSTEM_ACTOR,
+      contextKey: opts.systemId,
+    });
+  }
+  return opts.runs.runs.size - before;
+}
+
+describe("windowed-count trigger gate", () => {
+  it("does not fire below the threshold, then fires once it is reached", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "flapping",
+          event: EVENT,
+          window: { count: 3, minutes: 60, refire: "every" },
+        },
+      }),
+    ]);
+
+    // 2 occurrences ⇒ no run.
+    let started = await fireN({
+      deps,
+      store,
+      runs,
+      systemId: "sys-1",
+      newStatus: "unhealthy",
+      times: 2,
+    });
+    expect(started).toBe(0);
+
+    // 3rd occurrence crosses ⇒ run starts.
+    started = await fireN({
+      deps,
+      store,
+      runs,
+      systemId: "sys-1",
+      newStatus: "unhealthy",
+      times: 1,
+    });
+    expect(started).toBe(1);
+  });
+
+  it("only counts POST-FILTER occurrences (filter gates before the window)", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "flapping",
+          event: EVENT,
+          filter: 'trigger.payload.newStatus != "healthy"',
+          window: { count: 2, minutes: 60, refire: "once" },
+        },
+      }),
+    ]);
+
+    // Healthy transitions don't pass the filter ⇒ not counted.
+    let started = await fireN({
+      deps,
+      store,
+      runs,
+      systemId: "sys-1",
+      newStatus: "healthy",
+      times: 5,
+    });
+    expect(started).toBe(0);
+
+    // Two unhealthy transitions ⇒ edge fires once.
+    started = await fireN({
+      deps,
+      store,
+      runs,
+      systemId: "sys-1",
+      newStatus: "unhealthy",
+      times: 2,
+    });
+    expect(started).toBe(1);
+  });
+
+  it("`every` re-fires on every occurrence past the threshold; `once` fires only on the edge", async () => {
+    // every
+    {
+      const { deps, runs } = setup();
+      const store = makeAutomationStore([
+        buildAutomation({
+          trigger: {
+            id: "f",
+            event: EVENT,
+            window: { count: 2, minutes: 60, refire: "every" },
+          },
+        }),
+      ]);
+      const started = await fireN({
+        deps,
+        store,
+        runs,
+        systemId: "sys-1",
+        newStatus: "unhealthy",
+        times: 4,
+      });
+      // occurrences 2,3,4 all fire (>= 2) ⇒ 3 runs.
+      expect(started).toBe(3);
+    }
+    // once
+    {
+      const { deps, runs } = setup();
+      const store = makeAutomationStore([
+        buildAutomation({
+          trigger: {
+            id: "f",
+            event: EVENT,
+            window: { count: 2, minutes: 60, refire: "once" },
+          },
+        }),
+      ]);
+      const started = await fireN({
+        deps,
+        store,
+        runs,
+        systemId: "sys-1",
+        newStatus: "unhealthy",
+        times: 4,
+      });
+      // only occurrence 2 (=== 2) fires ⇒ 1 run.
+      expect(started).toBe(1);
+    }
+  });
+
+  it("windows are isolated per context key (per system)", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          window: { count: 3, minutes: 60, refire: "once" },
+        },
+      }),
+    ]);
+
+    await fireN({ deps, store, runs, systemId: "sys-1", newStatus: "unhealthy", times: 2 });
+    await fireN({ deps, store, runs, systemId: "sys-2", newStatus: "unhealthy", times: 2 });
+    // Neither system has reached 3 yet.
+    expect(runs.runs.size).toBe(0);
+
+    // sys-1 reaches 3 ⇒ fires; sys-2 still at 2.
+    const startedSys1 = await fireN({
+      deps,
+      store,
+      runs,
+      systemId: "sys-1",
+      newStatus: "unhealthy",
+      times: 1,
+    });
+    expect(startedSys1).toBe(1);
+  });
+});
+
+/**
+ * Fire the trigger `times` with an arbitrary payload + contextKey; returns how
+ * many runs started. Lets partitionBy tests vary a payload field (e.g.
+ * severity) independently of the built-in contextKey (systemId).
+ */
+async function firePayloads(opts: {
+  deps: ReturnType<typeof setup>["deps"];
+  store: AutomationStore;
+  runs: ReturnType<typeof setup>["runs"];
+  payload: Record<string, unknown>;
+  contextKey: string | null;
+  times: number;
+}): Promise<number> {
+  const before = opts.runs.runs.size;
+  for (let i = 0; i < opts.times; i++) {
+    await handleTriggerFiring({
+      deps: opts.deps,
+      automationStore: opts.store,
+      qualifiedEventId: EVENT,
+      triggerPayload: opts.payload,
+      actor: SYSTEM_ACTOR,
+      contextKey: opts.contextKey,
+    });
+  }
+  return opts.runs.runs.size - before;
+}
+
+describe("windowed-count trigger gate — partitionBy", () => {
+  it("partitions the count by the evaluated expression value", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          window: {
+            count: 2,
+            minutes: 60,
+            refire: "once",
+            partitionBy: "trigger.payload.severity",
+          },
+        },
+      }),
+    ]);
+
+    // Same system (contextKey sys-1), different severities ⇒ independent windows.
+    // Two `high` reach the threshold and fire; one `low` does not.
+    let started = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "high" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(started).toBe(0); // high count 1
+
+    started = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "low" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(started).toBe(0); // low count 1 (separate partition)
+
+    started = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "high" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(started).toBe(1); // high count 2 ⇒ fires on its own partition
+  });
+
+  it("keeps two distinct evaluated values in independent windows", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          window: {
+            count: 3,
+            minutes: 60,
+            refire: "once",
+            partitionBy: "trigger.payload.severity",
+          },
+        },
+      }),
+    ]);
+
+    await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "high" },
+      contextKey: "sys-1",
+      times: 2,
+    });
+    await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "low" },
+      contextKey: "sys-1",
+      times: 2,
+    });
+    // Neither partition has reached 3 yet (2 each).
+    expect(runs.runs.size).toBe(0);
+
+    const started = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1", severity: "high" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(started).toBe(1); // `high` reaches 3
+  });
+
+  it("omitted partitionBy ⇒ built-in contextKey (unchanged) — composite split by system", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          window: { count: 2, minutes: 60, refire: "once" },
+        },
+      }),
+    ]);
+
+    // Two systems, two events each: each is its own partition (the contextKey),
+    // so each fires once on its 2nd event.
+    await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    const startedSys2First = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-2" },
+      contextKey: "sys-2",
+      times: 1,
+    });
+    expect(startedSys2First).toBe(0); // each system at count 1
+
+    const startedSys1Second = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(startedSys1Second).toBe(1); // sys-1 reaches 2
+  });
+
+  it("partitionBy evaluating to empty/undefined falls back to the built-in contextKey", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          // `missing` is not in the payload ⇒ evaluates to undefined ⇒ fall
+          // back to contextKey (systemId). So per-system counting applies.
+          window: {
+            count: 2,
+            minutes: 60,
+            refire: "once",
+            partitionBy: "trigger.payload.missing",
+          },
+        },
+      }),
+    ]);
+
+    await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    // A different system must NOT share the bucket (fallback is per-context, not global).
+    const startedSys2 = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-2" },
+      contextKey: "sys-2",
+      times: 1,
+    });
+    expect(startedSys2).toBe(0); // sys-2 at count 1 (own bucket)
+
+    const startedSys1 = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(startedSys1).toBe(1); // sys-1 reaches 2 in its own (fallback) bucket
+  });
+
+  it("partitionBy that throws on eval falls back to the built-in contextKey (fail-open)", async () => {
+    const { deps, runs } = setup();
+    const store = makeAutomationStore([
+      buildAutomation({
+        trigger: {
+          id: "f",
+          event: EVENT,
+          // Unparseable expression ⇒ eval throws ⇒ fall back to contextKey.
+          window: {
+            count: 2,
+            minutes: 60,
+            refire: "once",
+            partitionBy: "trigger.payload.(((",
+          },
+        },
+      }),
+    ]);
+
+    await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    const startedSys1 = await firePayloads({
+      deps,
+      store,
+      runs,
+      payload: { systemId: "sys-1" },
+      contextKey: "sys-1",
+      times: 1,
+    });
+    expect(startedSys1).toBe(1); // counted per system via fallback
+  });
+});

package/src/dispatch/window-store.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "bun:test";
+
+import { createInMemoryWindowStore } from "./test-fixtures";
+import type { WindowRefire } from "./types";
+
+const AUTO = "auto-1";
+const TRIGGER = "flapping";
+const EVENT = "healthcheck.system_health_changed";
+
+function at(baseMs: number, offsetMinutes: number): Date {
+  return new Date(baseMs + offsetMinutes * 60_000);
+}
+
+function record(opts: {
+  store: ReturnType<typeof createInMemoryWindowStore>["store"];
+  occurredAt: Date;
+  windowMinutes?: number;
+  threshold?: number;
+  refire?: WindowRefire;
+  contextKey?: string | null;
+  automationId?: string;
+  triggerId?: string;
+  eventId?: string;
+}): Promise<boolean> {
+  return opts.store.recordAndCount({
+    automationId: opts.automationId ?? AUTO,
+    triggerId: opts.triggerId ?? TRIGGER,
+    eventId: opts.eventId ?? EVENT,
+    contextKey: opts.contextKey ?? "sys-1",
+    occurredAt: opts.occurredAt,
+    windowMinutes: opts.windowMinutes ?? 60,
+    threshold: opts.threshold ?? 3,
+    refire: opts.refire ?? "every",
+  });
+}
+
+describe("WindowStore.recordAndCount — counting within the window", () => {
+  it("counts occurrences within the trailing window (inclusive of the new row)", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    // 3 occurrences inside a 60-minute window; `every` threshold 3.
+    expect(await record({ store, occurredAt: at(base, 0) })).toBe(false); // count 1
+    expect(await record({ store, occurredAt: at(base, 10) })).toBe(false); // count 2
+    expect(await record({ store, occurredAt: at(base, 20) })).toBe(true); // count 3 ⇒ fire
+    expect(await record({ store, occurredAt: at(base, 30) })).toBe(true); // count 4, every ⇒ still fires
+  });
+
+  it("`once` fires only on the crossing edge", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    expect(
+      await record({ store, occurredAt: at(base, 0), refire: "once" }),
+    ).toBe(false); // count 1
+    expect(
+      await record({ store, occurredAt: at(base, 10), refire: "once" }),
+    ).toBe(false); // count 2
+    expect(
+      await record({ store, occurredAt: at(base, 20), refire: "once" }),
+    ).toBe(true); // count 3 === threshold ⇒ fire (edge)
+    expect(
+      await record({ store, occurredAt: at(base, 30), refire: "once" }),
+    ).toBe(false); // count 4 > threshold ⇒ suppressed
+  });
+
+  it("`once` re-arms as old rows age out and the count re-crosses", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    const w = 10; // 10-minute window
+    // First burst: 3 rows at t=0,1,2 inside the 10-min window ⇒ edge at the 3rd.
+    await record({ store, occurredAt: at(base, 0), windowMinutes: w, refire: "once" });
+    await record({ store, occurredAt: at(base, 1), windowMinutes: w, refire: "once" });
+    expect(
+      await record({ store, occurredAt: at(base, 2), windowMinutes: w, refire: "once" }),
+    ).toBe(true);
+    // 4th still inside ⇒ suppressed (count 4 > threshold).
+    expect(
+      await record({ store, occurredAt: at(base, 3), windowMinutes: w, refire: "once" }),
+    ).toBe(false);
+    // Second burst much later (t=100..102): the t=0..3 rows are all >10 min
+    // old, so the window holds only the new rows. The 3rd new row re-crosses
+    // the threshold edge.
+    await record({ store, occurredAt: at(base, 100), windowMinutes: w, refire: "once" }); // count 1
+    await record({ store, occurredAt: at(base, 101), windowMinutes: w, refire: "once" }); // count 2
+    expect(
+      await record({ store, occurredAt: at(base, 102), windowMinutes: w, refire: "once" }),
+    ).toBe(true); // count 3 ⇒ edge again
+  });
+
+  it("slides: occurrences older than the window do not count", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    const w = 10;
+    // 2 occurrences at t=0,1; then a gap past the window.
+    await record({ store, occurredAt: at(base, 0), windowMinutes: w, threshold: 3 });
+    await record({ store, occurredAt: at(base, 1), windowMinutes: w, threshold: 3 });
+    // t=20 is >10 min after t=0,1 — those have aged out; count is just 1.
+    expect(
+      await record({ store, occurredAt: at(base, 20), windowMinutes: w, threshold: 3 }),
+    ).toBe(false);
+  });
+});
+
+describe("WindowStore — key isolation", () => {
+  it("counts are independent per (automation, contextKey, eventId)", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    // Same automation+trigger, two systems: each needs its own 3 to fire.
+    await record({ store, occurredAt: at(base, 0), contextKey: "sys-1" });
+    await record({ store, occurredAt: at(base, 1), contextKey: "sys-1" });
+    await record({ store, occurredAt: at(base, 2), contextKey: "sys-2" });
+    // sys-1 reaches 3 first.
+    expect(
+      await record({ store, occurredAt: at(base, 3), contextKey: "sys-1" }),
+    ).toBe(true);
+    // sys-2 still at 2.
+    expect(
+      await record({ store, occurredAt: at(base, 4), contextKey: "sys-2" }),
+    ).toBe(false);
+
+    // A different automation watching the same event/system has its own count.
+    expect(
+      await record({
+        store,
+        occurredAt: at(base, 5),
+        contextKey: "sys-1",
+        automationId: "auto-2",
+      }),
+    ).toBe(false); // count 1 for auto-2/sys-1
+  });
+
+  it("a null contextKey forms its own per-automation window", async () => {
+    const { store } = createInMemoryWindowStore();
+    const base = Date.now();
+    await record({ store, occurredAt: at(base, 0), contextKey: null });
+    await record({ store, occurredAt: at(base, 1), contextKey: null });
+    expect(
+      await record({ store, occurredAt: at(base, 2), contextKey: null }),
+    ).toBe(true);
+  });
+});
+
+describe("WindowStore — pruning + lifecycle", () => {
+  it("sweepExpired deletes only rows older than the cutoff", async () => {
+    const { store, events } = createInMemoryWindowStore();
+    const base = Date.now();
+    await record({ store, occurredAt: at(base, -120) }); // 2h ago
+    await record({ store, occurredAt: at(base, 0) }); // now
+    await store.sweepExpired(at(base, -60)); // cutoff 1h ago
+    expect(events).toHaveLength(1);
+    expect(events[0]!.occurredAt.getTime()).toBe(at(base, 0).getTime());
+  });
+
+  it("deleteForAutomation drops only that automation's rows", async () => {
+    const { store, events } = createInMemoryWindowStore();
+    const base = Date.now();
+    await record({ store, occurredAt: at(base, 0), automationId: "auto-1" });
+    await record({ store, occurredAt: at(base, 1), automationId: "auto-2" });
+    await store.deleteForAutomation("auto-1");
+    expect(events).toHaveLength(1);
+    expect(events[0]!.automationId).toBe("auto-2");
+  });
+});