@checkstack/slo-backend 0.2.16 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @checkstack/slo-backend
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-common@0.2.0
+  - @checkstack/dependency-common@0.3.0
+  - @checkstack/healthcheck-common@0.13.0
+  - @checkstack/integration-common@0.3.0
+  - @checkstack/slo-common@0.3.0
+  - @checkstack/backend-api@0.13.1
+  - @checkstack/healthcheck-backend@0.18.1
+  - @checkstack/integration-backend@0.1.21
+  - @checkstack/catalog-common@1.5.3
+  - @checkstack/catalog-backend@0.7.1
+  - @checkstack/cache-api@0.2.1
+  - @checkstack/command-backend@0.1.21
+  - @checkstack/queue-api@0.2.15
+  - @checkstack/cache-utils@0.2.1
+
+## 0.3.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]
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+  - @checkstack/healthcheck-common@0.12.0
+  - @checkstack/healthcheck-backend@0.18.0
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/cache-utils@0.2.0
+  - @checkstack/catalog-backend@0.7.0
+  - @checkstack/backend-api@0.13.0
+  - @checkstack/catalog-common@1.5.2
+  - @checkstack/command-backend@0.1.20
+  - @checkstack/dependency-common@0.2.3
+  - @checkstack/integration-backend@0.1.20
+  - @checkstack/integration-common@0.2.9
+  - @checkstack/signal-common@0.1.10
+  - @checkstack/slo-common@0.2.2
+  - @checkstack/queue-api@0.2.14
+
 ## 0.2.16
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/slo-backend",
-  "version": "0.2.16",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,19 +13,21 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.12.0",
-    "@checkstack/slo-common": "0.2.0",
-    "@checkstack/healthcheck-common": "0.11.0",
-    "@checkstack/healthcheck-backend": "0.16.5",
-    "@checkstack/dependency-common": "0.2.1",
-    "@checkstack/catalog-common": "1.4.1",
-    "@checkstack/catalog-backend": "0.5.4",
-    "@checkstack/command-backend": "0.1.19",
-    "@checkstack/signal-common": "0.1.9",
-    "@checkstack/integration-backend": "0.1.19",
-    "@checkstack/integration-common": "0.2.8",
-    "@checkstack/common": "0.6.5",
-    "@checkstack/queue-api": "0.2.13",
+    "@checkstack/backend-api": "0.13.0",
+    "@checkstack/cache-api": "0.2.0",
+    "@checkstack/cache-utils": "0.2.0",
+    "@checkstack/slo-common": "0.2.2",
+    "@checkstack/healthcheck-common": "0.12.0",
+    "@checkstack/healthcheck-backend": "0.18.0",
+    "@checkstack/dependency-common": "0.2.3",
+    "@checkstack/catalog-common": "1.5.2",
+    "@checkstack/catalog-backend": "0.7.0",
+    "@checkstack/command-backend": "0.1.20",
+    "@checkstack/signal-common": "0.1.10",
+    "@checkstack/integration-backend": "0.1.20",
+    "@checkstack/integration-common": "0.2.9",
+    "@checkstack/common": "0.7.0",
+    "@checkstack/queue-api": "0.2.14",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
@@ -33,7 +35,7 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.4",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.19",
+    "@checkstack/test-utils-backend": "0.1.20",
     "@checkstack/tsconfig": "0.0.5",
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0"

package/src/cache.ts

@@ -0,0 +1,74 @@
+import type { CacheManager } from "@checkstack/cache-api";
+import {
+  createCachedScope,
+  type CachedScope,
+} from "@checkstack/cache-utils";
+import type { Logger } from "@checkstack/backend-api";
+
+/**
+ * 15s. Each `engine.computeStatus` call runs a SLO calculation over a
+ * rolling window so this cache is more about CPU than DB. Downtime events
+ * generated by the SLO engine can change status outside any tRPC mutation,
+ * so the TTL doubles as a freshness ceiling for that path.
+ */
+const SLO_TTL_MS = 15_000;
+
+const LIST_KEY = "list:objectives";
+const OBJECTIVE_PREFIX = "objective:";
+const SYSTEM_PREFIX = "system:";
+
+const objectiveKey = (id: string): string => `${OBJECTIVE_PREFIX}${id}`;
+const systemKey = (systemId: string): string => `${SYSTEM_PREFIX}${systemId}`;
+
+export interface SloCache {
+  wrapList: <T>(loader: () => Promise<T>) => Promise<T>;
+  wrapObjective: <T>(id: string, loader: () => Promise<T>) => Promise<T>;
+  wrapSystem: <T>(
+    systemId: string,
+    loader: () => Promise<T>,
+  ) => Promise<T>;
+
+  /**
+   * Drop all cached entries affected by a mutation that touches one
+   * objective on one system. Always awaits before signal broadcast.
+   */
+  invalidateForMutation: (props: {
+    objectiveId: string;
+    systemId: string;
+  }) => Promise<void>;
+
+  scope: CachedScope;
+}
+
+export function createSloCache({
+  cacheManager,
+  logger,
+}: {
+  cacheManager: CacheManager;
+  logger: Logger;
+}): SloCache {
+  const scope = createCachedScope({
+    cacheManager,
+    pluginId: "slo",
+    defaultTtlMs: SLO_TTL_MS,
+    onError: (op: string, error: unknown) => {
+      logger.warn(`slo cache ${op} failed: ${String(error)}`);
+    },
+  });
+
+  return {
+    wrapList: (loader) => scope.wrap(LIST_KEY, loader),
+    wrapObjective: (id, loader) => scope.wrap(objectiveKey(id), loader),
+    wrapSystem: (systemId, loader) => scope.wrap(systemKey(systemId), loader),
+
+    invalidateForMutation: async ({ objectiveId, systemId }) => {
+      await Promise.all([
+        scope.invalidate(LIST_KEY),
+        scope.invalidate(objectiveKey(objectiveId)),
+        scope.invalidate(systemKey(systemId)),
+      ]);
+    },
+
+    scope,
+  };
+}

package/src/index.ts

@@ -13,6 +13,7 @@ import { integrationEventExtensionPoint } from "@checkstack/integration-backend"
 import { SloService } from "./service";
 import { SloEngine } from "./slo-engine";
 import { createRouter } from "./router";
+import { createSloCache } from "./cache";
 import { DependencyApi } from "@checkstack/dependency-common";
 import { HealthCheckApi } from "@checkstack/healthcheck-common";
 import { catalogHooks } from "@checkstack/catalog-backend";
@@ -176,8 +177,16 @@ export default createBackendPlugin({
         signalService: coreServices.signalService,
         rpcClient: coreServices.rpcClient,
         queueManager: coreServices.queueManager,
+        cacheManager: coreServices.cacheManager,
       },
-      init: async ({ logger, database, rpc, signalService, rpcClient }) => {
+      init: async ({
+        logger,
+        database,
+        rpc,
+        signalService,
+        rpcClient,
+        cacheManager,
+      }) => {
         logger.debug("🔧 Initializing SLO Backend...");
 
         const service = new SloService(database as SafeDatabase<typeof schema>);
@@ -190,7 +199,14 @@ export default createBackendPlugin({
         // Store for afterPluginsReady
         sharedEngine = engine;
 
-        const router = createRouter({ service, engine, signalService, rpcClient });
+        const cache = createSloCache({ cacheManager, logger });
+        const router = createRouter({
+          service,
+          engine,
+          signalService,
+          rpcClient,
+          cache,
+        });
         rpc.registerRouter(router, sloContract);
 
         // Register command palette entries

package/src/router.ts

@@ -12,17 +12,20 @@ import type { SignalService } from "@checkstack/signal-common";
 import { CatalogApi } from "@checkstack/catalog-common";
 import type { SloService } from "./service";
 import type { SloEngine } from "./slo-engine";
+import type { SloCache } from "./cache";
 
 export function createRouter({
   service,
   engine,
   signalService,
   rpcClient,
+  cache,
 }: {
   service: SloService;
   engine: SloEngine;
   signalService: SignalService;
   rpcClient: RpcClient;
+  cache: SloCache;
 }) {
   const os = implement(sloContract)
     .$context<RpcContext>()
@@ -33,43 +36,49 @@ export function createRouter({
     // OBJECTIVES
     // =========================================================================
 
-    listObjectives: os.listObjectives.handler(async () => {
-      const objectives = await service.listObjectives();
-      const results = await Promise.all(
-        objectives.map(async (objective) => ({
-          objective,
-          status: await engine.computeStatus({ objective }),
-        })),
-      );
-      return { objectives: results };
-    }),
-
-    getObjective: os.getObjective.handler(async ({ input }) => {
-      const objective = await service.getObjective({ id: input.id });
-      if (!objective) {
-        // eslint-disable-next-line unicorn/no-null -- oRPC contract requires null for missing values
-        return null;
-      }
-      const status = await engine.computeStatus({ objective });
-      return { objective, status };
-    }),
-
-    getObjectivesForSystem: os.getObjectivesForSystem.handler(
-      async ({ input }) => {
-        const objectives = await service.getObjectivesForSystem({
-          systemId: input.systemId,
-        });
-        return Promise.all(
+    listObjectives: os.listObjectives.handler(async () =>
+      cache.wrapList(async () => {
+        const objectives = await service.listObjectives();
+        const results = await Promise.all(
           objectives.map(async (objective) => ({
             objective,
             status: await engine.computeStatus({ objective }),
           })),
         );
-      },
+        return { objectives: results };
+      }),
+    ),
+
+    getObjective: os.getObjective.handler(async ({ input }) =>
+      cache.wrapObjective(input.id, async () => {
+        const objective = await service.getObjective({ id: input.id });
+        if (!objective) {
+          // eslint-disable-next-line unicorn/no-null -- oRPC contract requires null for missing values
+          return null;
+        }
+        const status = await engine.computeStatus({ objective });
+        return { objective, status };
+      }),
+    ),
+
+    getObjectivesForSystem: os.getObjectivesForSystem.handler(
+      async ({ input }) =>
+        cache.wrapSystem(input.systemId, async () => {
+          const objectives = await service.getObjectivesForSystem({
+            systemId: input.systemId,
+          });
+          return Promise.all(
+            objectives.map(async (objective) => ({
+              objective,
+              status: await engine.computeStatus({ objective }),
+            })),
+          );
+        }),
     ),
 
     getBulkObjectivesForSystems: os.getBulkObjectivesForSystems.handler(
       async ({ input }) => {
+        // Per-entity caching: see ./cache.ts for the invalidation contract.
         const systems: Record<
           string,
           Array<{
@@ -80,15 +89,17 @@ export function createRouter({
 
         await Promise.all(
           input.systemIds.map(async (systemId) => {
-            const objectives = await service.getObjectivesForSystem({
-              systemId,
+            systems[systemId] = await cache.wrapSystem(systemId, async () => {
+              const objectives = await service.getObjectivesForSystem({
+                systemId,
+              });
+              return Promise.all(
+                objectives.map(async (objective) => ({
+                  objective,
+                  status: await engine.computeStatus({ objective }),
+                })),
+              );
             });
-            systems[systemId] = await Promise.all(
-              objectives.map(async (objective) => ({
-                objective,
-                status: await engine.computeStatus({ objective }),
-              })),
-            );
           }),
         );
 
@@ -105,6 +116,11 @@ export function createRouter({
         await engine.reconcileObjective({ objective });
 
         const status = await engine.computeStatus({ objective });
+        // Mutation invariant: db.write → cache.invalidate (await) → signals.emit.
+        await cache.invalidateForMutation({
+          objectiveId: objective.id,
+          systemId: objective.systemId,
+        });
         await signalService.broadcast(SLO_STATUS_CHANGED, {
           systemId: objective.systemId,
           objectiveId: objective.id,
@@ -128,6 +144,10 @@ export function createRouter({
       await engine.reconcileObjective({ objective });
 
       const status = await engine.computeStatus({ objective });
+      await cache.invalidateForMutation({
+        objectiveId: objective.id,
+        systemId: objective.systemId,
+      });
       await signalService.broadcast(SLO_STATUS_CHANGED, {
         systemId: objective.systemId,
         objectiveId: objective.id,
@@ -139,7 +159,16 @@ export function createRouter({
     }),
 
     deleteObjective: os.deleteObjective.handler(async ({ input }) => {
+      // Look up the objective first so we can target the per-system cache
+      // entry; otherwise we'd have no way to know which system to drop.
+      const existing = await service.getObjective({ id: input.id });
       const success = await service.deleteObjective({ id: input.id });
+      if (success && existing) {
+        await cache.invalidateForMutation({
+          objectiveId: existing.id,
+          systemId: existing.systemId,
+        });
+      }
       return { success };
     }),