@checkstack/cache-memory-backend 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # @checkstack/cache-memory-backend
 
+## 0.3.0
+
+### Minor Changes
+
+- aa89bc5: Replace the bespoke `registerInfrastructureTab()` registry with a standard
+  slot-extension contract (`InfrastructureTabsSlot` from
+  `@checkstack/infrastructure-common`). Plugins now contribute infrastructure
+  tabs via `createSlotExtension`, depending only on the slot owner.
+
+  The slot system in `@checkstack/frontend-api` gains a second type parameter
+  on `createSlot<TContext, TMetadata>` so extensions can declare typed static
+  metadata at registration time (label, icon, access rules, ordering for the
+  infrastructure tab bar). A new `useSlotExtensions(slot)` hook returns typed
+  extensions and subscribes to plugin lifecycle changes.
+
+  Each tab body now stacks a **Runtime** sub-section (live state, read-only)
+  on top of a **Configuration** sub-section (settings, gated by `canUpdate`).
+
+  **Queue runtime panel.** Surfaces aggregated counts (pending / processing /
+  completed / failed) plus three sub-tabs of recent jobs: **Active**, **Recent
+  failed** (with the failure message), and **Recent completed** (with
+  duration). Job payloads are deliberately not surfaced — they may carry
+  secrets and need a separate manage-access gate to be shown.
+
+  To support this, `Queue<T>` gains a required `listJobs(opts)` method
+  returning `JobSummary[]` (no payloads), and `QueueStats` gains a
+  `scope: "instance" | "cluster"` field. The in-memory queue keeps rolling
+  ring buffers (200 entries) for completed/failed history and tracks active
+  jobs by id; BullMQ uses native `getJobs`. `QueueManager.listJobs` aggregates
+  across queues and sorts (most-recent-first for terminal states, FIFO for
+  active/waiting/delayed).
+
+  **Cache runtime panel.** Lists the top N entries by size (or by recency) so
+  operators can debug a cache filling up. Values are deliberately omitted —
+  PII / secret risk. Backends opt in via an optional `listEntries?` method on
+  `CacheProvider`; non-supporting backends return `{ supported: false }` and
+  the UI renders a "not supported by this backend" hint. The in-memory cache
+  implements it using its existing per-entry byte tracking.
+
+  `CacheStats` also gains `scope: "instance" | "cluster"`.
+
+  **Multi-instance scope warning.** A new `<InstanceScopeBanner>` component in
+  `@checkstack/ui` renders a yellow banner above any runtime panel whose
+  backend reports `scope: "instance"` — i.e. in-memory queue or cache running
+  in a horizontally scaled deployment. The banner explains the metrics are
+  local to the responding replica and recommends switching to a clustered
+  backend (Redis-backed queue / cache) for cluster-wide visibility.
+
+  **Bug fix — stable cache provider proxy.** `CacheManagerImpl.getProvider()`
+  now returns a single stable proxy that delegates to whatever provider is
+  currently active. Previously, consumers of `createCachedScope` (and any
+  direct `cacheManager.getProvider()` caller) captured the active provider
+  reference at plugin-init time. After any `setActiveBackend` call — including
+  saving the same memory config in the new Cache tab, which reconstructs the
+  in-memory cache — those scopes wrote to an orphaned old provider while the
+  runtime panel read stats from the new (empty) one, making the runtime panel
+  appear to report 0 keys. With the proxy, all consumers share a single stable
+  identity and writes always land in the active provider.
+
+  **Bytes tracking on the in-memory cache.** `InMemoryCache.getStats().sizeBytes`
+  now returns a running approximation (UTF-8 bytes of the key plus
+  `v8.serialize(value).byteLength`, with a JSON fallback) that's kept in sync
+  across all eviction paths. Treat the number as a sanity gauge; it doesn't
+  include `Map` per-entry overhead.
+
+  **Pagination.** Both `Queue<T>.listJobs` and `CacheProvider.listEntries?`
+  are offset-paginated. Inputs gain an `offset: number`; outputs change to
+  `{ items, total: number | null, hasMore: boolean }`. `total` is nullable
+  so backends that can't compute it cheaply still paginate via `hasMore`.
+  The UI uses the existing `<Pagination>` component with a 25-row default
+  page size. `QueueManager.listJobs` aggregates by over-fetching
+  `[0, offset+limit)` per queue, merge-sorting, then slicing the window —
+  optimal for the single-queue case, acceptable for the multi-queue case
+  within the UI's reasonable page-depth bounds. BullMQ uses native offset
+  ranges via `getJobs(types, start, end)` plus `getJobCounts` for `total`.
+
+  **Pending tab.** The Queue runtime panel exposes a virtual `"pending"`
+  state (waiting ∪ delayed, FIFO). It's now the default sub-tab, since
+  "what's queued up?" is the most common question. Per-row state is shown
+  when viewing the combined list.
+
+  **Recurring schedules visible under Pending.** Cron- and interval-based
+  recurring jobs (e.g. healthchecks) are surfaced under Pending/Delayed
+  between fires, with a `nextRunAt` countdown column and a "(recurring)"
+  label. `JobSummary` gains optional `nextRunAt: Date` and `recurring:
+boolean` fields. The in-memory queue synthesises these rows from its
+  `recurringJobs` registry; BullMQ already materialises the next fire of
+  each scheduler as a delayed job and we now surface its trigger time and
+  the `repeatJobKey`-derived `recurring` flag.
+
+  **Bug fix — drop hook emits with no listeners.** `EventBus.emit` no
+  longer enqueues a job when zero listeners (distributed or instance-local)
+  are registered for the hook. Previously, hooks like
+  `core.plugin.initialized` — emitted on every plugin init but subscribed
+  to by nothing in the core repo — accumulated one waiting job per emit
+  forever. The in-memory queue's `processNext` short-circuits when there
+  are zero consumer groups, so its post-loop cleanup never ran for these
+  orphaned jobs. The fix drops the emit at the source and logs a debug
+  line. Note: in distributed deployments using a Redis-backed queue, this
+  means a subscriber on another replica won't receive an event if no
+  replica that emits it has a local listener. Plugins needing cross-process
+  delivery must register their listener on every replica that should
+  receive the hook.
+
+  **Breaking notes (treated as minor under beta semantics)**:
+
+  - `@checkstack/infrastructure-common` removes `registerInfrastructureTab`
+    and `getInfrastructureTabs`; former callers must register an extension
+    into `InfrastructureTabsSlot`.
+  - `@checkstack/queue-api`'s `Queue<T>` interface requires the new
+    `listJobs(opts)` method returning `ListJobsResult` (paginated). Both
+    bundled queue backends (memory, BullMQ) are updated; out-of-tree
+    implementations will need to add it.
+  - `QueueStats` and `CacheStats` add a required `scope` field.
+  - `CacheProvider.listEntries?` (when implemented) now returns
+    `ListEntriesResult` instead of `CacheEntrySummary[]`.
+  - `JobState` adds a `"pending"` variant.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+- Updated dependencies [aa89bc5]
+  - @checkstack/common@0.9.0
+  - @checkstack/cache-api@0.3.0
+  - @checkstack/backend-api@0.15.1
+  - @checkstack/cache-memory-common@0.2.2
+
+## 0.2.4
+
+### Patch Changes
+
+- Updated dependencies [50e5f5f]
+  - @checkstack/backend-api@0.15.0
+  - @checkstack/common@0.8.0
+  - @checkstack/cache-memory-common@0.2.1
+  - @checkstack/cache-api@0.2.4
+
 ## 0.2.3
 
 ### Patch Changes

package/package.json

@@ -1,26 +1,36 @@
 {
   "name": "@checkstack/cache-memory-backend",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
-    "type": "backend"
+    "type": "backend",
+    "pluginId": "cache-memory",
+    "bundle": [
+      "@checkstack/cache-memory-common"
+    ]
   },
   "scripts": {
     "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
-    "lint:code": "eslint . --max-warnings 0"
+    "lint:code": "eslint . --max-warnings 0",
+    "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.14.0",
-    "@checkstack/cache-api": "0.2.2",
-    "@checkstack/cache-memory-common": "0.2.0",
-    "@checkstack/common": "0.7.0",
+    "@checkstack/backend-api": "0.15.0",
+    "@checkstack/cache-api": "0.2.4",
+    "@checkstack/cache-memory-common": "0.2.1",
+    "@checkstack/common": "0.8.0",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@types/bun": "latest",
-    "@checkstack/tsconfig": "0.0.5",
-    "@checkstack/scripts": "0.1.2"
-  }
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
+  },
+  "description": "Checkstack cache-memory-backend plugin",
+  "author": {
+    "name": "Checkstack contributors"
+  },
+  "license": "Elastic-2.0"
 }

package/src/memory-cache.test.ts

@@ -216,4 +216,209 @@ describe("InMemoryCache", () => {
       // Entry may or may not be expired (passive eviction), but no crash
     });
   });
+
+  describe("getStats — byte tracking", () => {
+    it("starts at zero bytes", async () => {
+      const cache = createCache();
+      const stats = await cache.getStats();
+      expect(stats.sizeBytes).toBe(0);
+      expect(stats.keyCount).toBe(0);
+    });
+
+    it("grows on set and shrinks on delete", async () => {
+      const cache = createCache();
+      await cache.set("k", "small");
+      const afterSet = await cache.getStats();
+      expect(afterSet.sizeBytes).toBeGreaterThan(0);
+
+      await cache.delete("k");
+      const afterDelete = await cache.getStats();
+      expect(afterDelete.sizeBytes).toBe(0);
+      expect(afterDelete.keyCount).toBe(0);
+    });
+
+    it("scales with payload size", async () => {
+      const small = createCache();
+      const big = createCache();
+      await small.set("k", "x");
+      await big.set("k", "x".repeat(10_000));
+      const smallStats = await small.getStats();
+      const bigStats = await big.getStats();
+      expect(bigStats.sizeBytes!).toBeGreaterThan(smallStats.sizeBytes! * 100);
+    });
+
+    it("replaces (not double-counts) on overwrite", async () => {
+      const cache = createCache();
+      await cache.set("k", "first");
+      const first = (await cache.getStats()).sizeBytes!;
+      await cache.set("k", "second-but-longer-value");
+      const second = (await cache.getStats()).sizeBytes!;
+      expect(second).toBeGreaterThan(first);
+      expect((await cache.getStats()).keyCount).toBe(1);
+    });
+
+    it("returns to zero after deleteByPrefix", async () => {
+      const cache = createCache();
+      await cache.set("p:a", "1");
+      await cache.set("p:b", "2");
+      await cache.set("other", "3");
+      const removed = await cache.deleteByPrefix("p:");
+      expect(removed).toBe(2);
+      const stats = await cache.getStats();
+      expect(stats.keyCount).toBe(1);
+      expect(stats.sizeBytes!).toBeGreaterThan(0);
+
+      await cache.delete("other");
+      const empty = await cache.getStats();
+      expect(empty.sizeBytes).toBe(0);
+    });
+
+    it("decrements on TTL expiry via get", async () => {
+      const cache = createCache();
+      await cache.set("k", "value", 10);
+      expect((await cache.getStats()).sizeBytes!).toBeGreaterThan(0);
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      // Passive eviction via get
+      expect(await cache.get("k")).toBeUndefined();
+      expect((await cache.getStats()).sizeBytes).toBe(0);
+    });
+
+    it("decrements on LRU eviction at capacity", async () => {
+      const cache = createCache({ maxEntries: 2 });
+      await cache.set("a", "x".repeat(100));
+      await cache.set("b", "y".repeat(100));
+      const before = (await cache.getStats()).sizeBytes!;
+      await cache.set("c", "z");
+      // "a" should have been evicted; size went down by ~100 bytes plus a key,
+      // up by tiny amount for "c" — net should be lower than `before`.
+      const after = (await cache.getStats()).sizeBytes!;
+      expect(after).toBeLessThan(before);
+      expect((await cache.getStats()).keyCount).toBe(2);
+    });
+
+    it("counts non-JSON-safe values via v8.serialize", async () => {
+      const cache = createCache();
+      await cache.set("date", new Date());
+      await cache.set("map", new Map([["k", "v"]]));
+      const stats = await cache.getStats();
+      expect(stats.sizeBytes!).toBeGreaterThan(0);
+      expect(stats.keyCount).toBe(2);
+    });
+
+    it("reports scope=instance", async () => {
+      const cache = createCache();
+      const stats = await cache.getStats();
+      expect(stats.scope).toBe("instance");
+    });
+  });
+
+  describe("listEntries", () => {
+    it("returns empty when cache is empty", async () => {
+      const cache = createCache();
+      const result = await cache.listEntries({
+        offset: 0,
+        limit: 10,
+        sortBy: "biggest",
+      });
+      expect(result.items).toEqual([]);
+      expect(result.total).toBe(0);
+      expect(result.hasMore).toBe(false);
+    });
+
+    it("sorts by size descending when sortBy=biggest", async () => {
+      const cache = createCache();
+      await cache.set("small", "x");
+      await cache.set("big", "x".repeat(5000));
+      await cache.set("medium", "x".repeat(500));
+
+      const { items, total } = await cache.listEntries({
+        offset: 0,
+        limit: 10,
+        sortBy: "biggest",
+      });
+      expect(items.map((e) => e.key)).toEqual(["big", "medium", "small"]);
+      expect(total).toBe(3);
+      for (let i = 1; i < items.length; i++) {
+        expect(items[i - 1].byteSize).toBeGreaterThanOrEqual(
+          items[i].byteSize,
+        );
+      }
+    });
+
+    it("sorts by insertion recency when sortBy=newest", async () => {
+      const cache = createCache();
+      await cache.set("first", "a");
+      await cache.set("second", "b");
+      await cache.set("third", "c");
+
+      const { items } = await cache.listEntries({
+        offset: 0,
+        limit: 10,
+        sortBy: "newest",
+      });
+      expect(items.map((e) => e.key)).toEqual(["third", "second", "first"]);
+    });
+
+    it("paginates with offset/limit and reports total/hasMore", async () => {
+      const cache = createCache();
+      for (let i = 0; i < 30; i++) {
+        await cache.set(`k-${i}`, "x".repeat(i));
+      }
+      const page1 = await cache.listEntries({
+        offset: 0,
+        limit: 5,
+        sortBy: "biggest",
+      });
+      expect(page1.items).toHaveLength(5);
+      expect(page1.total).toBe(30);
+      expect(page1.hasMore).toBe(true);
+
+      const page2 = await cache.listEntries({
+        offset: 5,
+        limit: 5,
+        sortBy: "biggest",
+      });
+      expect(page2.items).toHaveLength(5);
+      expect(page2.items.map((e) => e.key)).not.toEqual(
+        page1.items.map((e) => e.key),
+      );
+
+      const lastPage = await cache.listEntries({
+        offset: 28,
+        limit: 5,
+        sortBy: "biggest",
+      });
+      expect(lastPage.items).toHaveLength(2);
+      expect(lastPage.hasMore).toBe(false);
+    });
+
+    it("does NOT include cached values in summaries", async () => {
+      const cache = createCache();
+      await cache.set("secret", { token: "very-private" });
+      const { items } = await cache.listEntries({
+        offset: 0,
+        limit: 10,
+        sortBy: "biggest",
+      });
+      expect(items[0].key).toBe("secret");
+      expect(Object.keys(items[0]).sort()).toEqual(
+        ["byteSize", "expiresAt", "key"].sort(),
+      );
+    });
+
+    it("surfaces TTL as expiresAt Date or null", async () => {
+      const cache = createCache();
+      await cache.set("ephemeral", "x", 60_000);
+      await cache.set("forever", "y");
+      const { items } = await cache.listEntries({
+        offset: 0,
+        limit: 10,
+        sortBy: "newest",
+      });
+      const ephemeral = items.find((e) => e.key === "ephemeral")!;
+      const forever = items.find((e) => e.key === "forever")!;
+      expect(ephemeral.expiresAt).toBeInstanceOf(Date);
+      expect(forever.expiresAt).toBeNull();
+    });
+  });
 });

package/src/memory-cache.ts

@@ -1,12 +1,27 @@
-import type { CacheProvider } from "@checkstack/cache-api";
+import type {
+  CacheProvider,
+  CacheStats,
+  CacheEntrySummary,
+  ListEntriesOptions,
+  ListEntriesResult,
+} from "@checkstack/cache-api";
 
 /**
  * Internal cache entry with optional expiration tracking.
+ *
+ * `byteSize` is an approximation of the entry's footprint computed at
+ * `set` time (UTF-8 byte length of the key plus a `v8.serialize`-based
+ * snapshot of the value, with a JSON fallback). It does not include the
+ * `Map` per-entry overhead and is intended for the Infrastructure runtime
+ * panel, not for memory-pressure decisions.
  */
 interface CacheEntry {
   value: unknown;
   /** Absolute timestamp (ms since epoch) when this entry expires, or undefined for no expiry */
   expiresAt: number | undefined;
+  byteSize: number;
+  /** Insertion order — used to sort by "newest" without keeping a separate index. */
+  insertionSeq: number;
 }
 
 /**
@@ -17,6 +32,30 @@ export interface InMemoryCacheConfig {
   sweepIntervalMs: number;
 }
 
+/**
+ * Approximate the byte footprint of a cache entry.
+ *
+ * Tries `v8.serialize` first (handles Dates, Maps, typed arrays, etc.); if
+ * that throws — e.g. on functions — falls back to JSON. If both fail we
+ * count just the key. The number is an estimate; treat it as a sanity gauge.
+ */
+function estimateEntryBytes(key: string, value: unknown): number {
+  const keyBytes = Buffer.byteLength(key, "utf8");
+  try {
+    // Lazy require so the module stays runtime-portable.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const v8 = require("node:v8") as typeof import("node:v8");
+    return keyBytes + v8.serialize(value).byteLength;
+  } catch {
+    try {
+      const json = JSON.stringify(value) ?? "";
+      return keyBytes + Buffer.byteLength(json, "utf8");
+    } catch {
+      return keyBytes;
+    }
+  }
+}
+
 /**
  * In-memory CacheProvider implementation using a Map.
  *
@@ -24,13 +63,17 @@ export interface InMemoryCacheConfig {
  * - 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
+ * - Approximate byte tracking for runtime stats
  */
 export class InMemoryCache implements CacheProvider {
   private store = new Map<string, CacheEntry>();
   private sweepTimer: ReturnType<typeof setInterval> | undefined;
+  private hitCount = 0;
+  private missCount = 0;
+  private byteSize = 0;
+  private insertionCounter = 0;
 
   constructor(private config: InMemoryCacheConfig) {
-    // Start periodic sweep if configured
     if (config.sweepIntervalMs > 0) {
       this.sweepTimer = setInterval(() => {
         this.sweep();
@@ -38,43 +81,58 @@ export class InMemoryCache implements CacheProvider {
     }
   }
 
+  private removeEntry(key: string): void {
+    const entry = this.store.get(key);
+    if (entry) {
+      this.byteSize -= entry.byteSize;
+      this.store.delete(key);
+    }
+  }
+
   async get<T>(key: string): Promise<T | undefined> {
     const entry = this.store.get(key);
-    if (!entry) return undefined;
+    if (!entry) {
+      this.missCount++;
+      return undefined;
+    }
 
-    // Passive TTL eviction
     if (entry.expiresAt !== undefined && Date.now() > entry.expiresAt) {
-      this.store.delete(key);
+      this.removeEntry(key);
+      this.missCount++;
       return undefined;
     }
 
+    this.hitCount++;
     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) {
+    // If replacing, drop the old entry's bytes first.
+    this.removeEntry(key);
+
+    if (this.store.size >= this.config.maxEntries) {
       this.evictOldest();
     }
 
-    // Delete and re-insert to maintain insertion order for LRU
-    this.store.delete(key);
-
+    const byteSize = estimateEntryBytes(key, value);
     this.store.set(key, {
       value,
       expiresAt: ttlMs === undefined ? undefined : Date.now() + ttlMs,
+      byteSize,
+      insertionSeq: ++this.insertionCounter,
     });
+    this.byteSize += byteSize;
   }
 
   async delete(key: string): Promise<void> {
-    this.store.delete(key);
+    this.removeEntry(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);
+        this.removeEntry(key);
         removed++;
       }
     }
@@ -85,9 +143,8 @@ export class InMemoryCache implements CacheProvider {
     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);
+      this.removeEntry(key);
       return false;
     }
 
@@ -102,19 +159,19 @@ export class InMemoryCache implements CacheProvider {
     const now = Date.now();
     for (const [key, entry] of this.store) {
       if (entry.expiresAt !== undefined && now > entry.expiresAt) {
-        this.store.delete(key);
+        this.removeEntry(key);
       }
     }
   }
 
   /**
    * Evict the oldest entry (first in Map insertion order).
-   * This provides simple LRU-style eviction.
+   * Provides simple LRU-style eviction.
    */
   private evictOldest(): void {
     const firstKey = this.store.keys().next().value;
     if (firstKey !== undefined) {
-      this.store.delete(firstKey);
+      this.removeEntry(firstKey);
     }
   }
 
@@ -134,4 +191,46 @@ export class InMemoryCache implements CacheProvider {
   get size(): number {
     return this.store.size;
   }
+
+  async getStats(): Promise<CacheStats> {
+    return {
+      keyCount: this.store.size,
+      sizeBytes: this.byteSize,
+      hits: this.hitCount,
+      misses: this.missCount,
+      scope: "instance",
+    };
+  }
+
+  async listEntries(opts: ListEntriesOptions): Promise<ListEntriesResult> {
+    const limit = Math.max(0, opts.limit);
+    const offset = Math.max(0, opts.offset);
+    const total = this.store.size;
+    if (limit === 0) {
+      return { items: [], total, hasMore: total > offset };
+    }
+
+    const all: Array<CacheEntrySummary & { insertionSeq: number }> = [];
+    for (const [key, entry] of this.store) {
+      all.push({
+        key,
+        byteSize: entry.byteSize,
+        expiresAt:
+          entry.expiresAt === undefined ? null : new Date(entry.expiresAt),
+        insertionSeq: entry.insertionSeq,
+      });
+    }
+
+    if (opts.sortBy === "biggest") {
+      all.sort((a, b) => b.byteSize - a.byteSize);
+    } else {
+      // newest first
+      all.sort((a, b) => b.insertionSeq - a.insertionSeq);
+    }
+
+    const items = all
+      .slice(offset, offset + limit)
+      .map(({ key, byteSize, expiresAt }) => ({ key, byteSize, expiresAt }));
+    return { items, total, hasMore: offset + items.length < total };
+  }
 }