@checkstack/cache-frontend 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,137 @@
 # @checkstack/cache-frontend
 
+## 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 [3547670]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+- Updated dependencies [950d6ec]
+- Updated dependencies [3547670]
+  - @checkstack/common@0.9.0
+  - @checkstack/ui@1.8.0
+  - @checkstack/frontend-api@0.5.0
+  - @checkstack/infrastructure-common@0.3.0
+  - @checkstack/cache-common@0.3.0
+
 ## 0.2.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/cache-frontend",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,18 +21,18 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/cache-common": "0.2.0",
-    "@checkstack/common": "0.7.0",
-    "@checkstack/frontend-api": "0.4.1",
-    "@checkstack/infrastructure-common": "0.2.2",
-    "@checkstack/ui": "1.7.0",
+    "@checkstack/cache-common": "0.2.1",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/frontend-api": "0.4.2",
+    "@checkstack/infrastructure-common": "0.2.3",
+    "@checkstack/ui": "1.7.1",
     "lucide-react": "^0.468.0",
     "react": "^18.3.1"
   },
   "devDependencies": {
     "@types/react": "^18.3.18",
     "typescript": "^5.7.2",
-    "@checkstack/tsconfig": "0.0.6",
-    "@checkstack/scripts": "0.1.2"
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
   }
 }

package/src/components/CacheInfrastructureTab.tsx

@@ -0,0 +1,21 @@
+import type { InfrastructureTabContext } from "@checkstack/infrastructure-common";
+import { CacheConfigTab } from "./CacheConfigTab";
+import { CacheRuntimePanel } from "./CacheRuntimePanel";
+
+/**
+ * Cache tab body for the Infrastructure Settings page.
+ *
+ * Stacks two sub-sections inside the same tab:
+ *  - Runtime: live cache stats (read-only, always shown).
+ *  - Configuration: provider selection (gated by `canUpdate`).
+ */
+export const CacheInfrastructureTab = ({
+  canUpdate,
+}: InfrastructureTabContext) => {
+  return (
+    <div className="space-y-6">
+      <CacheRuntimePanel />
+      <CacheConfigTab canUpdate={canUpdate} />
+    </div>
+  );
+};

package/src/components/CacheRuntimePanel.tsx

@@ -0,0 +1,274 @@
+import { useState } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { CacheApi } from "@checkstack/cache-common";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  InstanceScopeBanner,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabPanel,
+} from "@checkstack/ui";
+import {
+  Activity,
+  CheckCircle2,
+  Database,
+  HardDrive,
+  ListOrdered,
+  XCircle,
+} from "lucide-react";
+
+const REFRESH_INTERVAL_MS = 5000;
+const PAGE_SIZE = 25;
+
+type SortBy = "biggest" | "newest";
+
+const formatNumber = (n: number | null | undefined) =>
+  n === null || n === undefined
+    ? "—"
+    : n.toLocaleString(undefined, { maximumFractionDigits: 0 });
+
+const formatBytes = (n: number | null | undefined) => {
+  if (n === null || n === undefined) return "—";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MiB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GiB`;
+};
+
+const formatHitRate = (
+  hits: number | null | undefined,
+  misses: number | null | undefined,
+) => {
+  if (hits === null || hits === undefined) return "—";
+  if (misses === null || misses === undefined) return "—";
+  const total = hits + misses;
+  if (total === 0) return "—";
+  return `${((hits / total) * 100).toFixed(1)}%`;
+};
+
+const truncateMiddle = (s: string, head = 18, tail = 10) => {
+  if (s.length <= head + tail + 1) return s;
+  return `${s.slice(0, head)}…${s.slice(-tail)}`;
+};
+
+const formatTtl = (expiresAt: Date | null | undefined) => {
+  if (!expiresAt) return "—";
+  const ms = expiresAt.getTime() - Date.now();
+  if (ms <= 0) return "expired";
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `${hr}h`;
+  return `${Math.round(hr / 24)}d`;
+};
+
+interface StatTileProps {
+  label: string;
+  value: string;
+  icon: React.ComponentType<{ className?: string }>;
+}
+
+const StatTile = ({ label, value, icon: Icon }: StatTileProps) => (
+  <div className="flex items-center gap-3 rounded-lg border bg-card px-4 py-3">
+    <Icon className="h-5 w-5 shrink-0 text-muted-foreground" />
+    <div className="min-w-0">
+      <div className="text-xs font-medium text-muted-foreground">{label}</div>
+      <div className="text-2xl font-semibold tabular-nums">{value}</div>
+    </div>
+  </div>
+);
+
+const EntriesTable = ({ sortBy }: { sortBy: SortBy }) => {
+  const cacheClient = usePluginClient(CacheApi);
+  const [page, setPage] = useState(1);
+  const offset = (page - 1) * PAGE_SIZE;
+
+  const { data, isLoading, error } = cacheClient.listEntries.useQuery(
+    { offset, limit: PAGE_SIZE, sortBy },
+    { refetchInterval: REFRESH_INTERVAL_MS },
+  );
+
+  if (error) {
+    return (
+      <p className="text-sm text-destructive">Failed to load cache entries.</p>
+    );
+  }
+  if (isLoading) {
+    return <p className="text-sm text-muted-foreground">Loading…</p>;
+  }
+  if (data && !data.supported) {
+    return (
+      <p className="text-sm text-muted-foreground">
+        Listing not supported by this cache backend.
+      </p>
+    );
+  }
+  if (!data || data.items.length === 0) {
+    return <p className="text-sm text-muted-foreground">No cache entries.</p>;
+  }
+
+  const totalPages =
+    data.total === null
+      ? data.hasMore
+        ? page + 1
+        : page
+      : Math.max(1, Math.ceil(data.total / PAGE_SIZE));
+
+  return (
+    <div className="space-y-3">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Key</TableHead>
+            <TableHead className="text-right">Size</TableHead>
+            <TableHead className="text-right">TTL</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.items.map((entry) => (
+            <TableRow key={entry.key}>
+              <TableCell
+                className="font-mono text-xs whitespace-nowrap"
+                title={entry.key}
+              >
+                {truncateMiddle(entry.key)}
+              </TableCell>
+              <TableCell className="text-right tabular-nums">
+                {formatBytes(entry.byteSize)}
+              </TableCell>
+              <TableCell className="text-right tabular-nums">
+                {formatTtl(entry.expiresAt)}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <Pagination
+        page={page}
+        totalPages={totalPages}
+        onPageChange={setPage}
+        total={data.total ?? undefined}
+        showTotal={data.total !== null}
+      />
+    </div>
+  );
+};
+
+const SUB_TABS = [
+  {
+    id: "biggest",
+    label: "Biggest",
+    icon: <ListOrdered className="h-4 w-4" />,
+  },
+  {
+    id: "newest",
+    label: "Newest",
+    icon: <ListOrdered className="h-4 w-4" />,
+  },
+] as const;
+
+/**
+ * Cache Runtime panel. Counts on top, then a paginated table of keys
+ * sorted by size or recency. Values never returned (PII risk).
+ */
+export const CacheRuntimePanel = () => {
+  const cacheClient = usePluginClient(CacheApi);
+  const { data, isLoading, error } = cacheClient.getRuntimeStats.useQuery(
+    undefined,
+    { refetchInterval: REFRESH_INTERVAL_MS },
+  );
+  const [sortBy, setSortBy] = useState<SortBy>("biggest");
+
+  return (
+    <div className="space-y-4">
+      <InstanceScopeBanner
+        scope={data?.scope ?? "instance"}
+        subject="Cache"
+        recommendation="Switch to a clustered cache (e.g. Redis) for cluster-wide visibility."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Activity className="h-5 w-5" />
+            Cache Runtime
+          </CardTitle>
+          <CardDescription>
+            {data?.pluginId ? (
+              <>
+                Active provider:{" "}
+                <code className="text-xs">{data.pluginId}</code>. Refreshes
+                every {REFRESH_INTERVAL_MS / 1000}s. Backends that can&apos;t
+                report a metric cheaply show &quot;—&quot;.
+              </>
+            ) : (
+              <>Refreshes every {REFRESH_INTERVAL_MS / 1000}s.</>
+            )}
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          {error ? (
+            <div className="text-sm text-destructive">
+              Failed to load cache stats.
+            </div>
+          ) : (
+            <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+              <StatTile
+                label="Keys"
+                value={isLoading ? "…" : formatNumber(data?.keyCount)}
+                icon={Database}
+              />
+              <StatTile
+                label="Memory"
+                value={isLoading ? "…" : formatBytes(data?.sizeBytes)}
+                icon={HardDrive}
+              />
+              <StatTile
+                label="Hits"
+                value={isLoading ? "…" : formatNumber(data?.hits)}
+                icon={CheckCircle2}
+              />
+              <StatTile
+                label="Hit rate"
+                value={
+                  isLoading ? "…" : formatHitRate(data?.hits, data?.misses)
+                }
+                icon={XCircle}
+              />
+            </div>
+          )}
+
+          <div className="space-y-3">
+            <Tabs
+              items={SUB_TABS.map((t) => ({
+                id: t.id,
+                label: t.label,
+                icon: t.icon,
+              }))}
+              activeTab={sortBy}
+              onTabChange={(id) => setSortBy(id as SortBy)}
+            />
+            <TabPanel id="biggest" activeTab={sortBy}>
+              <EntriesTable sortBy="biggest" />
+            </TabPanel>
+            <TabPanel id="newest" activeTab={sortBy}>
+              <EntriesTable sortBy="newest" />
+            </TabPanel>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+};

package/src/index.tsx

@@ -1,22 +1,26 @@
-import { createFrontendPlugin } from "@checkstack/frontend-api";
-import { registerInfrastructureTab } from "@checkstack/infrastructure-common";
+import {
+  createFrontendPlugin,
+  createSlotExtension,
+} from "@checkstack/frontend-api";
+import { InfrastructureTabsSlot } from "@checkstack/infrastructure-common";
 import { pluginMetadata, cacheAccess } from "@checkstack/cache-common";
-import { CacheConfigTab } from "./components/CacheConfigTab";
+import { CacheInfrastructureTab } from "./components/CacheInfrastructureTab";
 import { HardDrive } from "lucide-react";
 
-// Register cache tab into the Infrastructure Configuration page
-registerInfrastructureTab({
-  id: "cache",
-  pluginId: pluginMetadata.pluginId,
-  label: "Cache",
-  icon: HardDrive,
-  component: CacheConfigTab,
-  readAccess: cacheAccess.settings.read,
-  manageAccess: cacheAccess.settings.manage,
-  order: 20, // After queue (10)
-});
-
 export const cachePlugin = createFrontendPlugin({
   metadata: pluginMetadata,
-  // No routes — the cache tab lives inside the infrastructure page
+  // No routes — the cache tab lives inside the infrastructure page.
+  extensions: [
+    createSlotExtension(InfrastructureTabsSlot, {
+      id: "cache.infrastructure.tab",
+      component: CacheInfrastructureTab,
+      metadata: {
+        label: "Cache",
+        icon: HardDrive,
+        readAccess: cacheAccess.settings.read,
+        manageAccess: cacheAccess.settings.manage,
+        order: 20,
+      },
+    }),
+  ],
 });