@checkstack/catalog-backend 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @checkstack/catalog-backend
 
+## 0.7.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]
+- Updated dependencies [8d1ef12]
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/cache-utils@0.2.0
+  - @checkstack/backend-api@0.13.0
+  - @checkstack/auth-backend@0.4.20
+  - @checkstack/auth-common@0.6.3
+  - @checkstack/catalog-common@1.5.2
+  - @checkstack/command-backend@0.1.20
+  - @checkstack/gitops-backend@0.2.4
+  - @checkstack/gitops-common@0.2.1
+  - @checkstack/notification-common@0.2.9
+
 ## 0.6.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-backend",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,8 +14,10 @@
   },
   "dependencies": {
     "@checkstack/backend-api": "0.12.0",
+    "@checkstack/cache-api": "0.1.0",
+    "@checkstack/cache-utils": "0.1.0",
     "@checkstack/auth-common": "0.6.2",
-    "@checkstack/catalog-common": "1.4.1",
+    "@checkstack/catalog-common": "1.5.1",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/auth-backend": "0.4.19",
     "@checkstack/gitops-backend": "0.2.3",

package/src/cache.ts

@@ -0,0 +1,94 @@
+import type { CacheManager } from "@checkstack/cache-api";
+import {
+  createCachedScope,
+  type CachedScope,
+} from "@checkstack/cache-utils";
+import type { Logger } from "@checkstack/backend-api";
+
+/**
+ * 25s — slightly under the dashboard's 30s `staleTime`. Catalog mutations
+ * are infrequent (admin operations), so signal-driven invalidation is the
+ * primary mechanism and TTL is a long safety net.
+ */
+const CATALOG_TTL_MS = 25_000;
+
+/** Topology family: entities, systems, groups, per-system, groups-for-system. */
+const ENTITY_PREFIX = "entity:";
+const VIEW_PREFIX = "view:";
+const CONTACTS_PREFIX = "contacts:";
+
+const ENTITIES_KEY = `${ENTITY_PREFIX}entities`;
+const SYSTEMS_KEY = `${ENTITY_PREFIX}systems`;
+const GROUPS_KEY = `${ENTITY_PREFIX}groups`;
+const VIEWS_KEY = `${VIEW_PREFIX}all`;
+
+const systemKey = (id: string): string => `${ENTITY_PREFIX}system:${id}`;
+const groupsForSystemKey = (systemId: string): string =>
+  `${ENTITY_PREFIX}groups-for-system:${systemId}`;
+const contactsKey = (systemId: string): string =>
+  `${CONTACTS_PREFIX}${systemId}`;
+
+export interface CatalogCache {
+  /** Read-through caches for the dashboard hot paths. */
+  wrapEntities: <T>(loader: () => Promise<T>) => Promise<T>;
+  wrapSystems: <T>(loader: () => Promise<T>) => Promise<T>;
+  wrapGroups: <T>(loader: () => Promise<T>) => Promise<T>;
+  wrapSystem: <T>(systemId: string, loader: () => Promise<T>) => Promise<T>;
+  wrapGroupsForSystem: <T>(
+    systemId: string,
+    loader: () => Promise<T>,
+  ) => Promise<T>;
+  wrapViews: <T>(loader: () => Promise<T>) => Promise<T>;
+  wrapContacts: <T>(systemId: string, loader: () => Promise<T>) => Promise<T>;
+
+  /**
+   * Drop the whole topology family (entities, systems, groups, per-system,
+   * groups-for-system). Used by every system/group/membership mutation —
+   * `getEntities` already joins all four tables, so any change to any of
+   * them logically affects every cached topology shape.
+   */
+  invalidateTopology: () => Promise<number>;
+
+  /** Drop the views cache. */
+  invalidateViews: () => Promise<number>;
+
+  /** Drop one system's contact cache. */
+  invalidateContacts: (systemId: string) => Promise<void>;
+
+  scope: CachedScope;
+}
+
+export function createCatalogCache({
+  cacheManager,
+  logger,
+}: {
+  cacheManager: CacheManager;
+  logger: Logger;
+}): CatalogCache {
+  const scope = createCachedScope({
+    cacheManager,
+    pluginId: "catalog",
+    defaultTtlMs: CATALOG_TTL_MS,
+    onError: (op: string, error: unknown) => {
+      logger.warn(`catalog cache ${op} failed: ${String(error)}`);
+    },
+  });
+
+  return {
+    wrapEntities: (loader) => scope.wrap(ENTITIES_KEY, loader),
+    wrapSystems: (loader) => scope.wrap(SYSTEMS_KEY, loader),
+    wrapGroups: (loader) => scope.wrap(GROUPS_KEY, loader),
+    wrapSystem: (systemId, loader) => scope.wrap(systemKey(systemId), loader),
+    wrapGroupsForSystem: (systemId, loader) =>
+      scope.wrap(groupsForSystemKey(systemId), loader),
+    wrapViews: (loader) => scope.wrap(VIEWS_KEY, loader),
+    wrapContacts: (systemId, loader) =>
+      scope.wrap(contactsKey(systemId), loader),
+
+    invalidateTopology: () => scope.invalidatePrefix(ENTITY_PREFIX),
+    invalidateViews: () => scope.invalidatePrefix(VIEW_PREFIX),
+    invalidateContacts: (systemId) => scope.invalidate(contactsKey(systemId)),
+
+    scope,
+  };
+}

package/src/index.ts

@@ -11,6 +11,7 @@ import {
   catalogRoutes,
 } from "@checkstack/catalog-common";
 import { createCatalogRouter } from "./router";
+import { createCatalogCache } from "./cache";
 import { NotificationApi } from "@checkstack/notification-common";
 import { AuthApi } from "@checkstack/auth-common";
 import { authHooks } from "@checkstack/auth-backend";
@@ -180,9 +181,10 @@ export default createBackendPlugin({
         rpc: coreServices.rpc,
         rpcClient: coreServices.rpcClient,
         logger: coreServices.logger,
+        cacheManager: coreServices.cacheManager,
       },
       // Phase 2: Register router only - no RPC calls to other plugins
-      init: async ({ database, rpc, rpcClient, logger }) => {
+      init: async ({ database, rpc, rpcClient, logger, cacheManager }) => {
         logger.debug("Initializing Catalog Backend...");
 
         // Populate the mutable DB reference for GitOps reconcile closures
@@ -195,6 +197,8 @@ export default createBackendPlugin({
         const authClient = rpcClient.forPlugin(AuthApi);
         const gitOpsClient = rpcClient.forPlugin(GitOpsApi);
 
+        const cache = createCatalogCache({ cacheManager, logger });
+
         // Register oRPC router with notification client and auth client
         const catalogRouter = createCatalogRouter({
           database: typedDb,
@@ -202,6 +206,7 @@ export default createBackendPlugin({
           authClient,
           gitOpsClient,
           pluginId: pluginMetadata.pluginId,
+          cache,
         });
         rpc.registerRouter(catalogRouter, catalogContract);
 

package/src/router.test.ts

@@ -2,6 +2,21 @@ import { describe, it, expect, mock } from "bun:test";
 import { createCatalogRouter } from "./router";
 import { createMockRpcContext } from "@checkstack/backend-api";
 import { call } from "@orpc/server";
+import type { CatalogCache } from "./cache";
+
+const passthroughCache: CatalogCache = {
+  wrapEntities: (loader) => loader(),
+  wrapSystems: (loader) => loader(),
+  wrapGroups: (loader) => loader(),
+  wrapSystem: (_systemId, loader) => loader(),
+  wrapGroupsForSystem: (_systemId, loader) => loader(),
+  wrapViews: (loader) => loader(),
+  wrapContacts: (_systemId, loader) => loader(),
+  invalidateTopology: async () => 0,
+  invalidateViews: async () => 0,
+  invalidateContacts: async () => {},
+  scope: {} as CatalogCache["scope"],
+};
 
 describe("Catalog Router - GitOps Provenance Enforcement", () => {
   const mockUser = {
@@ -39,6 +54,7 @@ describe("Catalog Router - GitOps Provenance Enforcement", () => {
     authClient: mockAuthClient as never,
     gitOpsClient: mockGitOpsClient as never,
     pluginId: "test-catalog",
+    cache: passthroughCache,
   });
 
   it("allows deleteSystem when GitOps lock is not present", async () => {

package/src/router.ts

@@ -13,6 +13,7 @@ import type { InferClient } from "@checkstack/common";
 import { catalogHooks } from "./hooks";
 import { eq } from "drizzle-orm";
 import { GitOpsApi } from "@checkstack/gitops-common";
+import type { CatalogCache } from "./cache";
 
 /**
  * Creates the catalog router using contract-based implementation.
@@ -30,6 +31,7 @@ export interface CatalogRouterDeps {
   authClient: InferClient<typeof AuthApi>;
   gitOpsClient: InferClient<typeof GitOpsApi>;
   pluginId: string;
+  cache: CatalogCache;
 }
 
 export const createCatalogRouter = ({
@@ -38,6 +40,7 @@ export const createCatalogRouter = ({
   authClient,
   gitOpsClient,
   pluginId,
+  cache,
 }: CatalogRouterDeps) => {
   const entityService = new EntityService(database);
 
@@ -95,49 +98,61 @@ export const createCatalogRouter = ({
   };
 
   // Implement each contract method
-  const getEntities = os.getEntities.handler(async () => {
-    const systems = await entityService.getSystems();
-    const groups = await entityService.getGroups();
-    // Cast to match contract - Drizzle json() returns unknown, but we expect Record | null
-    return {
-      systems: systems as unknown as Array<
-        (typeof systems)[number] & {
-          metadata: Record<string, unknown> | null;
-        }
-      >,
-      groups: groups as unknown as Array<
-        (typeof groups)[number] & { metadata: Record<string, unknown> | null }
-      >,
-    };
-  });
+  const getEntities = os.getEntities.handler(async () =>
+    cache.wrapEntities(async () => {
+      const systems = await entityService.getSystems();
+      const groups = await entityService.getGroups();
+      // Cast to match contract - Drizzle json() returns unknown, but we expect Record | null
+      return {
+        systems: systems as unknown as Array<
+          (typeof systems)[number] & {
+            metadata: Record<string, unknown> | null;
+          }
+        >,
+        groups: groups as unknown as Array<
+          (typeof groups)[number] & {
+            metadata: Record<string, unknown> | null;
+          }
+        >,
+      };
+    }),
+  );
 
-  const getSystems = os.getSystems.handler(async () => {
-    const systems = await entityService.getSystems();
-    return {
-      systems: systems as unknown as Array<
-        (typeof systems)[number] & { metadata: Record<string, unknown> | null }
-      >,
-    };
-  });
+  const getSystems = os.getSystems.handler(async () =>
+    cache.wrapSystems(async () => {
+      const systems = await entityService.getSystems();
+      return {
+        systems: systems as unknown as Array<
+          (typeof systems)[number] & {
+            metadata: Record<string, unknown> | null;
+          }
+        >,
+      };
+    }),
+  );
 
-  const getSystem = os.getSystem.handler(async ({ input }) => {
-    const system = await entityService.getSystem(input.systemId);
-    if (!system) {
-      // oRPC contract uses .nullable() which requires null
-      // eslint-disable-next-line unicorn/no-null
-      return null;
-    }
-    return system as typeof system & {
-      metadata: Record<string, unknown> | null;
-    };
-  });
+  const getSystem = os.getSystem.handler(async ({ input }) =>
+    cache.wrapSystem(input.systemId, async () => {
+      const system = await entityService.getSystem(input.systemId);
+      if (!system) {
+        // oRPC contract uses .nullable() which requires null
+        // eslint-disable-next-line unicorn/no-null
+        return null;
+      }
+      return system as typeof system & {
+        metadata: Record<string, unknown> | null;
+      };
+    }),
+  );
 
-  const getGroups = os.getGroups.handler(async () => {
-    const groups = await entityService.getGroups();
-    return groups as unknown as Array<
-      (typeof groups)[number] & { metadata: Record<string, unknown> | null }
-    >;
-  });
+  const getGroups = os.getGroups.handler(async () =>
+    cache.wrapGroups(async () => {
+      const groups = await entityService.getGroups();
+      return groups as unknown as Array<
+        (typeof groups)[number] & { metadata: Record<string, unknown> | null }
+      >;
+    }),
+  );
 
   const createSystem = os.createSystem.handler(async ({ input }) => {
     const result = await entityService.createSystem(input);
@@ -145,6 +160,11 @@ export const createCatalogRouter = ({
     // Create a notification group for this system
     await createNotificationGroup("system", result.id, result.name);
 
+    // Drop the topology cache before any downstream side-effect that might
+    // observe it (notification group creation already happened, but the
+    // hook chain in deleteSystem/etc. relies on this ordering).
+    await cache.invalidateTopology();
+
     return result as typeof result & {
       metadata: Record<string, unknown> | null;
     };
@@ -170,6 +190,7 @@ export const createCatalogRouter = ({
         message: "System not found",
       });
     }
+    await cache.invalidateTopology();
     return result as typeof result & {
       metadata: Record<string, unknown> | null;
     };
@@ -182,6 +203,14 @@ export const createCatalogRouter = ({
     // Delete the notification group for this system
     await deleteNotificationGroup("system", input);
 
+    // Drop catalog topology + this system's contacts BEFORE the hook fires,
+    // so downstream plugins (e.g. healthcheck) and any frontend that
+    // refetches in response see fresh data.
+    await Promise.all([
+      cache.invalidateTopology(),
+      cache.invalidateContacts(input),
+    ]);
+
     // Emit hook for other plugins to clean up related data
     await context.emitHook(catalogHooks.systemDeleted, { systemId: input });
 
@@ -197,6 +226,8 @@ export const createCatalogRouter = ({
     // Create a notification group for this catalog group
     await createNotificationGroup("group", result.id, result.name);
 
+    await cache.invalidateTopology();
+
     // New groups have no systems yet
     return {
       ...result,
@@ -226,6 +257,7 @@ export const createCatalogRouter = ({
         message: "Group not found after update",
       });
     }
+    await cache.invalidateTopology();
     return fullGroup as unknown as typeof fullGroup & {
       metadata: Record<string, unknown> | null;
     };
@@ -238,6 +270,8 @@ export const createCatalogRouter = ({
     // Delete the notification group for this catalog group
     await deleteNotificationGroup("group", input);
 
+    await cache.invalidateTopology();
+
     // Emit hook for other plugins to clean up related data
     await context.emitHook(catalogHooks.groupDeleted, { groupId: input });
 
@@ -248,10 +282,11 @@ export const createCatalogRouter = ({
     // Note: We only enforce the lock on the System, not the Group.
     // This is because system-group associations are reconciled as a kindExtension
     // of the System kind. The Group reconciler does not touch associations.
-    // Thus, it is perfectly safe (and intended) to manually add an unlocked System 
+    // Thus, it is perfectly safe (and intended) to manually add an unlocked System
     // to a GitOps-managed Group.
     await enforceNotGitOpsLocked("System", input.systemId);
     await entityService.addSystemToGroup(input);
+    await cache.invalidateTopology();
     return { success: true };
   });
 
@@ -260,28 +295,34 @@ export const createCatalogRouter = ({
       // See addSystemToGroup for why we only check the System provenance lock.
       await enforceNotGitOpsLocked("System", input.systemId);
       await entityService.removeSystemFromGroup(input);
+      await cache.invalidateTopology();
       return { success: true };
     },
   );
 
-  const getViews = os.getViews.handler(async () => entityService.getViews());
+  const getViews = os.getViews.handler(async () =>
+    cache.wrapViews(() => entityService.getViews()),
+  );
 
   const createView = os.createView.handler(async ({ input }) => {
-    return entityService.createView({
+    const result = await entityService.createView({
       name: input.name,
       type: "custom",
       config: input.configuration as Record<string, unknown>,
     });
+    await cache.invalidateViews();
+    return result;
   });
 
   // System Contacts handlers
-  const getSystemContacts = os.getSystemContacts.handler(async ({ input }) => {
-    const rawContacts = await entityService.getContactsForSystem(
-      input.systemId,
-    );
+  const getSystemContacts = os.getSystemContacts.handler(async ({ input }) =>
+    cache.wrapContacts(input.systemId, async () => {
+      const rawContacts = await entityService.getContactsForSystem(
+        input.systemId,
+      );
 
-    // Resolve user profiles for user-type contacts
-    const enrichedContacts: SystemContact[] = await Promise.all(
+      // Resolve user profiles for user-type contacts
+      const enrichedContacts: SystemContact[] = await Promise.all(
       rawContacts.map(async (contact) => {
         if (contact.type === "user" && contact.userId) {
           // Resolve user profile via auth service
@@ -309,8 +350,9 @@ export const createCatalogRouter = ({
       }),
     );
 
-    return enrichedContacts;
-  });
+      return enrichedContacts;
+    }),
+  );
 
   const addSystemContact = os.addSystemContact.handler(async ({ input }) => {
     await enforceNotGitOpsLocked("System", input.systemId);
@@ -334,6 +376,8 @@ export const createCatalogRouter = ({
       label: input.label,
     });
 
+    await cache.invalidateContacts(input.systemId);
+
     // Return the enriched contact
     if (result.type === "user" && result.userId) {
       const user = await authClient.getUserById({ userId: result.userId });
@@ -366,6 +410,9 @@ export const createCatalogRouter = ({
         await enforceNotGitOpsLocked("System", contacts[0].systemId);
       }
       await entityService.removeContact(input);
+      if (contacts[0]) {
+        await cache.invalidateContacts(contacts[0].systemId);
+      }
       return { success: true };
     },
   );
@@ -420,14 +467,15 @@ export const createCatalogRouter = ({
    * Used by the dependency plugin for batched notification deduplication.
    */
   const getSystemGroupIds = os.getSystemGroupIds.handler(
-    async ({ input }) => {
-      const systemGroups = await database
-        .select({ groupId: schema.systemsGroups.groupId })
-        .from(schema.systemsGroups)
-        .where(eq(schema.systemsGroups.systemId, input.systemId));
+    async ({ input }) =>
+      cache.wrapGroupsForSystem(input.systemId, async () => {
+        const systemGroups = await database
+          .select({ groupId: schema.systemsGroups.groupId })
+          .from(schema.systemsGroups)
+          .where(eq(schema.systemsGroups.systemId, input.systemId));
 
-      return { groupIds: systemGroups.map((sg) => sg.groupId) };
-    },
+        return { groupIds: systemGroups.map((sg) => sg.groupId) };
+      }),
   );
 
   // Build and return the router