@checkstack/incident-backend 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # @checkstack/incident-backend
 
+## 0.6.0
+
+### Minor Changes
+
+- 8d1ef12: ## Anomaly Detection & UI Improvements
+
+  ### Anomaly Detection Enhancements (Phase 2)
+
+  - **`@checkstack/anomaly-backend`**: Implemented background baseline analyzer jobs and anomaly trend deviation detection mechanics.
+  - **`@checkstack/anomaly-common`**: Added new baseline statistical logic and inference rules.
+  - **`@checkstack/anomaly-frontend`**: Added new Anomaly Widget and refactored system detail rendering to be more human-readable.
+  - **`@checkstack/dashboard-frontend`**: Refined the global anomaly widget and fixed hardcoded access gating to render appropriately.
+  - **`@checkstack/healthcheck-backend`**: Connected executor telemetry to the anomaly pipeline.
+  - **`@checkstack/healthcheck-frontend`**: Reconciled baseline display consistency in Drawer and charts.
+
+  ### Notification Identifiers
+
+  - **`@checkstack/incident-backend`**: Resolved system IDs to human-readable System Names within Incident notifications to eliminate ID-only alert content.
+  - **`@checkstack/maintenance-backend`**: Adopted the same resolution strategy for Maintenance notifications to keep parity.
+
+  ### UI Experience
+
+  - **`@checkstack/incident-frontend`**: Fixed the "Back to X" BackLink to properly use `react-router` hook `useNavigate` instead of doing a full application reload.
+  - **`@checkstack/healthcheck-frontend`**: Implemented `useNavigate` for seamless SPA back-linking.
+  - **`@checkstack/integration-frontend`**: Updated connections and delivery logs links to navigate without hard reloads.
+
+- 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/catalog-backend@0.7.0
+  - @checkstack/backend-api@0.13.0
+  - @checkstack/auth-common@0.6.3
+  - @checkstack/catalog-common@1.5.2
+  - @checkstack/command-backend@0.1.20
+  - @checkstack/incident-common@0.4.9
+  - @checkstack/integration-backend@0.1.20
+  - @checkstack/integration-common@0.2.9
+  - @checkstack/signal-common@0.1.10
+
+## 0.5.1
+
+### Patch Changes
+
+- @checkstack/catalog-common@1.5.1
+- @checkstack/incident-common@0.4.8
+- @checkstack/catalog-backend@0.6.1
+
 ## 0.5.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-backend",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,9 +14,11 @@
   },
   "dependencies": {
     "@checkstack/backend-api": "0.12.0",
-    "@checkstack/incident-common": "0.4.7",
-    "@checkstack/catalog-common": "1.4.1",
-    "@checkstack/catalog-backend": "0.5.4",
+    "@checkstack/cache-api": "0.1.0",
+    "@checkstack/cache-utils": "0.1.0",
+    "@checkstack/incident-common": "0.4.8",
+    "@checkstack/catalog-common": "1.5.1",
+    "@checkstack/catalog-backend": "0.6.1",
     "@checkstack/auth-common": "0.6.2",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/signal-common": "0.1.9",

package/src/cache.ts

@@ -0,0 +1,129 @@
+import type { CacheManager } from "@checkstack/cache-api";
+import {
+  createCachedScope,
+  type CachedScope,
+} from "@checkstack/cache-utils";
+import type { Logger } from "@checkstack/backend-api";
+import type { IncidentService } from "./service";
+
+/**
+ * 15s — comfortably under the dashboard's 30s `staleTime` so signal-driven
+ * invalidation almost always wins, and TTL only acts as a safety net.
+ */
+const INCIDENT_TTL_MS = 15_000;
+
+const LIST_PREFIX = "list:";
+const INCIDENT_PREFIX = "incident:";
+const SYSTEM_PREFIX = "system:";
+
+const incidentKey = (id: string): string => `${INCIDENT_PREFIX}${id}`;
+const systemKey = (systemId: string): string => `${SYSTEM_PREFIX}${systemId}`;
+
+/**
+ * Stable JSON for filter shapes — sort keys so {a:1,b:2} and {b:2,a:1}
+ * collapse to the same cache key. Filter shapes here are tiny (<10 fields)
+ * so a recursive sort is cheap and the resulting key is human-readable.
+ */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => stableStringify(v)).join(",")}]`;
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries
+    .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+    .join(",")}}`;
+}
+
+const listKey = (filters: unknown): string =>
+  `${LIST_PREFIX}${stableStringify(filters ?? {})}`;
+
+type ListResult = Awaited<ReturnType<IncidentService["listIncidents"]>>;
+type IncidentResult = Awaited<ReturnType<IncidentService["getIncident"]>>;
+type SystemResult = Awaited<ReturnType<IncidentService["getIncidentsForSystem"]>>;
+
+export interface IncidentCache {
+  /** Read-through cache for {@link IncidentService.listIncidents}. */
+  wrapList: (
+    filters: unknown,
+    loader: () => Promise<ListResult>,
+  ) => Promise<ListResult>;
+
+  /** Read-through cache for {@link IncidentService.getIncident}. */
+  wrapIncident: (
+    id: string,
+    loader: () => Promise<IncidentResult>,
+  ) => Promise<IncidentResult>;
+
+  /** Read-through cache for {@link IncidentService.getIncidentsForSystem}. */
+  wrapSystem: (
+    systemId: string,
+    loader: () => Promise<SystemResult>,
+  ) => Promise<SystemResult>;
+
+  /**
+   * Invalidate everything affected by a mutation on `incidentId` that
+   * touches `systemIds`. Drops:
+   *  - the per-incident cache entry
+   *  - every per-system cache entry for the affected systems
+   *  - every cached list shape (any filter could match)
+   *
+   * Must be awaited *before* emitting `INCIDENT_UPDATED` signals so any
+   * frontend that refetches in response sees fresh data.
+   */
+  invalidateForMutation: (props: {
+    incidentId: string;
+    systemIds: readonly string[];
+  }) => Promise<void>;
+
+  /** Invalidate every cached entry for one system (used on system deletion). */
+  invalidateSystem: (systemId: string) => Promise<void>;
+
+  scope: CachedScope;
+}
+
+export function createIncidentCache({
+  cacheManager,
+  logger,
+}: {
+  cacheManager: CacheManager;
+  logger: Logger;
+}): IncidentCache {
+  const scope = createCachedScope({
+    cacheManager,
+    pluginId: "incident",
+    defaultTtlMs: INCIDENT_TTL_MS,
+    onError: (op, error) => {
+      logger.warn(`incident cache ${op} failed: ${String(error)}`);
+    },
+  });
+
+  return {
+    wrapList: (filters, loader) => scope.wrap(listKey(filters), loader),
+    wrapIncident: (id, loader) => scope.wrap(incidentKey(id), loader),
+    wrapSystem: (systemId, loader) => scope.wrap(systemKey(systemId), loader),
+
+    invalidateForMutation: async ({ incidentId, systemIds }) => {
+      await Promise.all([
+        scope.invalidate(incidentKey(incidentId)),
+        ...systemIds.map((systemId) =>
+          scope.invalidate(systemKey(systemId)),
+        ),
+        scope.invalidatePrefix(LIST_PREFIX),
+      ]);
+    },
+
+    invalidateSystem: async (systemId) => {
+      await Promise.all([
+        scope.invalidate(systemKey(systemId)),
+        scope.invalidatePrefix(LIST_PREFIX),
+      ]);
+    },
+
+    scope,
+  };
+}

package/src/index.ts

@@ -18,6 +18,7 @@ import { catalogHooks } from "@checkstack/catalog-backend";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import { resolveRoute } from "@checkstack/common";
 import { incidentHooks } from "./hooks";
+import { createIncidentCache } from "./cache";
 
 // =============================================================================
 // Integration Event Payload Schemas
@@ -99,6 +100,10 @@ export default createBackendPlugin({
       pluginMetadata,
     );
 
+    let incidentCache:
+      | ReturnType<typeof createIncidentCache>
+      | undefined;
+
     env.registerInit({
       schema,
       deps: {
@@ -106,8 +111,16 @@ export default createBackendPlugin({
         rpc: coreServices.rpc,
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
+        cacheManager: coreServices.cacheManager,
       },
-      init: async ({ logger, database, rpc, rpcClient, signalService }) => {
+      init: async ({
+        logger,
+        database,
+        rpc,
+        rpcClient,
+        signalService,
+        cacheManager,
+      }) => {
         logger.debug("🔧 Initializing Incident Backend...");
 
         const catalogClient = rpcClient.forPlugin(CatalogApi);
@@ -116,12 +129,15 @@ export default createBackendPlugin({
         const service = new IncidentService(
           database as SafeDatabase<typeof schema>,
         );
+        const cache = createIncidentCache({ cacheManager, logger });
+        incidentCache = cache;
         const router = createRouter(
           service,
           signalService,
           catalogClient,
           authClient,
           logger,
+          cache,
         );
         rpc.registerRouter(router, incidentContract);
 
@@ -165,6 +181,7 @@ export default createBackendPlugin({
               `Cleaning up incident associations for deleted system: ${payload.systemId}`,
             );
             await service.removeSystemAssociations(payload.systemId);
+            await incidentCache?.invalidateSystem(payload.systemId);
           },
           { mode: "work-queue", workerGroup: "incident-system-cleanup" },
         );

package/src/router.ts

@@ -16,6 +16,7 @@ import type { InferClient } from "@checkstack/common";
 import { incidentHooks } from "./hooks";
 import { notifyAffectedSystems } from "./notifications";
 import type { IncidentUpdate } from "@checkstack/incident-common";
+import type { IncidentCache } from "./cache";
 
 export function createRouter(
   service: IncidentService,
@@ -23,6 +24,7 @@ export function createRouter(
   catalogClient: InferClient<typeof CatalogApi>,
   authClient: InferClient<typeof AuthApi>,
   logger: Logger,
+  cache: IncidentCache,
 ) {
   /**
    * Resolve user IDs to profile names for a list of updates.
@@ -58,46 +60,82 @@ export function createRouter(
     }));
   }
 
+  /**
+   * Fetch system names for a list of system IDs.
+   */
+  async function resolveSystemNames(
+    systemIds: string[],
+  ): Promise<Map<string, string>> {
+    const systemNames = new Map<string, string>();
+    if (systemIds.length === 0) return systemNames;
+
+    await Promise.all(
+      [...new Set(systemIds)].map(async (systemId) => {
+        try {
+          const system = await catalogClient.getSystem({ systemId });
+          if (system?.name) {
+            systemNames.set(systemId, system.name);
+          }
+        } catch {
+          // System not found, skip
+        }
+      }),
+    );
+    return systemNames;
+  }
+
   const os = implement(incidentContract)
     .$context<RpcContext>()
     .use(autoAuthMiddleware);
 
   return os.router({
     listIncidents: os.listIncidents.handler(async ({ input }) => {
-      return { incidents: await service.listIncidents(input ?? {}) };
+      return {
+        incidents: await cache.wrapList(input ?? {}, () =>
+          service.listIncidents(input ?? {}),
+        ),
+      };
     }),
 
     getIncident: os.getIncident.handler(async ({ input }) => {
-      const result = await service.getIncident(input.id);
+      const result = await cache.wrapIncident(input.id, () =>
+        service.getIncident(input.id),
+      );
       if (!result) {
         // eslint-disable-next-line unicorn/no-null -- oRPC contract requires null for missing values
         return null;
       }
-      // Resolve user names for updates
+      // User-name resolution stays outside the cache: it's a foreign-system
+      // lookup with its own freshness needs and is cheap relative to the
+      // incident query.
       const updatesWithNames = await resolveUserNames(result.updates);
       return { ...result, updates: updatesWithNames };
     }),
 
     getIncidentsForSystem: os.getIncidentsForSystem.handler(
       async ({ input }) => {
-        return service.getIncidentsForSystem(input.systemId);
+        return cache.wrapSystem(input.systemId, () =>
+          service.getIncidentsForSystem(input.systemId),
+        );
       },
     ),
 
     getBulkIncidentsForSystems: os.getBulkIncidentsForSystems.handler(
       async ({ input }) => {
+        // Per-entity caching: each system's incidents are cached individually
+        // so dashboards with overlapping (but non-identical) system sets share
+        // cache entries. See ./cache.ts for the key/TTL/invalidation contract.
         const incidents: Record<
           string,
           Awaited<ReturnType<typeof service.getIncidentsForSystem>>
         > = {};
-
-        // Fetch incidents for each system in parallel
         await Promise.all(
           input.systemIds.map(async (systemId) => {
-            incidents[systemId] = await service.getIncidentsForSystem(systemId);
+            incidents[systemId] = await cache.wrapSystem(systemId, () =>
+              service.getIncidentsForSystem(systemId),
+            );
           }),
         );
-
         return { incidents };
       },
     ),
@@ -107,6 +145,14 @@ export function createRouter(
         context.user && "id" in context.user ? context.user.id : undefined;
       const result = await service.createIncident(input, userId);
 
+      // Invalidate before signal so any frontend that refetches in response
+      // sees fresh data. The mutation invariant for every handler in this
+      // file is: db.write → cache.invalidate (await) → signals.emit.
+      await cache.invalidateForMutation({
+        incidentId: result.id,
+        systemIds: result.systemIds,
+      });
+
       // Broadcast signal for realtime updates
       await signalService.broadcast(INCIDENT_UPDATED, {
         incidentId: result.id,
@@ -126,12 +172,14 @@ export function createRouter(
       });
 
       // Send notifications to system subscribers
+      const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,
         systemIds: result.systemIds,
+        systemNames,
         action: "created",
         severity: result.severity,
       });
@@ -145,6 +193,11 @@ export function createRouter(
         throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
       }
 
+      await cache.invalidateForMutation({
+        incidentId: result.id,
+        systemIds: result.systemIds,
+      });
+
       // Broadcast signal for realtime updates
       await signalService.broadcast(INCIDENT_UPDATED, {
         incidentId: result.id,
@@ -163,12 +216,14 @@ export function createRouter(
       });
 
       // Send notifications to system subscribers
+      const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,
         systemIds: result.systemIds,
+        systemNames,
         action: "updated",
         severity: result.severity,
       });
@@ -188,9 +243,15 @@ export function createRouter(
 
       const result = await service.addUpdate(input, userId);
 
-      // Get incident to broadcast with correct systemIds
+      // Read post-write state directly from the service so the broadcast
+      // payload is fresh; the cache is invalidated below before the signal.
       const incident = await service.getIncident(input.incidentId);
       if (incident) {
+        await cache.invalidateForMutation({
+          incidentId: input.incidentId,
+          systemIds: incident.systemIds,
+        });
+
         await signalService.broadcast(INCIDENT_UPDATED, {
           incidentId: input.incidentId,
           systemIds: incident.systemIds,
@@ -232,12 +293,14 @@ export function createRouter(
             notificationAction = "updated";
           }
 
+          const systemNames = await resolveSystemNames(incident.systemIds);
           await notifyAffectedSystems({
             catalogClient,
             logger,
             incidentId: input.incidentId,
             incidentTitle: incident.title,
             systemIds: incident.systemIds,
+            systemNames,
             action: notificationAction,
             severity: incident.severity,
           });
@@ -259,6 +322,11 @@ export function createRouter(
         throw new ORPCError("NOT_FOUND", { message: "Incident not found" });
       }
 
+      await cache.invalidateForMutation({
+        incidentId: result.id,
+        systemIds: result.systemIds,
+      });
+
       // Broadcast signal for realtime updates
       await signalService.broadcast(INCIDENT_UPDATED, {
         incidentId: result.id,
@@ -276,12 +344,14 @@ export function createRouter(
       });
 
       // Send notifications to system subscribers
+      const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,
         systemIds: result.systemIds,
+        systemNames,
         action: "resolved",
         severity: result.severity,
       });
@@ -294,6 +364,11 @@ export function createRouter(
       const incident = await service.getIncident(input.id);
       const success = await service.deleteIncident(input.id);
       if (success && incident) {
+        await cache.invalidateForMutation({
+          incidentId: input.id,
+          systemIds: incident.systemIds,
+        });
+
         await signalService.broadcast(INCIDENT_UPDATED, {
           incidentId: input.id,
           systemIds: incident.systemIds,