@checkstack/cache-memory-backend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @checkstack/cache-memory-backend
+
+## 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]
+- Updated dependencies [8d1ef12]
+  - @checkstack/cache-memory-common@0.2.0
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/backend-api@0.13.0

package/package.json

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

package/src/index.ts

@@ -0,0 +1,23 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import { InMemoryCachePlugin } from "./plugin";
+import { cacheMemoryAccessRules } from "@checkstack/cache-memory-common";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerAccessRules(cacheMemoryAccessRules);
+
+    env.registerInit({
+      deps: {
+        cachePluginRegistry: coreServices.cachePluginRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ cachePluginRegistry, logger }) => {
+        logger.debug("🔌 Registering In-Memory Cache Plugin...");
+        const plugin = new InMemoryCachePlugin();
+        cachePluginRegistry.register(plugin);
+      },
+    });
+  },
+});

package/src/memory-cache.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import { InMemoryCache } from "./memory-cache";
+
+describe("InMemoryCache", () => {
+  const caches: InMemoryCache[] = [];
+
+  function createCache({
+    maxEntries = 100,
+    sweepIntervalMs = 0,
+  }: { maxEntries?: number; sweepIntervalMs?: number } = {}): InMemoryCache {
+    const cache = new InMemoryCache({ maxEntries, sweepIntervalMs });
+    caches.push(cache);
+    return cache;
+  }
+
+  afterEach(() => {
+    for (const cache of caches) {
+      cache.stop();
+    }
+    caches.length = 0;
+  });
+
+  describe("basic operations", () => {
+    it("returns undefined for missing keys", async () => {
+      const cache = createCache();
+      expect(await cache.get("nonexistent")).toBeUndefined();
+    });
+
+    it("stores and retrieves values", async () => {
+      const cache = createCache();
+      await cache.set("key1", { data: "hello" });
+      expect(await cache.get<{ data: string }>("key1")).toEqual({
+        data: "hello",
+      });
+    });
+
+    it("stores and retrieves primitive values", async () => {
+      const cache = createCache();
+      await cache.set("num", 42);
+      await cache.set("str", "test");
+      await cache.set("bool", true);
+
+      expect(await cache.get<number>("num")).toBe(42);
+      expect(await cache.get<string>("str")).toBe("test");
+      expect(await cache.get<boolean>("bool")).toBe(true);
+    });
+
+    it("overwrites existing values", async () => {
+      const cache = createCache();
+      await cache.set("key", "v1");
+      await cache.set("key", "v2");
+      expect(await cache.get<string>("key")).toBe("v2");
+    });
+
+    it("deletes values", async () => {
+      const cache = createCache();
+      await cache.set("key", "value");
+      expect(await cache.has("key")).toBe(true);
+
+      await cache.delete("key");
+      expect(await cache.has("key")).toBe(false);
+      expect(await cache.get("key")).toBeUndefined();
+    });
+
+    it("delete is a no-op for missing keys", async () => {
+      const cache = createCache();
+      // Should not throw
+      await cache.delete("nonexistent");
+    });
+
+    it("has returns false for missing keys", async () => {
+      const cache = createCache();
+      expect(await cache.has("missing")).toBe(false);
+    });
+
+    it("has returns true for existing keys", async () => {
+      const cache = createCache();
+      await cache.set("present", 1);
+      expect(await cache.has("present")).toBe(true);
+    });
+  });
+
+  describe("TTL expiration", () => {
+    it("returns value before TTL expires", async () => {
+      const cache = createCache();
+      await cache.set("key", "value", 10_000);
+      expect(await cache.get<string>("key")).toBe("value");
+    });
+
+    it("returns undefined after TTL expires (passive eviction on get)", async () => {
+      const cache = createCache();
+      // Set with 1ms TTL
+      await cache.set("key", "value", 1);
+      // Wait for expiry
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(await cache.get("key")).toBeUndefined();
+    });
+
+    it("has returns false after TTL expires", async () => {
+      const cache = createCache();
+      await cache.set("key", "value", 1);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(await cache.has("key")).toBe(false);
+    });
+
+    it("set without TTL creates non-expiring entry", async () => {
+      const cache = createCache();
+      await cache.set("key", "forever");
+      // Should always be available
+      expect(await cache.get<string>("key")).toBe("forever");
+    });
+
+    it("overwriting resets TTL", async () => {
+      const cache = createCache();
+      await cache.set("key", "v1", 1);
+      // Overwrite with no TTL
+      await cache.set("key", "v2");
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      // Should still be available since new entry has no TTL
+      expect(await cache.get<string>("key")).toBe("v2");
+    });
+  });
+
+  describe("capacity eviction", () => {
+    it("evicts oldest entries when maxEntries is reached", async () => {
+      const cache = createCache({ maxEntries: 3 });
+      await cache.set("a", 1);
+      await cache.set("b", 2);
+      await cache.set("c", 3);
+
+      // Adding a 4th should evict "a" (oldest)
+      await cache.set("d", 4);
+
+      expect(await cache.has("a")).toBe(false);
+      expect(await cache.get<number>("b")).toBe(2);
+      expect(await cache.get<number>("c")).toBe(3);
+      expect(await cache.get<number>("d")).toBe(4);
+      expect(cache.size).toBe(3);
+    });
+
+    it("overwriting existing key does not trigger eviction", async () => {
+      const cache = createCache({ maxEntries: 2 });
+      await cache.set("a", 1);
+      await cache.set("b", 2);
+
+      // Overwrite "a" — should NOT evict anything
+      await cache.set("a", 10);
+
+      expect(await cache.get<number>("a")).toBe(10);
+      expect(await cache.get<number>("b")).toBe(2);
+      expect(cache.size).toBe(2);
+    });
+  });
+
+  describe("deleteByPrefix", () => {
+    it("removes only keys starting with the prefix", async () => {
+      const cache = createCache();
+      await cache.set("incident:list:active", "a");
+      await cache.set("incident:get:1", "b");
+      await cache.set("incident:get:2", "c");
+      await cache.set("healthcheck:status:s1", "d");
+
+      const removed = await cache.deleteByPrefix("incident:get:");
+
+      expect(removed).toBe(2);
+      expect(await cache.has("incident:list:active")).toBe(true);
+      expect(await cache.has("incident:get:1")).toBe(false);
+      expect(await cache.has("incident:get:2")).toBe(false);
+      expect(await cache.has("healthcheck:status:s1")).toBe(true);
+    });
+
+    it("returns 0 when no keys match", async () => {
+      const cache = createCache();
+      await cache.set("foo", "bar");
+      expect(await cache.deleteByPrefix("nope:")).toBe(0);
+      expect(await cache.has("foo")).toBe(true);
+    });
+
+    it("treats expired entries as deletable", async () => {
+      const cache = createCache();
+      await cache.set("scope:a", "x", 1);
+      await cache.set("scope:b", "y");
+      await new Promise((resolve) => setTimeout(resolve, 10));
+
+      // Both keys are still in the underlying map (passive eviction);
+      // deleteByPrefix sweeps both regardless.
+      const removed = await cache.deleteByPrefix("scope:");
+      expect(removed).toBe(2);
+      expect(cache.size).toBe(0);
+    });
+  });
+
+  describe("sweep", () => {
+    it("periodic sweep removes expired entries", async () => {
+      // Sweep every 10ms
+      const cache = createCache({ sweepIntervalMs: 10 });
+      await cache.set("expires", "value", 1);
+      await cache.set("stays", "value");
+
+      // Wait for sweep to run
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // "expires" should have been swept
+      expect(cache.size).toBe(1);
+      expect(await cache.get<string>("stays")).toBe("value");
+    });
+  });
+
+  describe("stop", () => {
+    it("stops the sweep timer", async () => {
+      const cache = createCache({ sweepIntervalMs: 10 });
+      cache.stop();
+      // Should not throw or continue sweeping
+      await cache.set("key", "value", 1);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      // Entry may or may not be expired (passive eviction), but no crash
+    });
+  });
+});

package/src/memory-cache.ts

@@ -0,0 +1,137 @@
+import type { CacheProvider } from "@checkstack/cache-api";
+
+/**
+ * Internal cache entry with optional expiration tracking.
+ */
+interface CacheEntry {
+  value: unknown;
+  /** Absolute timestamp (ms since epoch) when this entry expires, or undefined for no expiry */
+  expiresAt: number | undefined;
+}
+
+/**
+ * Configuration for the InMemoryCache.
+ */
+export interface InMemoryCacheConfig {
+  maxEntries: number;
+  sweepIntervalMs: number;
+}
+
+/**
+ * In-memory CacheProvider implementation using a Map.
+ *
+ * Features:
+ * - Passive TTL eviction: expired entries are detected on `get` and `has`
+ * - Active sweep: periodic background sweep removes expired entries
+ * - LRU-style eviction: oldest entries are evicted when maxEntries is reached
+ */
+export class InMemoryCache implements CacheProvider {
+  private store = new Map<string, CacheEntry>();
+  private sweepTimer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(private config: InMemoryCacheConfig) {
+    // Start periodic sweep if configured
+    if (config.sweepIntervalMs > 0) {
+      this.sweepTimer = setInterval(() => {
+        this.sweep();
+      }, config.sweepIntervalMs);
+    }
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+
+    // Passive TTL eviction
+    if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+
+    return entry.value as T;
+  }
+
+  async set<T>(key: string, value: T, ttlMs?: number): Promise<void> {
+    // Evict oldest entries if at capacity (and key doesn't already exist)
+    if (!this.store.has(key) && this.store.size >= this.config.maxEntries) {
+      this.evictOldest();
+    }
+
+    // Delete and re-insert to maintain insertion order for LRU
+    this.store.delete(key);
+
+    this.store.set(key, {
+      value,
+      expiresAt: ttlMs === undefined ? undefined : Date.now() + ttlMs,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async deleteByPrefix(prefix: string): Promise<number> {
+    let removed = 0;
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key);
+        removed++;
+      }
+    }
+    return removed;
+  }
+
+  async has(key: string): Promise<boolean> {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+
+    // Passive TTL eviction
+    if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Sweep expired entries from the store.
+   * Called periodically by the sweep timer.
+   */
+  private sweep(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (entry.expiresAt !== undefined && now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Evict the oldest entry (first in Map insertion order).
+   * This provides simple LRU-style eviction.
+   */
+  private evictOldest(): void {
+    const firstKey = this.store.keys().next().value;
+    if (firstKey !== undefined) {
+      this.store.delete(firstKey);
+    }
+  }
+
+  /**
+   * Stop the sweep timer. Call during shutdown.
+   */
+  stop(): void {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = undefined;
+    }
+  }
+
+  /**
+   * Get the current number of entries (for testing/stats).
+   */
+  get size(): number {
+    return this.store.size;
+  }
+}

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Cache Memory backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "cache-memory",
+});

package/src/plugin.ts

@@ -0,0 +1,34 @@
+import type { CachePlugin, CacheProvider } from "@checkstack/cache-api";
+import type { Logger } from "@checkstack/backend-api";
+import { z } from "zod";
+import { InMemoryCache } from "./memory-cache";
+
+const configSchema = z.object({
+  maxEntries: z
+    .number()
+    .min(1)
+    .default(10_000)
+    .describe("Maximum number of cache entries before eviction"),
+  sweepIntervalMs: z
+    .number()
+    .min(0)
+    .default(60_000)
+    .describe(
+      "Interval in ms for background sweep of expired entries. Set to 0 to disable.",
+    ),
+});
+
+export type InMemoryCacheConfig = z.infer<typeof configSchema>;
+
+export class InMemoryCachePlugin implements CachePlugin<InMemoryCacheConfig> {
+  id = "memory";
+  displayName = "In-Memory Cache";
+  description =
+    "Simple in-memory cache for development and single-instance deployments";
+  configVersion = 1;
+  configSchema = configSchema;
+
+  createProvider(config: InMemoryCacheConfig, _logger: Logger): CacheProvider {
+    return new InMemoryCache(config);
+  }
+}

package/tsconfig.json

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