@checkstack/cache-utils 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# @checkstack/cache-utils
+
+## 0.2.0
+
+### Minor Changes
+
+- 8d1ef12: ## Per-entity caching with single-flight + safe invalidation across the dashboard hot paths
+
+  ### `@checkstack/cache-api`
+
+  - **Breaking** for backend implementors: `CacheProvider` now requires `deleteByPrefix(prefix: string): Promise<number>` for family-level invalidation. The in-memory provider implements it; downstream providers (Redis, etc.) must add it before upgrading.
+  - `createScopedCache` forwards `deleteByPrefix` and keeps prefixes scoped to the calling plugin.
+
+  ### `@checkstack/cache-utils` (new package)
+
+  High-level read-through caching helpers built on `CacheProvider`:
+
+  - `createCachedScope({ cacheManager, pluginId })` returns a scope with `wrap`, `wrapMany`, `invalidate`, and `invalidatePrefix`.
+  - **Single-flight**: concurrent cache misses for the same key share one loader.
+  - **Per-entity bulk caching** via `wrapMany` so list/bulk RPCs cache by id rather than by the full input shape — overlapping callers share entries and invalidation stays exact.
+  - **Race-safe invalidation** via per-key epoch counters: a loader started before a mutation cannot repopulate the cache with stale data after the mutation invalidates it. The mutation invariant is `db.write → cache.invalidate (await) → signals.emit`.
+  - Cache failures fall through to the loader so a cache outage cannot break reads.
+
+  ### `@checkstack/backend`
+
+  - The internal null `CacheProvider` (used when no cache backend is configured) now implements the new `deleteByPrefix` method as a no-op. Patch bump only — no behavior change for existing callers.
+
+  ### `@checkstack/healthcheck-backend`
+
+  - `getSystemHealthStatus` and `getBulkSystemHealthStatus` now read through a per-system cache (`healthcheck:status:<systemId>`), eliminating N database queries per dashboard refresh for unchanged systems.
+  - Mutation paths (configuration CRUD, system associations, satellite ingest, queue-driven check runs, system/satellite removal hooks) invalidate affected keys before broadcasting their signals so frontend refetches always observe fresh data.
+
+  ### `@checkstack/incident-backend`
+
+  - `listIncidents`, `getIncident`, `getIncidentsForSystem`, and `getBulkIncidentsForSystems` now read through a scoped cache:
+    - per-incident at `incident:<id>`
+    - per-system at `system:<systemId>`
+    - per-filter-shape at `list:<stable-stringify(filters)>` for the few list shapes the dashboard polls
+  - Mutations (`createIncident`, `updateIncident`, `addUpdate`, `resolveIncident`, `deleteIncident`) invalidate the incident, every affected system, and every cached list before broadcasting `INCIDENT_UPDATED`.
+  - The catalog `systemDeleted` cleanup hook drops that system's cached entries.
+
+  ### `@checkstack/maintenance-backend`
+
+  - `listMaintenances`, `getMaintenance`, `getMaintenancesForSystem`, and `getBulkMaintenancesForSystems` use the same per-entity / per-system / per-filter-shape pattern as incidents.
+  - Mutations (`createMaintenance`, `updateMaintenance`, `addUpdate`, `closeMaintenance`, `deleteMaintenance`) invalidate before broadcasting `MAINTENANCE_UPDATED`.
+
+  ### `@checkstack/catalog-backend`
+
+  - Topology reads (`getEntities`, `getSystems`, `getSystem`, `getGroups`, `getSystemGroupIds`) cache under the `entity:` family (25s TTL).
+  - Views (`getViews`) and per-system contacts (`getSystemContacts`) cache in their own families.
+  - System / group / membership mutations drop the entire `entity:` family (every reader joins the same tables); view and contact mutations drop only their respective scopes.
+
+  ### `@checkstack/slo-backend`
+
+  - `listObjectives`, `getObjective`, `getObjectivesForSystem`, and `getBulkObjectivesForSystems` cache results including the expensive `engine.computeStatus` output.
+  - Per-entity caching for the bulk handler so dashboards with overlapping system sets share entries.
+  - Mutations (`createObjective`, `updateObjective`, `deleteObjective`) invalidate before broadcasting `SLO_STATUS_CHANGED`.
+
+  ### `@checkstack/anomaly-backend`
+
+  - New `router-cache.ts` adds a cache scope distinct from the existing detector baseline cache, keyed by stable filter hash.
+  - `getAnomalies` and `getAnomalyBaselines` cache through this scope (15s TTL).
+  - The detector invalidates the router cache before broadcasting `ANOMALY_STATE_CHANGED` on every state transition (suspicious/anomaly/recovered).
+  - Config mutations also invalidate.
+
+  ### `@checkstack/notification-backend`
+
+  - `getUnreadCount`, `getNotifications`, and `getSubscriptions` cache per-user.
+  - `markAsRead`, `deleteNotification`, `notifyUsers`, and `notifyGroups` invalidate every affected user's cache before sending realtime signals to that user.
+  - `subscribe` and `unsubscribe` invalidate the user's subscription cache.
+
+  ### `@checkstack/announcement-backend`
+
+  - `getActiveAnnouncements` caches per-user (or anonymous) and per-`includeDismissed` flag (45s TTL — admin-driven, slowly changing).
+  - `listAllAnnouncements` caches under a single key.
+  - `dismissAnnouncement` only drops that user's cache; `createAnnouncement`, `updateAnnouncement`, `deleteAnnouncement` drop every user's cache before broadcasting `ANNOUNCEMENT_UPDATED`.
+  - The auth `userDeleted` cleanup hook drops that user's cached entries.
+
+### Patch Changes
+
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+  - @checkstack/cache-api@0.2.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@checkstack/cache-utils",
+  "version": "0.2.0",
+  "checkstack": {
+    "type": "tooling"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "dependencies": {
+    "@checkstack/cache-api": "0.1.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2",
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/cached-scope.test.ts

@@ -0,0 +1,342 @@
+import { describe, expect, it, mock } from "bun:test";
+import type { CacheManager, CacheProvider } from "@checkstack/cache-api";
+import { createCachedScope } from "./cached-scope";
+
+function createMemoryProvider(): CacheProvider {
+  const store = new Map<string, unknown>();
+  return {
+    get: async <T>(key: string) => store.get(key) as T | undefined,
+    set: async (key, value) => {
+      store.set(key, value);
+    },
+    delete: async (key) => {
+      store.delete(key);
+    },
+    deleteByPrefix: async (prefix) => {
+      let removed = 0;
+      for (const key of [...store.keys()]) {
+        if (key.startsWith(prefix)) {
+          store.delete(key);
+          removed++;
+        }
+      }
+      return removed;
+    },
+    has: async (key) => store.has(key),
+  };
+}
+
+function createManager(provider: CacheProvider): CacheManager {
+  return {
+    getProvider: () => provider,
+    getActivePlugin: () => "test",
+    getActiveConfig: () => ({}),
+    setActiveBackend: async () => {},
+    shutdown: async () => {},
+  };
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+describe("createCachedScope", () => {
+  describe("wrap (single-flight)", () => {
+    it("returns the loader's value on a cold miss and caches it", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+      });
+
+      const loader = mock(async () => "hello");
+      const value = await scope.wrap("k", loader);
+
+      expect(value).toBe("hello");
+      expect(loader).toHaveBeenCalledTimes(1);
+      expect(await provider.get<string>("test:k")).toBe("hello");
+    });
+
+    it("returns the cached value on subsequent calls without invoking the loader", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+      });
+
+      const loader = mock(async () => "hello");
+      await scope.wrap("k", loader);
+      const second = await scope.wrap("k", loader);
+
+      expect(second).toBe("hello");
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it("deduplicates concurrent misses for the same key (single-flight)", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+      });
+
+      const gate = deferred<string>();
+      const loader = mock(() => gate.promise);
+
+      const a = scope.wrap("k", loader);
+      const b = scope.wrap("k", loader);
+      const c = scope.wrap("k", loader);
+
+      gate.resolve("once");
+      const results = await Promise.all([a, b, c]);
+
+      expect(results).toEqual(["once", "once", "once"]);
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not deduplicate across different keys", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+      });
+
+      const loader = mock(async (key: string) => `v:${key}`);
+      const [a, b] = await Promise.all([
+        scope.wrap("a", () => loader("a")),
+        scope.wrap("b", () => loader("b")),
+      ]);
+
+      expect(a).toBe("v:a");
+      expect(b).toBe("v:b");
+      expect(loader).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not cache loader errors and clears the in-flight slot", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+      });
+
+      const loader = mock(async (): Promise<string> => {
+        throw new Error("boom");
+      });
+
+      await expect(scope.wrap("k", loader)).rejects.toThrow("boom");
+      // Second call must re-run the loader (no negative caching, no stuck in-flight).
+      await expect(scope.wrap("k", loader)).rejects.toThrow("boom");
+      expect(loader).toHaveBeenCalledTimes(2);
+      expect(await provider.has("test:k")).toBe(false);
+    });
+
+    it("falls through to the loader if the cache get throws", async () => {
+      const broken: CacheProvider = {
+        ...createMemoryProvider(),
+        get: async () => {
+          throw new Error("cache down");
+        },
+      };
+      const scope = createCachedScope({
+        cacheManager: createManager(broken),
+        pluginId: "test",
+        onError: () => {},
+      });
+
+      const loader = mock(async () => "ok");
+      const value = await scope.wrap("k", loader);
+      expect(value).toBe("ok");
+      expect(loader).toHaveBeenCalledTimes(1);
+    });
+
+    it("respects per-call ttlMs over the scope default", async () => {
+      const provider = createMemoryProvider();
+      const setSpy = mock(provider.set);
+      provider.set = setSpy;
+
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "test",
+        defaultTtlMs: 1000,
+      });
+
+      await scope.wrap("k", async () => "v", { ttlMs: 9999 });
+      expect(setSpy).toHaveBeenCalledWith("test:k", "v", 9999);
+    });
+  });
+
+  describe("wrapMany", () => {
+    it("returns results in input order, caching per id", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      const loader = mock(async (id: string) => `status:${id}`);
+      const result = await scope.wrapMany(["s1", "s2", "s3"], {
+        keyFor: (id) => `status:${id}`,
+        loader,
+      });
+
+      expect(result).toEqual(["status:s1", "status:s2", "status:s3"]);
+      expect(loader).toHaveBeenCalledTimes(3);
+      expect(await provider.get<string>("hc:status:s1")).toBe("status:s1");
+      expect(await provider.get<string>("hc:status:s2")).toBe("status:s2");
+    });
+
+    it("only calls the loader for missing ids on subsequent calls", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      const loader = mock(async (id: string) => `v:${id}`);
+      await scope.wrapMany(["a", "b"], {
+        keyFor: (id) => `e:${id}`,
+        loader,
+      });
+      loader.mockClear();
+
+      const result = await scope.wrapMany(["a", "b", "c"], {
+        keyFor: (id) => `e:${id}`,
+        loader,
+      });
+
+      expect(result).toEqual(["v:a", "v:b", "v:c"]);
+      expect(loader).toHaveBeenCalledTimes(1);
+      expect(loader).toHaveBeenCalledWith("c");
+    });
+
+    it("returns [] for an empty id list without touching the cache", async () => {
+      const provider = createMemoryProvider();
+      const getSpy = mock(provider.get) as CacheProvider["get"];
+      provider.get = getSpy;
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      const result = await scope.wrapMany<string, string>([], {
+        keyFor: (id) => id,
+        loader: async () => "x",
+      });
+      expect(result).toEqual([]);
+      expect(getSpy).not.toHaveBeenCalled();
+    });
+
+    it("deduplicates concurrent loads for the same id within a bulk call", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "hc",
+      });
+
+      const loader = mock(async (id: string) => `v:${id}`);
+
+      const [first, second] = await Promise.all([
+        scope.wrapMany(["a", "b"], {
+          keyFor: (id) => `e:${id}`,
+          loader,
+        }),
+        scope.wrapMany(["a", "c"], {
+          keyFor: (id) => `e:${id}`,
+          loader,
+        }),
+      ]);
+
+      expect(first).toEqual(["v:a", "v:b"]);
+      expect(second).toEqual(["v:a", "v:c"]);
+      // 'a' should be loaded once across both concurrent bulks.
+      expect(loader).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("invalidate / invalidatePrefix", () => {
+    it("invalidate removes a single key so the next read re-loads", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "p",
+      });
+
+      const loader = mock(async () => "v1");
+      await scope.wrap("k", loader);
+      await scope.invalidate("k");
+
+      const second = await scope.wrap("k", async () => "v2");
+      expect(second).toBe("v2");
+    });
+
+    it("invalidatePrefix removes every key under the prefix and reports the count", async () => {
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "p",
+      });
+
+      await scope.wrap("list:active", async () => "a");
+      await scope.wrap("list:resolved", async () => "b");
+      await scope.wrap("get:1", async () => "c");
+
+      const removed = await scope.invalidatePrefix("list:");
+      expect(removed).toBe(2);
+      expect(await provider.has("p:list:active")).toBe(false);
+      expect(await provider.has("p:list:resolved")).toBe(false);
+      expect(await provider.has("p:get:1")).toBe(true);
+    });
+
+    it("invalidatePrefix cannot reach keys in other plugin scopes", async () => {
+      const provider = createMemoryProvider();
+      const scopeA = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "a",
+      });
+      const scopeB = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "b",
+      });
+
+      await scopeA.wrap("x", async () => "1");
+      await scopeB.wrap("x", async () => "2");
+
+      await scopeA.invalidatePrefix("");
+      expect(await scopeB.provider.get<string>("x")).toBe("2");
+    });
+
+    it("epoch check prevents an in-flight loader from writing stale data after invalidation", async () => {
+      // Race: loader's DB query was issued before the mutation's DB write
+      // committed, so the loader will return pre-mutation data. The mutation
+      // then runs invalidate. By the time the loader resolves, the cache
+      // must NOT be repopulated with the stale value.
+      const provider = createMemoryProvider();
+      const scope = createCachedScope({
+        cacheManager: createManager(provider),
+        pluginId: "p",
+      });
+
+      const gate = deferred<string>();
+      // Capture epoch synchronously when "DB query is issued" — the loader
+      // body runs lazily inside wrap, which captures epoch before issuing it.
+      const loader = mock(() => gate.promise);
+
+      const reading = scope.wrap("k", loader);
+      // Let wrap progress past its initial cache-miss check and start the
+      // loader. Once the loader is running, simulate the mutation:
+      await Promise.resolve();
+      await Promise.resolve();
+      await scope.invalidate("k");
+      gate.resolve("pre-mutation-value");
+      await reading;
+
+      // Cache must not contain the stale value the in-flight loader returned.
+      expect(await provider.has("p:k")).toBe(false);
+    });
+  });
+});

package/src/cached-scope.ts

@@ -0,0 +1,213 @@
+import {
+  createScopedCache,
+  type CacheManager,
+  type CacheProvider,
+} from "@checkstack/cache-api";
+
+/**
+ * High-level cache helper used by routers/services that want to wrap
+ * read-through caching around DB queries with safe invalidation.
+ *
+ * Built on top of {@link CacheProvider} but adds:
+ *  - single-flight per key (no thundering herd on cache miss)
+ *  - {@link wrapMany} for per-entity caching of bulk reads
+ *  - prefix-based bulk invalidation (delegated to the provider)
+ *  - graceful fallback to the underlying loader if the cache layer throws,
+ *    so a cache outage cannot take down the read path
+ */
+export interface CachedScope {
+  /**
+   * Read-through cache for a single key. If the key is cached, returns it.
+   * Otherwise calls {@link loader}, stores the result, and returns it.
+   *
+   * Concurrent callers for the same key share a single in-flight loader
+   * promise (single-flight) so a cache miss does not stampede the DB.
+   */
+  wrap<T>(
+    key: string,
+    loader: () => Promise<T>,
+    options?: { ttlMs?: number },
+  ): Promise<T>;
+
+  /**
+   * Per-entity caching for bulk reads. For each id, returns the cached value
+   * if present; otherwise loads it via {@link loader} and caches it. Misses
+   * are loaded in parallel and concurrent loads for the same id are
+   * deduplicated (single-flight).
+   *
+   * The {@link keyFor} function maps an id to a cache key inside this scope —
+   * keep it stable so invalidation and reads agree. Use plain readable keys
+   * like `status:${id}` so {@link invalidatePrefix} can target families.
+   */
+  wrapMany<Id, T>(
+    ids: readonly Id[],
+    options: {
+      keyFor: (id: Id) => string;
+      loader: (id: Id) => Promise<T>;
+      ttlMs?: number;
+    },
+  ): Promise<T[]>;
+
+  /**
+   * Invalidate exactly one key. Safe to call from mutation paths.
+   * Prefer this over prefix invalidation when you know the affected entity.
+   */
+  invalidate(key: string): Promise<void>;
+
+  /**
+   * Invalidate every key in this scope that starts with {@link prefix}.
+   * Use sparingly — prefer per-entity {@link invalidate} when possible.
+   * Returns the number of keys actually removed.
+   */
+  invalidatePrefix(prefix: string): Promise<number>;
+
+  /** The underlying scoped {@link CacheProvider}, exposed for advanced cases. */
+  readonly provider: CacheProvider;
+}
+
+/**
+ * Create a {@link CachedScope} for a plugin. All keys are automatically
+ * prefixed with the plugin id (via {@link createScopedCache}) so plugins
+ * sharing a backend don't collide and {@link invalidatePrefix} cannot reach
+ * keys belonging to other plugins.
+ */
+export function createCachedScope({
+  cacheManager,
+  pluginId,
+  defaultTtlMs,
+  onError,
+}: {
+  cacheManager: CacheManager;
+  pluginId: string;
+  defaultTtlMs?: number;
+  /**
+   * Called when a cache operation throws. Defaults to swallowing the error
+   * after the loader's value has been returned — a cache failure must never
+   * fail a request. Use this hook to surface metrics/logs.
+   */
+  onError?: (op: "get" | "set" | "delete" | "deleteByPrefix", error: unknown) => void;
+}): CachedScope {
+  const provider = createScopedCache({
+    pluginId,
+    provider: cacheManager.getProvider(),
+  });
+
+  const inflight = new Map<string, Promise<unknown>>();
+  /**
+   * Per-key epoch counter. Incremented on every invalidate so that an
+   * in-flight loader started before invalidation cannot write stale data
+   * to the cache after invalidation completes. The mutation path therefore
+   * truly wins the race even if a reader had already begun a DB query
+   * against pre-mutation state.
+   */
+  const epochs = new Map<string, number>();
+
+  const reportError = (
+    op: "get" | "set" | "delete" | "deleteByPrefix",
+    error: unknown,
+  ) => {
+    if (onError) {
+      onError(op, error);
+    }
+  };
+
+  function bumpEpoch(key: string): void {
+    epochs.set(key, (epochs.get(key) ?? 0) + 1);
+  }
+
+  async function wrap<T>(
+    key: string,
+    loader: () => Promise<T>,
+    options?: { ttlMs?: number },
+  ): Promise<T> {
+    try {
+      const cached = await provider.get<T>(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+    } catch (error) {
+      reportError("get", error);
+      // fall through to loader
+    }
+
+    const existing = inflight.get(key) as Promise<T> | undefined;
+    if (existing) {
+      return existing;
+    }
+
+    const ttlMs = options?.ttlMs ?? defaultTtlMs;
+    const startEpoch = epochs.get(key) ?? 0;
+    const loading = (async () => {
+      try {
+        const value = await loader();
+        if ((epochs.get(key) ?? 0) === startEpoch) {
+          try {
+            await provider.set(key, value, ttlMs);
+          } catch (error) {
+            reportError("set", error);
+          }
+        }
+        // If epoch changed, an invalidation happened during the load —
+        // do NOT write the (now stale) value. The caller still receives
+        // it (their read began before the mutation), but the next reader
+        // will go to the DB and see the post-mutation state.
+        return value;
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+    inflight.set(key, loading);
+    return loading;
+  }
+
+  async function wrapMany<Id, T>(
+    ids: readonly Id[],
+    options: {
+      keyFor: (id: Id) => string;
+      loader: (id: Id) => Promise<T>;
+      ttlMs?: number;
+    },
+  ): Promise<T[]> {
+    if (ids.length === 0) {
+      return [];
+    }
+    return Promise.all(
+      ids.map((id) =>
+        wrap(options.keyFor(id), () => options.loader(id), {
+          ttlMs: options.ttlMs,
+        }),
+      ),
+    );
+  }
+
+  async function invalidate(key: string): Promise<void> {
+    bumpEpoch(key);
+    inflight.delete(key);
+    try {
+      await provider.delete(key);
+    } catch (error) {
+      reportError("delete", error);
+    }
+  }
+
+  async function invalidatePrefix(prefix: string): Promise<number> {
+    for (const key of inflight.keys()) {
+      if (key.startsWith(prefix)) {
+        inflight.delete(key);
+      }
+    }
+    for (const key of epochs.keys()) {
+      if (key.startsWith(prefix)) {
+        bumpEpoch(key);
+      }
+    }
+    try {
+      return await provider.deleteByPrefix(prefix);
+    } catch (error) {
+      reportError("deleteByPrefix", error);
+      return 0;
+    }
+  }
+
+  return { wrap, wrapMany, invalidate, invalidatePrefix, provider };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./cached-scope";

package/tsconfig.json

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