@checkstack/backend 0.6.6 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,116 @@
 # @checkstack/backend
 
+## 0.7.0
+
+### Minor Changes
+
+- 8d1ef12: ## Infrastructure Configuration Shell & Cache System
+
+  ### New Packages
+
+  - **`@checkstack/cache-api`**: Core cache abstractions — `CacheProvider` interface, `createScopedCache` factory for plugin key isolation, `CachePlugin`/`CacheManager` lifecycle interfaces.
+  - **`@checkstack/cache-common`**: Shared cache types, RPC contract (`getPlugins`, `getConfiguration`, `updateConfiguration`), access rules, and plugin metadata.
+  - **`@checkstack/cache-backend`**: Cache settings RPC router — exposes plugin discovery, configuration read/write endpoints with access-gated authorization.
+  - **`@checkstack/cache-frontend`**: Cache configuration tab component for the Infrastructure Settings page.
+  - **`@checkstack/infrastructure-common`**: Infrastructure tab registry, routes, and shared types for the IDE-style configuration shell.
+  - **`@checkstack/infrastructure-frontend`**: Infrastructure Settings page with vertical tab bar, per-tab access control, and user menu integration.
+
+  ### Modified Packages
+
+  - **`@checkstack/backend-api`**: Added `cachePluginRegistry` and `cacheManager` to `RpcContext` and `coreServices`.
+  - **`@checkstack/backend`**: Registered cache services in boot sequence, added cache config loading, extended dependency sorter for cache plugin ordering.
+  - **`@checkstack/queue-frontend`**: Refactored from standalone `/queue/config` route to an infrastructure tab. Queue settings now live inside the Infrastructure Settings page.
+
+  ### Architecture
+
+  The former monolithic Queue Config page is replaced by a pluggable Infrastructure Settings shell (`/infrastructure/config`). Plugins register configuration tabs via `registerInfrastructureTab()` with their own access rules, icons, and components. The shell evaluates per-tab access and only renders tabs the user can see.
+
+### Patch 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.
+
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/backend-api@0.13.0
+  - @checkstack/api-docs-common@0.1.10
+  - @checkstack/auth-common@0.6.3
+  - @checkstack/signal-backend@0.1.20
+  - @checkstack/signal-common@0.1.10
+  - @checkstack/queue-api@0.2.14
+
 ## 0.6.6
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "checkstack": {
     "type": "backend"
   },
@@ -14,10 +14,11 @@
   },
   "dependencies": {
     "@checkstack/api-docs-common": "0.1.9",
-    "@checkstack/auth-common": "0.6.1",
+    "@checkstack/auth-common": "0.6.2",
     "@checkstack/backend-api": "0.12.0",
     "@checkstack/common": "0.6.5",
     "@checkstack/drizzle-helper": "0.0.4",
+    "@checkstack/cache-api": "0.1.0",
     "@checkstack/queue-api": "0.2.13",
     "@checkstack/signal-backend": "0.1.19",
     "@checkstack/signal-common": "0.1.9",

package/src/index.ts

@@ -13,6 +13,8 @@ import { eq, and } from "drizzle-orm";
 import { PluginLocalInstaller } from "./services/plugin-installer";
 import { QueuePluginRegistryImpl } from "./services/queue-plugin-registry";
 import { QueueManagerImpl } from "./services/queue-manager";
+import { CachePluginRegistryImpl } from "./services/cache-plugin-registry";
+import { CacheManagerImpl } from "./services/cache-manager";
 import {
   createWebSocketHandler,
   SignalServiceImpl,
@@ -278,6 +280,20 @@ const init = async () => {
   );
   pluginManager.registerService(coreServices.queueManager, queueManager);
 
+  // 1.8. Register Cache Services
+  rootLogger.debug("Registering cache services...");
+  const cacheRegistry = new CachePluginRegistryImpl();
+  const cacheManager = new CacheManagerImpl(
+    cacheRegistry,
+    configService,
+    rootLogger
+  );
+  pluginManager.registerService(
+    coreServices.cachePluginRegistry,
+    cacheRegistry
+  );
+  pluginManager.registerService(coreServices.cacheManager, cacheManager);
+
   // Serve static assets for runtime frontend plugins only
   // Backend plugins don't need public assets - only frontend plugins do
   // e.g. /assets/plugins/my-plugin-frontend/index.js -> runtime_plugins/node_modules/my-plugin-frontend/dist/index.js
@@ -378,6 +394,10 @@ const init = async () => {
   // 7. Start config polling for multi-instance coordination
   queueManager.startPolling(5000);
 
+  // 8. Load Cache Configuration AFTER plugins (cache plugins register first)
+  rootLogger.info("📦 Loading cache configuration...");
+  await cacheManager.loadConfiguration();
+
   // 9. Setup plugin lifecycle signal broadcasting to frontend
   // Only broadcast for frontend plugins (plugins ending with -frontend)
   await eventBus.subscribe(

package/src/plugin-manager/api-router.ts

@@ -13,6 +13,10 @@ import {
   type Hook,
 } from "@checkstack/backend-api";
 import type { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
+import type {
+  CachePluginRegistry,
+  CacheManager,
+} from "@checkstack/cache-api";
 import type { ServiceRegistry } from "../services/service-registry";
 import type { EventBus } from "@checkstack/backend-api";
 import type { PluginMetadata } from "@checkstack/common";
@@ -98,6 +102,10 @@ export function createApiRouteHandler({
       coreServices.queuePluginRegistry,
     );
     const queueManager = await getService(coreServices.queueManager);
+    const cachePluginRegistry = await getService(
+      coreServices.cachePluginRegistry,
+    );
+    const cacheManager = await getService(coreServices.cacheManager);
     const eventBus = await getService(coreServices.eventBus);
 
     if (
@@ -109,6 +117,8 @@ export function createApiRouteHandler({
       !collectorRegistry ||
       !queuePluginRegistry ||
       !queueManager ||
+      !cachePluginRegistry ||
+      !cacheManager ||
       !eventBus
     ) {
       return c.json({ error: "Core services not initialized" }, 500);
@@ -139,6 +149,8 @@ export function createApiRouteHandler({
       collectorRegistry: collectorRegistry as CollectorRegistry,
       queuePluginRegistry: queuePluginRegistry as QueuePluginRegistry,
       queueManager: queueManager as QueueManager,
+      cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
+      cacheManager: cacheManager as CacheManager,
       user,
       emitHook,
     };

package/src/plugin-manager/dependency-sorter.ts

@@ -30,11 +30,16 @@ export function sortPlugins({
 
   // Track queue plugin providers (plugins that depend on queuePluginRegistry)
   const queuePluginProviders = new Set<string>();
+  // Track cache plugin providers (plugins that depend on cachePluginRegistry)
+  const cachePluginProviders = new Set<string>();
   for (const p of pendingInits) {
     for (const [, ref] of Object.entries(p.deps)) {
       if (ref.id === coreServices.queuePluginRegistry.id) {
         queuePluginProviders.add(p.metadata.pluginId);
       }
+      if (ref.id === coreServices.cachePluginRegistry.id) {
+        cachePluginProviders.add(p.metadata.pluginId);
+      }
     }
   }
 
@@ -72,6 +77,25 @@ export function sortPlugins({
         }
       }
     }
+
+    // Special handling: if this plugin uses cacheManager, it must wait for all cache plugin providers
+    const usesCacheManager = Object.values(p.deps).some(
+      (ref) => ref.id === coreServices.cacheManager.id
+    );
+    if (usesCacheManager) {
+      for (const cpp of cachePluginProviders) {
+        if (cpp !== consumerId) {
+          if (!graph.has(cpp)) {
+            graph.set(cpp, []);
+          }
+          // Add edge: cache plugin provider -> cache consumer
+          if (!graph.get(cpp)!.includes(consumerId)) {
+            graph.get(cpp)!.push(consumerId);
+            inDegree.set(consumerId, (inDegree.get(consumerId) || 0) + 1);
+          }
+        }
+      }
+    }
   }
 
   const queue: string[] = [];

package/src/rpc-rest-compat.test.ts

@@ -58,6 +58,13 @@ describe("RPC REST Compatibility", () => {
       getActivePlugin: () => "none",
       getQueue: () => ({}),
     } as any);
+    pluginManager.registerService(coreServices.cachePluginRegistry, {
+      getPlugins: () => [],
+    } as any);
+    pluginManager.registerService(coreServices.cacheManager, {
+      getActivePlugin: () => "memory",
+      getProvider: () => ({}),
+    } as any);
 
     // 4. Mount the plugins
     await pluginManager.loadPlugins(app);

package/src/services/cache-manager.ts

@@ -0,0 +1,191 @@
+import type { CacheManager, CacheProvider } from "@checkstack/cache-api";
+import type { CachePluginRegistryImpl } from "./cache-plugin-registry";
+import type { Logger, ConfigService } from "@checkstack/backend-api";
+import { z } from "zod";
+import { extractErrorMessage } from "@checkstack/common";
+
+/**
+ * Schema for the active cache plugin pointer.
+ * Stored in the ConfigService for persistence and multi-instance coordination.
+ */
+const activeCachePointerSchema = z.object({
+  activePluginId: z.string(),
+  version: z.number(),
+});
+
+type ActiveCachePointer = z.infer<typeof activeCachePointerSchema>;
+
+/**
+ * A no-op CacheProvider used before any backend is configured.
+ * All operations are safe to call but behave as if the cache is empty.
+ */
+const nullProvider: CacheProvider = {
+  // eslint-disable-next-line unicorn/no-useless-undefined
+  get: async () => undefined,
+  set: async () => {},
+  delete: async () => {},
+  deleteByPrefix: async () => 0,
+  has: async () => false,
+};
+
+/**
+ * CacheManagerImpl handles cache provider lifecycle and backend switching.
+ *
+ * Simpler than QueueManagerImpl — no proxy pattern needed since cache is
+ * stateless key/value. The active provider is replaced atomically on backend switch.
+ */
+export class CacheManagerImpl implements CacheManager {
+  private activePluginId: string = "memory";
+  private activeConfig: unknown = {
+    maxEntries: 10_000,
+    sweepIntervalMs: 60_000,
+  };
+  private configVersion: number = 0;
+  private activeProvider: CacheProvider = nullProvider;
+
+  constructor(
+    private registry: CachePluginRegistryImpl,
+    private configService: ConfigService,
+    private logger: Logger,
+  ) {}
+
+  async loadConfiguration(): Promise<void> {
+    try {
+      const pointer = await this.configService.get<ActiveCachePointer>(
+        "cache:active",
+        activeCachePointerSchema,
+        1,
+      );
+
+      if (pointer) {
+        this.activePluginId = pointer.activePluginId;
+        this.configVersion = pointer.version;
+
+        const plugin = this.registry.getPlugin(this.activePluginId);
+        if (plugin) {
+          const config = await this.configService.get(
+            this.activePluginId,
+            plugin.configSchema,
+            plugin.configVersion,
+          );
+
+          if (config) {
+            this.activeConfig = config;
+          }
+        }
+
+        this.logger.info(
+          `📦 Loaded cache configuration: plugin=${this.activePluginId}, version=${this.configVersion}`,
+        );
+      } else {
+        this.logger.info(
+          `📦 No cache configuration found, using default: plugin=${this.activePluginId}`,
+        );
+      }
+
+      // Initialize the active provider
+      this.initializeProvider();
+    } catch (error) {
+      this.logger.error("Failed to load cache configuration", error);
+      // Continue with defaults — nullProvider is already set
+    }
+  }
+
+  private initializeProvider(): void {
+    const plugin = this.registry.getPlugin(this.activePluginId);
+    if (!plugin) {
+      this.logger.warn(
+        `Cache plugin '${this.activePluginId}' not found, using null provider`,
+      );
+      return;
+    }
+
+    try {
+      this.activeProvider = plugin.createProvider(
+        this.activeConfig,
+        this.logger,
+      );
+    } catch (error) {
+      this.logger.error(
+        `Failed to create cache provider for '${this.activePluginId}'`,
+        error,
+      );
+    }
+  }
+
+  getProvider(): CacheProvider {
+    return this.activeProvider;
+  }
+
+  getActivePlugin(): string {
+    return this.activePluginId;
+  }
+
+  getActiveConfig(): unknown {
+    return this.activeConfig;
+  }
+
+  async setActiveBackend(pluginId: string, config: unknown): Promise<void> {
+    // 1. Validate plugin exists
+    const newPlugin = this.registry.getPlugin(pluginId);
+    if (!newPlugin) {
+      throw new Error(`Cache plugin '${pluginId}' not found`);
+    }
+
+    // 2. Validate config against schema
+    newPlugin.configSchema.parse(config);
+
+    // 3. Create new provider (acts as connection test)
+    this.logger.info("🔍 Testing new cache provider...");
+    let newProvider: CacheProvider;
+    try {
+      newProvider = newPlugin.createProvider(config, this.logger);
+      // Quick smoke test
+      await newProvider.set("__test__", true, 1000);
+      await newProvider.delete("__test__");
+      this.logger.info("✅ Cache provider test successful");
+    } catch (error) {
+      const message = extractErrorMessage(error);
+      this.logger.error(`❌ Cache provider test failed: ${message}`);
+      throw new Error(`Failed to create cache provider: ${message}`);
+    }
+
+    // 4. Stop old provider if it has a stop method
+    const oldProvider = this.activeProvider;
+    if ("stop" in oldProvider && typeof oldProvider.stop === "function") {
+      await (oldProvider as { stop: () => Promise<void> }).stop();
+    }
+
+    // 5. Switch to new provider
+    const oldPluginId = this.activePluginId;
+    this.activePluginId = pluginId;
+    this.activeConfig = config;
+    this.configVersion++;
+    this.activeProvider = newProvider;
+
+    // 6. Persist configuration
+    await this.configService.set(
+      pluginId,
+      newPlugin.configSchema,
+      newPlugin.configVersion,
+      config,
+    );
+
+    await this.configService.set("cache:active", activeCachePointerSchema, 1, {
+      activePluginId: pluginId,
+      version: this.configVersion,
+    });
+
+    this.logger.info(`✅ Cache backend switched: ${oldPluginId} → ${pluginId}`);
+  }
+
+  async shutdown(): Promise<void> {
+    this.logger.info("🛑 Shutting down cache provider...");
+    const provider = this.activeProvider;
+    if ("stop" in provider && typeof provider.stop === "function") {
+      await (provider as { stop: () => Promise<void> }).stop();
+    }
+    this.activeProvider = nullProvider;
+    this.logger.info("✅ Cache provider shut down");
+  }
+}

package/src/services/cache-plugin-registry.ts

@@ -0,0 +1,20 @@
+import type {
+  CachePlugin,
+  CachePluginRegistry,
+} from "@checkstack/cache-api";
+
+export class CachePluginRegistryImpl implements CachePluginRegistry {
+  private plugins = new Map<string, CachePlugin<unknown>>();
+
+  register(plugin: CachePlugin<unknown>): void {
+    this.plugins.set(plugin.id, plugin);
+  }
+
+  getPlugin(id: string): CachePlugin<unknown> | undefined {
+    return this.plugins.get(id);
+  }
+
+  getPlugins(): CachePlugin<unknown>[] {
+    return [...this.plugins.values()];
+  }
+}