@checkstack/queue-frontend 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @checkstack/queue-frontend
 
+## 0.4.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/queue-common@0.4.0
+  - @checkstack/signal-frontend@0.1.2
+
 ## 0.3.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/queue-frontend",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,12 +21,12 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
-    "@checkstack/frontend-api": "0.4.1",
-    "@checkstack/infrastructure-common": "0.2.2",
-    "@checkstack/queue-common": "0.3.0",
-    "@checkstack/signal-frontend": "0.1.0",
-    "@checkstack/ui": "1.7.0",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/frontend-api": "0.4.2",
+    "@checkstack/infrastructure-common": "0.2.3",
+    "@checkstack/queue-common": "0.3.1",
+    "@checkstack/signal-frontend": "0.1.1",
+    "@checkstack/ui": "1.7.1",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "lucide-react": "^0.468.0",
@@ -37,7 +37,7 @@
   "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/QueueInfrastructureTab.tsx

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

package/src/components/QueueRuntimePanel.tsx

@@ -0,0 +1,328 @@
+import { useState } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { QueueApi, type JobStateDto } from "@checkstack/queue-common";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  InstanceScopeBanner,
+  Pagination,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tabs,
+  TabPanel,
+} from "@checkstack/ui";
+import {
+  Activity,
+  AlertTriangle,
+  CheckCircle2,
+  Clock,
+  Hourglass,
+  Loader2,
+  PlayCircle,
+} from "lucide-react";
+
+const REFRESH_INTERVAL_MS = 5000;
+const PAGE_SIZE = 25;
+
+const formatNumber = (n: number) =>
+  n.toLocaleString(undefined, { maximumFractionDigits: 0 });
+
+const formatRelative = (date?: Date) => {
+  if (!date) return "—";
+  const ms = Date.now() - date.getTime();
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  return `${Math.round(hr / 24)}d ago`;
+};
+
+const formatDuration = (start?: Date, end?: Date) => {
+  if (!start) return "—";
+  const finish = end ?? new Date();
+  const ms = finish.getTime() - start.getTime();
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.round(ms / 60_000)}m`;
+};
+
+const truncateMiddle = (s: string, head = 8, tail = 6) => {
+  if (s.length <= head + tail + 1) return s;
+  return `${s.slice(0, head)}…${s.slice(-tail)}`;
+};
+
+const formatCountdown = (target?: Date) => {
+  if (!target) return "—";
+  const ms = target.getTime() - Date.now();
+  if (ms <= 0) return "now";
+  const sec = Math.round(ms / 1000);
+  if (sec < 60) return `in ${sec}s`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `in ${min}m`;
+  const hr = Math.round(min / 60);
+  if (hr < 24) return `in ${hr}h`;
+  return `in ${Math.round(hr / 24)}d`;
+};
+
+interface CountTileProps {
+  label: string;
+  value: number | undefined;
+  icon: React.ComponentType<{ className?: string }>;
+  tone: "default" | "warning" | "danger" | "success";
+}
+
+const toneClasses: Record<CountTileProps["tone"], string> = {
+  default: "text-muted-foreground",
+  warning: "text-amber-600 dark:text-amber-400",
+  danger: "text-destructive",
+  success: "text-emerald-600 dark:text-emerald-400",
+};
+
+const CountTile = ({ label, value, icon: Icon, tone }: CountTileProps) => (
+  <div className="flex items-center gap-3 rounded-lg border bg-card px-4 py-3">
+    <Icon className={`h-5 w-5 shrink-0 ${toneClasses[tone]}`} />
+    <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 === undefined ? "—" : formatNumber(value)}
+      </div>
+    </div>
+  </div>
+);
+
+interface JobsTableProps {
+  state: JobStateDto;
+}
+
+const JobsTable = ({ state }: JobsTableProps) => {
+  const queueClient = usePluginClient(QueueApi);
+  const [page, setPage] = useState(1);
+  const offset = (page - 1) * PAGE_SIZE;
+
+  const { data, isLoading, error } = queueClient.listJobs.useQuery(
+    { state, offset, limit: PAGE_SIZE },
+    { refetchInterval: REFRESH_INTERVAL_MS },
+  );
+
+  if (error) {
+    return <p className="text-sm text-destructive">Failed to load jobs.</p>;
+  }
+  if (isLoading) {
+    return <p className="text-sm text-muted-foreground">Loading…</p>;
+  }
+  if (!data || data.items.length === 0) {
+    return <p className="text-sm text-muted-foreground">No {state} jobs.</p>;
+  }
+
+  const showFinished = state === "completed" || state === "failed";
+  const showError = state === "failed";
+  const showState = state === "pending";
+  const showNextRun =
+    state === "pending" || state === "delayed" || state === "waiting";
+
+  // total may be null for backends that can't compute it cheaply; in that
+  // case we synthesise totalPages from hasMore so the next button stays usable.
+  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 className="w-[140px]">Job ID</TableHead>
+            <TableHead>Queue</TableHead>
+            {showState && <TableHead>State</TableHead>}
+            <TableHead>Enqueued</TableHead>
+            {showNextRun && <TableHead>Next run</TableHead>}
+            {state === "active" && <TableHead>Running for</TableHead>}
+            {showFinished && <TableHead>Finished</TableHead>}
+            {showFinished && <TableHead>Duration</TableHead>}
+            <TableHead className="text-right">Attempts</TableHead>
+            {showError && <TableHead>Error</TableHead>}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {data.items.map((job) => (
+            <TableRow key={job.id}>
+              <TableCell
+                className="font-mono text-xs whitespace-nowrap"
+                title={job.id}
+              >
+                {truncateMiddle(job.id)}
+              </TableCell>
+              <TableCell>{job.name ?? "—"}</TableCell>
+              {showState && (
+                <TableCell className="capitalize">
+                  {job.recurring ? "Recurring" : job.state}
+                </TableCell>
+              )}
+              <TableCell title={job.enqueuedAt.toString()}>
+                {formatRelative(job.enqueuedAt)}
+              </TableCell>
+              {showNextRun && (
+                <TableCell title={job.nextRunAt?.toString()}>
+                  {formatCountdown(job.nextRunAt)}
+                </TableCell>
+              )}
+              {state === "active" && (
+                <TableCell>{formatDuration(job.startedAt)}</TableCell>
+              )}
+              {showFinished && (
+                <TableCell title={job.finishedAt?.toString()}>
+                  {formatRelative(job.finishedAt)}
+                </TableCell>
+              )}
+              {showFinished && (
+                <TableCell>
+                  {formatDuration(job.startedAt, job.finishedAt)}
+                </TableCell>
+              )}
+              <TableCell className="text-right tabular-nums">
+                {job.attempts}
+              </TableCell>
+              {showError && (
+                <TableCell
+                  className="max-w-[280px] truncate text-destructive"
+                  title={job.failedReason}
+                >
+                  {job.failedReason ?? "—"}
+                </TableCell>
+              )}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+      <Pagination
+        page={page}
+        totalPages={totalPages}
+        onPageChange={setPage}
+        total={data.total ?? undefined}
+        showTotal={data.total !== null}
+      />
+    </div>
+  );
+};
+
+const SUB_TABS = [
+  { id: "pending", label: "Pending", icon: <Hourglass className="h-4 w-4" /> },
+  { id: "active", label: "Active", icon: <PlayCircle className="h-4 w-4" /> },
+  {
+    id: "failed",
+    label: "Recent failed",
+    icon: <AlertTriangle className="h-4 w-4" />,
+  },
+  {
+    id: "completed",
+    label: "Recent completed",
+    icon: <CheckCircle2 className="h-4 w-4" />,
+  },
+] as const;
+
+/**
+ * Queue Runtime panel. Aggregated counts, then a paginated tabbed listing
+ * of Active / Recent failed / Recent completed jobs. Job payloads are
+ * deliberately not surfaced — they may carry secrets.
+ */
+export const QueueRuntimePanel = () => {
+  const queueClient = usePluginClient(QueueApi);
+  const { data: stats, isLoading, error } = queueClient.getStats.useQuery(
+    undefined,
+    { refetchInterval: REFRESH_INTERVAL_MS },
+  );
+  const [activeSubTab, setActiveSubTab] = useState<JobStateDto>("pending");
+
+  return (
+    <div className="space-y-4">
+      <InstanceScopeBanner
+        scope={stats?.scope ?? "instance"}
+        subject="Queue"
+        recommendation="Switch to a Redis-backed queue (e.g. BullMQ) for cluster-wide visibility."
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="flex items-center gap-2">
+            <Activity className="h-5 w-5" />
+            Queue Runtime
+          </CardTitle>
+          <CardDescription>
+            Live aggregated job counts. Refreshes every{" "}
+            {REFRESH_INTERVAL_MS / 1000}s.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          {error ? (
+            <div className="text-sm text-destructive">
+              Failed to load queue stats.
+            </div>
+          ) : (
+            <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+              <CountTile
+                label="Pending"
+                value={isLoading ? undefined : stats?.pending}
+                icon={Clock}
+                tone="warning"
+              />
+              <CountTile
+                label="Processing"
+                value={isLoading ? undefined : stats?.processing}
+                icon={Loader2}
+                tone="default"
+              />
+              <CountTile
+                label="Completed"
+                value={isLoading ? undefined : stats?.completed}
+                icon={CheckCircle2}
+                tone="success"
+              />
+              <CountTile
+                label="Failed"
+                value={isLoading ? undefined : stats?.failed}
+                icon={AlertTriangle}
+                tone="danger"
+              />
+            </div>
+          )}
+
+          <div className="space-y-3">
+            <Tabs
+              items={SUB_TABS.map((t) => ({
+                id: t.id,
+                label: t.label,
+                icon: t.icon,
+              }))}
+              activeTab={activeSubTab}
+              onTabChange={(id) => setActiveSubTab(id as JobStateDto)}
+            />
+            <TabPanel id="pending" activeTab={activeSubTab}>
+              <JobsTable state="pending" />
+            </TabPanel>
+            <TabPanel id="active" activeTab={activeSubTab}>
+              <JobsTable state="active" />
+            </TabPanel>
+            <TabPanel id="failed" activeTab={activeSubTab}>
+              <JobsTable state="failed" />
+            </TabPanel>
+            <TabPanel id="completed" activeTab={activeSubTab}>
+              <JobsTable state="completed" />
+            </TabPanel>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+};

package/src/index.tsx

@@ -1,25 +1,28 @@
-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, queueAccess } from "@checkstack/queue-common";
-import { QueueConfigTab } from "./components/QueueConfigTab";
+import { QueueInfrastructureTab } from "./components/QueueInfrastructureTab";
 import { Gauge } from "lucide-react";
 
-// Register queue tab into the Infrastructure Configuration page
-registerInfrastructureTab({
-  id: "queue",
-  pluginId: pluginMetadata.pluginId,
-  label: "Queue",
-  icon: Gauge,
-  component: QueueConfigTab,
-  readAccess: queueAccess.settings.read,
-  manageAccess: queueAccess.settings.manage,
-  order: 10, // First tab
-});
-
 export const queuePlugin = createFrontendPlugin({
   metadata: pluginMetadata,
-  // No routes — the queue tab lives inside the infrastructure page now
-  // Former standalone /queue/config route is replaced by /infrastructure/config
+  // No routes — the queue tab lives inside the infrastructure page.
+  extensions: [
+    createSlotExtension(InfrastructureTabsSlot, {
+      id: "queue.infrastructure.tab",
+      component: QueueInfrastructureTab,
+      metadata: {
+        label: "Queue",
+        icon: Gauge,
+        readAccess: queueAccess.settings.read,
+        manageAccess: queueAccess.settings.manage,
+        order: 10,
+      },
+    }),
+  ],
 });
 
 export * from "./api";