@checkstack/notification-backend 0.1.23 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # @checkstack/notification-backend
 
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-common@0.2.0
+  - @checkstack/notification-common@0.3.0
+  - @checkstack/backend-api@0.13.1
+  - @checkstack/auth-backend@0.4.21
+  - @checkstack/cache-api@0.2.1
+  - @checkstack/queue-api@0.2.15
+  - @checkstack/cache-utils@0.2.1
+
+## 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]
+- 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/notification-common@0.2.9
+  - @checkstack/signal-common@0.1.10
+  - @checkstack/queue-api@0.2.14
+
 ## 0.1.23
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-backend",
-  "version": "0.1.23",
+  "version": "0.2.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,22 +14,24 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/notification-common": "0.2.8",
-    "@checkstack/backend-api": "0.12.0",
-    "@checkstack/signal-common": "0.1.9",
-    "@checkstack/queue-api": "0.2.13",
-    "@checkstack/auth-backend": "0.4.18",
-    "@checkstack/auth-common": "0.6.1",
+    "@checkstack/notification-common": "0.2.9",
+    "@checkstack/backend-api": "0.13.0",
+    "@checkstack/cache-api": "0.2.0",
+    "@checkstack/cache-utils": "0.2.0",
+    "@checkstack/signal-common": "0.1.10",
+    "@checkstack/queue-api": "0.2.14",
+    "@checkstack/auth-backend": "0.4.20",
+    "@checkstack/auth-common": "0.6.3",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
-    "@checkstack/common": "0.6.5",
+    "@checkstack/common": "0.7.0",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.4",
     "@checkstack/scripts": "0.1.2",
     "@checkstack/tsconfig": "0.0.5",
-    "@checkstack/test-utils-backend": "0.1.19",
+    "@checkstack/test-utils-backend": "0.1.20",
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0"
   }

package/src/cache.ts

@@ -0,0 +1,101 @@
+import type { CacheManager } from "@checkstack/cache-api";
+import {
+  createCachedScope,
+  type CachedScope,
+} from "@checkstack/cache-utils";
+import type { Logger } from "@checkstack/backend-api";
+
+/**
+ * 15s. The NotificationBell on every page polls `getUnreadCount` every 30s,
+ * so even short caching provides huge savings. Mutations send signals to the
+ * affected users which trigger frontend refetches — invalidation must
+ * complete before the signal so the refetch hits a fresh DB read.
+ */
+const NOTIFICATION_TTL_MS = 15_000;
+
+const UNREAD_PREFIX = "unread:";
+const NOTIFS_PREFIX = "notifs:";
+const SUBS_PREFIX = "subs:";
+
+const unreadKey = (userId: string): string => `${UNREAD_PREFIX}${userId}`;
+const subsKey = (userId: string): string => `${SUBS_PREFIX}${userId}`;
+
+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 notifsKey = (userId: string, filters: unknown): string =>
+  `${NOTIFS_PREFIX}${userId}:${stableStringify(filters ?? {})}`;
+const notifsPrefixForUser = (userId: string): string =>
+  `${NOTIFS_PREFIX}${userId}:`;
+
+export interface NotificationCache {
+  wrapUnread: <T>(userId: string, loader: () => Promise<T>) => Promise<T>;
+  wrapNotifications: <T>(
+    userId: string,
+    filters: unknown,
+    loader: () => Promise<T>,
+  ) => Promise<T>;
+  wrapSubscriptions: <T>(
+    userId: string,
+    loader: () => Promise<T>,
+  ) => Promise<T>;
+
+  /**
+   * Drop unread + notifications cache for a single user. Used after a
+   * mutation that adds/removes/marks-as-read a notification for that user.
+   */
+  invalidateForUser: (userId: string) => Promise<void>;
+
+  /** Drop subscriptions cache for one user (subscribe/unsubscribe). */
+  invalidateSubscriptions: (userId: string) => Promise<void>;
+
+  scope: CachedScope;
+}
+
+export function createNotificationCache({
+  cacheManager,
+  logger,
+}: {
+  cacheManager: CacheManager;
+  logger: Logger;
+}): NotificationCache {
+  const scope = createCachedScope({
+    cacheManager,
+    pluginId: "notification",
+    defaultTtlMs: NOTIFICATION_TTL_MS,
+    onError: (op: string, error: unknown) => {
+      logger.warn(`notification cache ${op} failed: ${String(error)}`);
+    },
+  });
+
+  return {
+    wrapUnread: (userId, loader) => scope.wrap(unreadKey(userId), loader),
+    wrapNotifications: (userId, filters, loader) =>
+      scope.wrap(notifsKey(userId, filters), loader),
+    wrapSubscriptions: (userId, loader) =>
+      scope.wrap(subsKey(userId), loader),
+
+    invalidateForUser: async (userId) => {
+      await Promise.all([
+        scope.invalidate(unreadKey(userId)),
+        scope.invalidatePrefix(notifsPrefixForUser(userId)),
+      ]);
+    },
+
+    invalidateSubscriptions: (userId) => scope.invalidate(subsKey(userId)),
+
+    scope,
+  };
+}

package/src/index.ts

@@ -21,6 +21,7 @@ import { eq } from "drizzle-orm";
 
 import * as schema from "./schema";
 import { createNotificationRouter } from "./router";
+import { createNotificationCache } from "./cache";
 import { authHooks } from "@checkstack/auth-backend";
 import { createOAuthCallbackHandler } from "./oauth-callback-handler";
 import { createStrategyService } from "./strategy-service";
@@ -157,6 +158,7 @@ export default createBackendPlugin({
         rpcClient: coreServices.rpcClient,
         config: coreServices.config,
         signalService: coreServices.signalService,
+        cacheManager: coreServices.cacheManager,
       },
       init: async ({
         logger,
@@ -165,6 +167,7 @@ export default createBackendPlugin({
         rpcClient,
         config,
         signalService,
+        cacheManager,
       }) => {
         logger.debug("🔔 Initializing Notification Backend...");
 
@@ -184,6 +187,8 @@ export default createBackendPlugin({
           env as unknown as { strategyService: typeof strategyService }
         ).strategyService = strategyService;
 
+        const cache = createNotificationCache({ cacheManager, logger });
+
         // Create and register the notification router with strategy registry
         const router = createNotificationRouter(
           db,
@@ -191,7 +196,8 @@ export default createBackendPlugin({
           signalService,
           strategyRegistry,
           rpcClient,
-          logger
+          logger,
+          cache,
         );
         rpc.registerRouter(router, notificationContract);
 

package/src/router.ts

@@ -18,6 +18,7 @@ import {
 } from "@checkstack/notification-common";
 import { AuthApi } from "@checkstack/auth-common";
 import type { SignalService } from "@checkstack/signal-common";
+import type { NotificationCache } from "./cache";
 import { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import {
@@ -95,7 +96,8 @@ export const createNotificationRouter = (
   signalService: SignalService,
   strategyRegistry: NotificationStrategyRegistry,
   rpcApi: RpcClient,
-  logger: Logger
+  logger: Logger,
+  cache: NotificationCache,
 ) => {
   // Create strategy service for config management
   const strategyService: StrategyService = createStrategyService({
@@ -269,39 +271,46 @@ export const createNotificationRouter = (
         // context.user is guaranteed to be RealUser by contract meta + autoAuthMiddleware
         const userId = (context.user as RealUser).id;
 
-        const result = await getUserNotifications(database, userId, {
-          limit: input.limit,
-          offset: input.offset,
-          unreadOnly: input.unreadOnly,
-        });
+        return cache.wrapNotifications(userId, input, async () => {
+          const result = await getUserNotifications(database, userId, {
+            limit: input.limit,
+            offset: input.offset,
+            unreadOnly: input.unreadOnly,
+          });
 
-        return {
-          notifications: result.notifications.map((n) => ({
-            id: n.id,
-            userId: n.userId,
-            title: n.title,
-            body: n.body,
-            action: n.action ?? undefined,
-            importance: n.importance as "info" | "warning" | "critical",
-            isRead: n.isRead,
-            groupId: n.groupId ?? undefined,
-            createdAt: n.createdAt,
-          })),
-          total: result.total,
-        };
+          return {
+            notifications: result.notifications.map((n) => ({
+              id: n.id,
+              userId: n.userId,
+              title: n.title,
+              body: n.body,
+              action: n.action ?? undefined,
+              importance: n.importance as "info" | "warning" | "critical",
+              isRead: n.isRead,
+              groupId: n.groupId ?? undefined,
+              createdAt: n.createdAt,
+            })),
+            total: result.total,
+          };
+        });
       }
     ),
 
     getUnreadCount: os.getUnreadCount.handler(async ({ context }) => {
       const userId = (context.user as RealUser).id;
-      const count = await getUnreadCount(database, userId);
-      return { count };
+      return cache.wrapUnread(userId, async () => {
+        const count = await getUnreadCount(database, userId);
+        return { count };
+      });
     }),
 
     markAsRead: os.markAsRead.handler(async ({ input, context }) => {
       const userId = (context.user as RealUser).id;
       await markAsRead(database, userId, input.notificationId);
 
+      // Mutation invariant: db.write → cache.invalidate (await) → signal.
+      await cache.invalidateForUser(userId);
+
       // Send signal to update NotificationBell in realtime
       void signalService.sendToUser(NOTIFICATION_READ, userId, {
         notificationId: input.notificationId,
@@ -312,6 +321,7 @@ export const createNotificationRouter = (
       async ({ input, context }) => {
         const userId = (context.user as RealUser).id;
         await deleteNotification(database, userId, input.notificationId);
+        await cache.invalidateForUser(userId);
       }
     ),
 
@@ -333,11 +343,9 @@ export const createNotificationRouter = (
 
     getSubscriptions: os.getSubscriptions.handler(async ({ context }) => {
       const userId = (context.user as RealUser).id;
-      const subscriptions = await getEnrichedUserSubscriptions(
-        database,
-        userId
+      return cache.wrapSubscriptions(userId, () =>
+        getEnrichedUserSubscriptions(database, userId),
       );
-      return subscriptions;
     }),
 
     subscribe: os.subscribe.handler(async ({ input, context }) => {
@@ -354,11 +362,13 @@ export const createNotificationRouter = (
         }
         throw error;
       }
+      await cache.invalidateSubscriptions(userId);
     }),
 
     unsubscribe: os.unsubscribe.handler(async ({ input, context }) => {
       const userId = (context.user as RealUser).id;
       await unsubscribeFromGroup(database, userId, input.groupId);
+      await cache.invalidateSubscriptions(userId);
     }),
 
     // ==========================================================================
@@ -465,6 +475,12 @@ export const createNotificationRouter = (
           userId: schema.notifications.userId,
         });
 
+      // Drop each affected user's cache before signaling, so the
+      // NotificationBell's refetch sees the new unread count.
+      await Promise.all(
+        userIds.map((userId) => cache.invalidateForUser(userId)),
+      );
+
       // Send realtime signals to each user
       for (const notification of inserted) {
         void signalService.sendToUser(
@@ -527,6 +543,10 @@ export const createNotificationRouter = (
           userId: schema.notifications.userId,
         });
 
+      await Promise.all(
+        subscribers.map((sub) => cache.invalidateForUser(sub.userId)),
+      );
+
       // Send realtime signals to each subscriber
       for (const notification of inserted) {
         void signalService.sendToUser(