@checkstack/announcement-backend 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # @checkstack/announcement-backend
 
+## 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]
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/cache-utils@0.2.0
+  - @checkstack/backend-api@0.13.0
+  - @checkstack/announcement-common@0.2.2
+  - @checkstack/auth-backend@0.4.20
+  - @checkstack/command-backend@0.1.20
+  - @checkstack/signal-common@0.1.10
+
 ## 0.2.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/announcement-backend",
-  "version": "0.2.5",
+  "version": "0.3.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/announcement-common": "0.2.1",
-    "@checkstack/auth-backend": "0.4.18",
+    "@checkstack/auth-backend": "0.4.19",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/common": "0.6.5",
     "@checkstack/signal-common": "0.1.9",

package/src/cache.ts

@@ -0,0 +1,73 @@
+import type { CacheManager } from "@checkstack/cache-api";
+import {
+  createCachedScope,
+  type CachedScope,
+} from "@checkstack/cache-utils";
+import type { Logger } from "@checkstack/backend-api";
+
+/** 45s — admin-driven, infrequently changing data. */
+const ANNOUNCEMENT_TTL_MS = 45_000;
+
+const ACTIVE_PREFIX = "active:";
+const LIST_ALL_KEY = "list:all";
+
+const activeKeyForUser = (userId: string, includeDismissed: boolean): string =>
+  `${ACTIVE_PREFIX}user:${userId}:${includeDismissed ? "all" : "undismissed"}`;
+const activeKeyForAnon = (includeDismissed: boolean): string =>
+  `${ACTIVE_PREFIX}anon:${includeDismissed ? "all" : "undismissed"}`;
+const userActivePrefix = (userId: string): string =>
+  `${ACTIVE_PREFIX}user:${userId}:`;
+
+export interface AnnouncementCache {
+  wrapActive: <T>(
+    props: { userId: string | undefined; includeDismissed: boolean },
+    loader: () => Promise<T>,
+  ) => Promise<T>;
+  wrapListAll: <T>(loader: () => Promise<T>) => Promise<T>;
+
+  /** Drop all cached active-announcement results for every user. */
+  invalidateAllActive: () => Promise<number>;
+
+  /** Drop just one user's active-announcement cache (e.g. on dismissal). */
+  invalidateUserActive: (userId: string) => Promise<number>;
+
+  /** Drop the admin list cache. */
+  invalidateListAll: () => Promise<void>;
+
+  scope: CachedScope;
+}
+
+export function createAnnouncementCache({
+  cacheManager,
+  logger,
+}: {
+  cacheManager: CacheManager;
+  logger: Logger;
+}): AnnouncementCache {
+  const scope = createCachedScope({
+    cacheManager,
+    pluginId: "announcement",
+    defaultTtlMs: ANNOUNCEMENT_TTL_MS,
+    onError: (op: string, error: unknown) => {
+      logger.warn(`announcement cache ${op} failed: ${String(error)}`);
+    },
+  });
+
+  return {
+    wrapActive: ({ userId, includeDismissed }, loader) => {
+      const key =
+        userId === undefined
+          ? activeKeyForAnon(includeDismissed)
+          : activeKeyForUser(userId, includeDismissed);
+      return scope.wrap(key, loader);
+    },
+    wrapListAll: (loader) => scope.wrap(LIST_ALL_KEY, loader),
+
+    invalidateAllActive: () => scope.invalidatePrefix(ACTIVE_PREFIX),
+    invalidateUserActive: (userId) =>
+      scope.invalidatePrefix(userActivePrefix(userId)),
+    invalidateListAll: () => scope.invalidate(LIST_ALL_KEY),
+
+    scope,
+  };
+}

package/src/index.ts

@@ -10,6 +10,7 @@ import { resolveRoute } from "@checkstack/common";
 import { eq } from "drizzle-orm";
 import * as schema from "./schema";
 import { createAnnouncementRouter } from "./router";
+import { createAnnouncementCache, type AnnouncementCache } from "./cache";
 import { authHooks } from "@checkstack/auth-backend";
 import { registerSearchProvider } from "@checkstack/command-backend";
 import type { SafeDatabase } from "@checkstack/backend-api";
@@ -21,18 +22,24 @@ export default createBackendPlugin({
     // Register access rules
     env.registerAccessRules(announcementAccessRules);
 
+    let announcementCache: AnnouncementCache | undefined;
+
     env.registerInit({
       schema,
       deps: {
         rpc: coreServices.rpc,
         logger: coreServices.logger,
         signalService: coreServices.signalService,
+        cacheManager: coreServices.cacheManager,
       },
-      init: async ({ database, rpc, signalService }) => {
+      init: async ({ database, rpc, signalService, logger, cacheManager }) => {
         const db = database as SafeDatabase<typeof schema>;
 
+        const cache = createAnnouncementCache({ cacheManager, logger });
+        announcementCache = cache;
+
         // Create and register the announcement router
-        const router = createAnnouncementRouter(db, signalService);
+        const router = createAnnouncementRouter(db, signalService, cache);
         rpc.registerRouter(router, announcementContract);
 
         // Register commands in the command palette
@@ -74,6 +81,7 @@ export default createBackendPlugin({
             await db
               .delete(schema.announcementDismissals)
               .where(eq(schema.announcementDismissals.userId, userId));
+            await announcementCache?.invalidateUserActive(userId);
             logger.debug(
               `Cleaned up announcement dismissals for user: ${userId}`,
             );

package/src/router.test.ts

@@ -4,6 +4,16 @@ import { createMockRpcContext } from "@checkstack/backend-api";
 import { createMockDb } from "@checkstack/test-utils-backend";
 import { ANNOUNCEMENT_UPDATED } from "@checkstack/announcement-common";
 import { call } from "@orpc/server";
+import type { AnnouncementCache } from "./cache";
+
+const passthroughCache: AnnouncementCache = {
+  wrapActive: (_props, loader) => loader(),
+  wrapListAll: (loader) => loader(),
+  invalidateAllActive: async () => 0,
+  invalidateUserActive: async () => 0,
+  invalidateListAll: async () => {},
+  scope: {} as AnnouncementCache["scope"],
+};
 
 describe("Announcement Router", () => {
   const adminUser = {
@@ -48,7 +58,11 @@ describe("Announcement Router", () => {
   beforeEach(() => {
     mockDb = createMockDb();
     mockSignalService.broadcast.mockClear();
-    router = createAnnouncementRouter(mockDb as never, mockSignalService);
+    router = createAnnouncementRouter(
+      mockDb as never,
+      mockSignalService,
+      passthroughCache,
+    );
   });
 
   // ---------------------------------------------------------------------------

package/src/router.ts

@@ -13,6 +13,7 @@ import {
 import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import { eq, and, or, lte, gte, isNull } from "drizzle-orm";
+import type { AnnouncementCache } from "./cache";
 
 type AnnouncementDb = SafeDatabase<typeof schema>;
 
@@ -44,6 +45,7 @@ function toAnnouncement(
 export function createAnnouncementRouter(
   db: AnnouncementDb,
   signalService: SignalService,
+  cache: AnnouncementCache,
 ) {
   const os = implement(announcementContract)
     .$context<RpcContext>()
@@ -55,51 +57,59 @@ export function createAnnouncementRouter(
     // -------------------------------------------------------------------------
     getActiveAnnouncements: os.getActiveAnnouncements.handler(
       async ({ input, context }) => {
-        const now = new Date();
         const includeDismissed = input?.includeDismissed ?? false;
-
-        // Base query: active announcements within their time window
-        const rows = await db
-          .select()
-          .from(schema.announcements)
-          .where(
-            and(
-              eq(schema.announcements.active, true),
-              or(
-                isNull(schema.announcements.startsAt),
-                lte(schema.announcements.startsAt, now),
-              ),
-              or(
-                isNull(schema.announcements.expiresAt),
-                gte(schema.announcements.expiresAt, now),
-              ),
-            ),
-          );
-
-        let announcements = rows.map((row) => toAnnouncement(row));
-
-        // If the caller is authenticated, filter out their dismissed announcements
-        // (unless includeDismissed is explicitly requested, e.g. for dashboard)
         const user = context.user;
-        if (!includeDismissed && user && "id" in user) {
-          const userId = (user as RealUser).id;
-          const dismissals = await db
-            .select({ announcementId: schema.announcementDismissals.announcementId })
-            .from(schema.announcementDismissals)
-            .where(eq(schema.announcementDismissals.userId, userId));
-
-          const dismissedIds = new Set(dismissals.map((d) => d.announcementId));
-          announcements = announcements.filter((a) => !dismissedIds.has(a.id));
-        }
-
-        // Filter visibility for unauthenticated users
-        if (!user) {
-          announcements = announcements.filter(
-            (a) => a.visibility === "all",
-          );
-        }
-
-        return { announcements };
+        const userId =
+          user && "id" in user ? (user as RealUser).id : undefined;
+
+        return cache.wrapActive({ userId, includeDismissed }, async () => {
+          const now = new Date();
+
+          // Base query: active announcements within their time window
+          const rows = await db
+            .select()
+            .from(schema.announcements)
+            .where(
+              and(
+                eq(schema.announcements.active, true),
+                or(
+                  isNull(schema.announcements.startsAt),
+                  lte(schema.announcements.startsAt, now),
+                ),
+                or(
+                  isNull(schema.announcements.expiresAt),
+                  gte(schema.announcements.expiresAt, now),
+                ),
+              ),
+            );
+
+          let announcements = rows.map((row) => toAnnouncement(row));
+
+          // If the caller is authenticated, filter out their dismissed announcements
+          // (unless includeDismissed is explicitly requested, e.g. for dashboard)
+          if (!includeDismissed && userId !== undefined) {
+            const dismissals = await db
+              .select({ announcementId: schema.announcementDismissals.announcementId })
+              .from(schema.announcementDismissals)
+              .where(eq(schema.announcementDismissals.userId, userId));
+
+            const dismissedIds = new Set(
+              dismissals.map((d) => d.announcementId),
+            );
+            announcements = announcements.filter(
+              (a) => !dismissedIds.has(a.id),
+            );
+          }
+
+          // Filter visibility for unauthenticated users
+          if (userId === undefined) {
+            announcements = announcements.filter(
+              (a) => a.visibility === "all",
+            );
+          }
+
+          return { announcements };
+        });
       },
     ),
 
@@ -132,20 +142,25 @@ export function createAnnouncementRouter(
             dismissedAt: new Date(),
           })
           .onConflictDoNothing();
+
+        // Drop only this user's cache — other users' dismissals are unaffected.
+        await cache.invalidateUserActive(userId);
       },
     ),
 
     // -------------------------------------------------------------------------
     // Admin: List all announcements
     // -------------------------------------------------------------------------
-    listAllAnnouncements: os.listAllAnnouncements.handler(async () => {
-      const rows = await db
-        .select()
-        .from(schema.announcements)
-        .orderBy(schema.announcements.createdAt);
+    listAllAnnouncements: os.listAllAnnouncements.handler(async () =>
+      cache.wrapListAll(async () => {
+        const rows = await db
+          .select()
+          .from(schema.announcements)
+          .orderBy(schema.announcements.createdAt);
 
-      return { announcements: rows.map((row) => toAnnouncement(row)) };
-    }),
+        return { announcements: rows.map((row) => toAnnouncement(row)) };
+      }),
+    ),
 
     // -------------------------------------------------------------------------
     // Admin: Create announcement
@@ -177,6 +192,11 @@ export function createAnnouncementRouter(
 
         const announcement = toAnnouncement(row);
 
+        await Promise.all([
+          cache.invalidateAllActive(),
+          cache.invalidateListAll(),
+        ]);
+
         await signalService.broadcast(ANNOUNCEMENT_UPDATED, {
           announcementId: announcement.id,
           action: "created",
@@ -241,6 +261,11 @@ export function createAnnouncementRouter(
         .returning({ id: schema.announcements.id });
 
       if (result.length > 0) {
+        await Promise.all([
+          cache.invalidateAllActive(),
+          cache.invalidateListAll(),
+        ]);
+
         await signalService.broadcast(ANNOUNCEMENT_UPDATED, {
           announcementId: input.id,
           action: "deleted",