@checkstack/cache-api 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# @checkstack/cache-api
+
+## 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.
+
+- 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
+
+- Updated dependencies [8d1ef12]
+  - @checkstack/backend-api@0.13.0

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@checkstack/cache-api",
+  "version": "0.2.0",
+  "checkstack": {
+    "type": "tooling"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "dependencies": {
+    "@checkstack/backend-api": "0.12.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/cache-manager.ts

@@ -0,0 +1,38 @@
+import type { CacheProvider } from "./cache-provider";
+
+/**
+ * CacheManager handles cache provider lifecycle and backend switching.
+ *
+ * Simpler than QueueManager — no proxy pattern needed since cache is stateless key/value.
+ * The active provider is replaced atomically on backend switch.
+ */
+export interface CacheManager {
+  /**
+   * Get the currently active CacheProvider.
+   * Returns a singleton provider for the active backend.
+   */
+  getProvider(): CacheProvider;
+
+  /**
+   * Get the currently active cache plugin ID.
+   */
+  getActivePlugin(): string;
+
+  /**
+   * Get the currently active cache plugin configuration.
+   */
+  getActiveConfig(): unknown;
+
+  /**
+   * Switch to a different cache backend.
+   * The old provider is shut down and replaced with a new one.
+   *
+   * @throws Error if connection test fails
+   */
+  setActiveBackend(pluginId: string, config: unknown): Promise<void>;
+
+  /**
+   * Gracefully shutdown the active cache provider.
+   */
+  shutdown(): Promise<void>;
+}

package/src/cache-plugin.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { CacheProvider } from "./cache-provider";
+import type { Logger, Migration } from "@checkstack/backend-api";
+
+/**
+ * Plugin interface for cache backend implementations.
+ * Mirrors the QueuePlugin pattern — each cache backend (in-memory, Redis, etc.)
+ * implements this interface and registers with the CachePluginRegistry.
+ */
+export interface CachePlugin<Config = unknown> {
+  id: string;
+  displayName: string;
+  description?: string;
+
+  /** Current version of the configuration schema */
+  configVersion: number;
+
+  /** Validation schema for the plugin-specific config */
+  configSchema: z.ZodType<Config>;
+
+  /** Optional migrations for backward compatibility */
+  migrations?: Migration<unknown, unknown>[];
+
+  /**
+   * Create a new CacheProvider instance with the given config.
+   * Unlike QueuePlugin.createQueue, there's only one provider per backend (not named instances).
+   */
+  createProvider(config: Config, logger: Logger): CacheProvider;
+}
+
+/**
+ * Registry for cache plugin implementations.
+ * Cache backend plugins register themselves here during initialization.
+ */
+export interface CachePluginRegistry {
+  register(plugin: CachePlugin<unknown>): void;
+  getPlugin(id: string): CachePlugin<unknown> | undefined;
+  getPlugins(): CachePlugin<unknown>[];
+}

package/src/cache-provider.test.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from "bun:test";
+import { createScopedCache, type CacheProvider } from "./cache-provider";
+
+/**
+ * Minimal in-memory CacheProvider for testing the scoped cache factory.
+ */
+function createTestProvider(): CacheProvider & {
+  store: Map<string, unknown>;
+} {
+  const store = new Map<string, unknown>();
+  return {
+    store,
+    get: async <T>(key: string) => store.get(key) as T | undefined,
+    set: async <T>(_key: string, value: T) => {
+      store.set(_key, value);
+    },
+    delete: async (key: string) => {
+      store.delete(key);
+    },
+    deleteByPrefix: async (prefix: string) => {
+      let removed = 0;
+      for (const key of [...store.keys()]) {
+        if (key.startsWith(prefix)) {
+          store.delete(key);
+          removed++;
+        }
+      }
+      return removed;
+    },
+    has: async (key: string) => store.has(key),
+  };
+}
+
+describe("createScopedCache", () => {
+  it("prefixes keys with plugin ID on set/get", async () => {
+    const provider = createTestProvider();
+    const scoped = createScopedCache({ pluginId: "my-plugin", provider });
+
+    await scoped.set("baseline:abc", { mean: 42 });
+
+    // Scoped cache should prefix the key
+    expect(provider.store.has("my-plugin:baseline:abc")).toBe(true);
+    expect(provider.store.has("baseline:abc")).toBe(false);
+
+    // Scoped get should also prefix
+    const result = await scoped.get<{ mean: number }>("baseline:abc");
+    expect(result).toEqual({ mean: 42 });
+  });
+
+  it("prefixes keys on delete", async () => {
+    const provider = createTestProvider();
+    const scoped = createScopedCache({ pluginId: "test", provider });
+
+    await scoped.set("key1", "value1");
+    expect(await scoped.has("key1")).toBe(true);
+
+    await scoped.delete("key1");
+    expect(await scoped.has("key1")).toBe(false);
+    expect(provider.store.has("test:key1")).toBe(false);
+  });
+
+  it("prefixes keys on has", async () => {
+    const provider = createTestProvider();
+    const scoped = createScopedCache({ pluginId: "plugin-a", provider });
+
+    expect(await scoped.has("missing")).toBe(false);
+
+    await scoped.set("exists", true);
+    expect(await scoped.has("exists")).toBe(true);
+  });
+
+  it("isolates keys between different scoped caches", async () => {
+    const provider = createTestProvider();
+    const scopeA = createScopedCache({ pluginId: "plugin-a", provider });
+    const scopeB = createScopedCache({ pluginId: "plugin-b", provider });
+
+    await scopeA.set("shared-key", "value-a");
+    await scopeB.set("shared-key", "value-b");
+
+    // Each scope should see its own value
+    expect(await scopeA.get<string>("shared-key")).toBe("value-a");
+    expect(await scopeB.get<string>("shared-key")).toBe("value-b");
+
+    // Underlying provider should have both prefixed keys
+    expect(provider.store.has("plugin-a:shared-key")).toBe(true);
+    expect(provider.store.has("plugin-b:shared-key")).toBe(true);
+  });
+
+  it("deleteByPrefix only removes keys under the scope's prefix", async () => {
+    const provider = createTestProvider();
+    const scopeA = createScopedCache({ pluginId: "a", provider });
+    const scopeB = createScopedCache({ pluginId: "b", provider });
+
+    await scopeA.set("bulk:1", "x");
+    await scopeA.set("bulk:2", "y");
+    await scopeA.set("other", "z");
+    await scopeB.set("bulk:1", "keep");
+
+    const removed = await scopeA.deleteByPrefix("bulk:");
+
+    expect(removed).toBe(2);
+    expect(await scopeA.has("bulk:1")).toBe(false);
+    expect(await scopeA.has("bulk:2")).toBe(false);
+    expect(await scopeA.has("other")).toBe(true);
+    expect(await scopeB.has("bulk:1")).toBe(true);
+  });
+
+  it("deleting from one scope does not affect the other", async () => {
+    const provider = createTestProvider();
+    const scopeA = createScopedCache({ pluginId: "a", provider });
+    const scopeB = createScopedCache({ pluginId: "b", provider });
+
+    await scopeA.set("key", 1);
+    await scopeB.set("key", 2);
+
+    await scopeA.delete("key");
+
+    expect(await scopeA.has("key")).toBe(false);
+    expect(await scopeB.has("key")).toBe(true);
+    expect(await scopeB.get<number>("key")).toBe(2);
+  });
+});

package/src/cache-provider.ts

@@ -0,0 +1,68 @@
+/**
+ * Cache provider interface for key-value storage with optional TTL.
+ *
+ * Implementations should be stateless from the caller's perspective —
+ * the provider manages internal state (eviction, connections, etc.)
+ * but all operations are explicit via this interface.
+ */
+export interface CacheProvider {
+  /**
+   * Retrieve a cached value by key.
+   * Returns undefined if the key doesn't exist or has expired.
+   */
+  get<T>(key: string): Promise<T | undefined>;
+
+  /**
+   * Store a value with an optional TTL (time-to-live) in milliseconds.
+   * If the key already exists, its value and TTL are replaced.
+   */
+  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+
+  /**
+   * Delete a cached value by key.
+   * No-op if the key doesn't exist.
+   */
+  delete(key: string): Promise<void>;
+
+  /**
+   * Delete every key starting with the given prefix.
+   * Used to invalidate a whole family of keys at once (e.g. all bulk results
+   * for a plugin). Returns the number of keys actually removed so callers
+   * can emit metrics.
+   */
+  deleteByPrefix(prefix: string): Promise<number>;
+
+  /**
+   * Check if a key exists and has not expired.
+   */
+  has(key: string): Promise<boolean>;
+}
+
+/**
+ * Creates a scoped cache that automatically prefixes all keys with the plugin ID.
+ * This ensures key isolation between plugins using the same underlying CacheProvider.
+ *
+ * Follows the Scoped Registry Pattern used by HealthCheckRegistry and other core services.
+ *
+ * @param pluginId - The plugin ID to use as a key prefix
+ * @param provider - The underlying CacheProvider
+ * @returns A CacheProvider with keys scoped to the plugin
+ */
+export function createScopedCache({
+  pluginId,
+  provider,
+}: {
+  pluginId: string;
+  provider: CacheProvider;
+}): CacheProvider {
+  const prefix = `${pluginId}:`;
+  return {
+    get: <T>(key: string) => provider.get<T>(`${prefix}${key}`),
+    set: <T>(key: string, value: T, ttlMs?: number) =>
+      provider.set<T>(`${prefix}${key}`, value, ttlMs),
+    delete: (key: string) => provider.delete(`${prefix}${key}`),
+    deleteByPrefix: (innerPrefix: string) =>
+      provider.deleteByPrefix(`${prefix}${innerPrefix}`),
+    has: (key: string) => provider.has(`${prefix}${key}`),
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./cache-provider";
+export * from "./cache-plugin";
+export * from "./cache-manager";

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}