@checkstack/queue-frontend 0.0.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,164 @@
 # @checkstack/queue-frontend
 
+## 0.2.0
+
+### Minor Changes
+
+- 180be38: # Queue Lag Warning
+
+  Added a queue lag warning system that displays alerts when pending jobs exceed configurable thresholds.
+
+  ## Features
+
+  - **Backend Stats API**: New `getStats`, `getLagStatus`, and `updateLagThresholds` RPC endpoints
+  - **Signal-based Updates**: `QUEUE_LAG_CHANGED` signal for real-time frontend updates
+  - **Aggregated Stats**: `QueueManager.getAggregatedStats()` sums stats across all queues
+  - **Configurable Thresholds**: Warning (default 100) and Critical (default 500) thresholds stored in config
+  - **Dashboard Integration**: Queue lag alert displayed on main Dashboard (access-gated)
+  - **Queue Settings Page**: Lag alert and Performance Tuning guidance card with concurrency tips
+
+  ## UI Changes
+
+  - Queue lag alert banner appears on Dashboard and Queue Settings when pending jobs exceed thresholds
+  - New "Performance Tuning" card with concurrency settings guidance and bottleneck indicators
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+### Patch Changes
+
+- Updated dependencies [180be38]
+- Updated dependencies [7a23261]
+  - @checkstack/queue-common@0.2.0
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/ui@0.2.1
+  - @checkstack/signal-frontend@0.0.7
+
+## 0.1.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/queue-common@0.1.0
+  - @checkstack/ui@0.2.0
+
 ## 0.0.5
 
 ### Patch Changes

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@checkstack/queue-frontend",
-  "version": "0.0.5",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.tsx"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -15,6 +20,7 @@
     "@checkstack/common": "workspace:*",
     "@checkstack/frontend-api": "workspace:*",
     "@checkstack/queue-common": "workspace:*",
+    "@checkstack/signal-frontend": "workspace:*",
     "@checkstack/ui": "workspace:*",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",

package/src/api.ts

@@ -1,15 +1,8 @@
-import { createApiRef } from "@checkstack/frontend-api";
-import { QueueApi } from "@checkstack/queue-common";
-import type { InferClient } from "@checkstack/common";
-
 // Re-export types for convenience
 export type {
   QueuePluginDto,
   QueueConfigurationDto,
   UpdateQueueConfiguration,
 } from "@checkstack/queue-common";
-
-// QueueApiClient type inferred from the client definition
-export type QueueApiClient = InferClient<typeof QueueApi>;
-
-export const queueApiRef = createApiRef<QueueApiClient>("queue-api");
+// Client definition is in @checkstack/queue-common - use with usePluginClient
+export { QueueApi } from "@checkstack/queue-common";

package/src/components/QueueLagAlert.tsx

@@ -0,0 +1,95 @@
+import React from "react";
+import {
+  useApi,
+  accessApiRef,
+  usePluginClient,
+} from "@checkstack/frontend-api";
+import { useSignal } from "@checkstack/signal-frontend";
+import {
+  QueueApi,
+  QUEUE_LAG_CHANGED,
+  queueAccess,
+  type LagSeverity,
+} from "@checkstack/queue-common";
+import { Alert, AlertTitle, AlertDescription } from "@checkstack/ui";
+import { AlertTriangle, AlertCircle } from "lucide-react";
+
+interface QueueLagAlertProps {
+  /** Only show if user has queue settings access */
+  requireAccess?: boolean;
+}
+
+/**
+ * Displays a warning alert when queue is lagging (high pending jobs).
+ * Uses signal for real-time updates + initial fetch via useQuery.
+ */
+export const QueueLagAlert: React.FC<QueueLagAlertProps> = ({
+  requireAccess = true,
+}) => {
+  const accessApi = useApi(accessApiRef);
+  const queueClient = usePluginClient(QueueApi);
+
+  // Check access if required
+  const { allowed, loading: accessLoading } = accessApi.useAccess(
+    queueAccess.settings.read
+  );
+
+  // Fetch lag status via useQuery
+  const { data: lagStatus, isLoading } = queueClient.getLagStatus.useQuery(
+    undefined,
+    {
+      enabled: !requireAccess || allowed,
+      staleTime: 30_000, // Cache for 30 seconds
+    }
+  );
+
+  // State for real-time updates via signal
+  const [signalData, setSignalData] = React.useState<
+    | {
+        pending: number;
+        severity: LagSeverity;
+      }
+    | undefined
+  >();
+
+  // Listen for real-time lag updates
+  useSignal(QUEUE_LAG_CHANGED, (payload) => {
+    setSignalData({ pending: payload.pending, severity: payload.severity });
+  });
+
+  // Use signal data if available, otherwise use query data
+  const pending = signalData?.pending ?? lagStatus?.pending ?? 0;
+  const severity = signalData?.severity ?? lagStatus?.severity ?? "none";
+
+  // Don't render if loading, no access, or no lag
+  if (isLoading || accessLoading) {
+    return;
+  }
+
+  if (requireAccess && !allowed) {
+    return;
+  }
+
+  if (severity === "none") {
+    return;
+  }
+
+  const variant = severity === "critical" ? "error" : "warning";
+  const Icon = severity === "critical" ? AlertCircle : AlertTriangle;
+  const title =
+    severity === "critical" ? "Queue backlog critical" : "Queue building up";
+  const description =
+    severity === "critical"
+      ? `${pending} jobs pending. Consider scaling or reducing load.`
+      : `${pending} jobs pending. Some jobs may be delayed.`;
+
+  return (
+    <Alert variant={variant} className="mb-4">
+      <Icon className="h-5 w-5" />
+      <div>
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{description}</AlertDescription>
+      </div>
+    </Alert>
+  );
+};

package/src/components/UserMenuItems.tsx

@@ -3,20 +3,17 @@ import { Link } from "react-router-dom";
 import { ListOrdered } from "lucide-react";
 import type { UserMenuItemsContext } from "@checkstack/frontend-api";
 import { DropdownMenuItem } from "@checkstack/ui";
-import { qualifyPermissionId, resolveRoute } from "@checkstack/common";
+import { resolveRoute } from "@checkstack/common";
 import {
   queueRoutes,
-  permissions,
+  queueAccess,
   pluginMetadata,
 } from "@checkstack/queue-common";
 
 export const QueueUserMenuItems = ({
-  permissions: userPerms,
+  accessRules: userPerms,
 }: UserMenuItemsContext) => {
-  const qualifiedId = qualifyPermissionId(
-    pluginMetadata,
-    permissions.queueRead
-  );
+  const qualifiedId = `${pluginMetadata.pluginId}.${queueAccess.settings.read.id}`;
   const canRead = userPerms.includes("*") || userPerms.includes(qualifiedId);
 
   if (!canRead) {

package/src/index.tsx

@@ -1,36 +1,23 @@
 import {
-  rpcApiRef,
-  ApiRef,
   UserMenuItemsSlot,
   createSlotExtension,
   createFrontendPlugin,
 } from "@checkstack/frontend-api";
-import { queueApiRef, type QueueApiClient } from "./api";
 import { QueueConfigPage } from "./pages/QueueConfigPage";
 import { QueueUserMenuItems } from "./components/UserMenuItems";
 import {
   queueRoutes,
-  QueueApi,
   pluginMetadata,
-  permissions,
+  queueAccess,
 } from "@checkstack/queue-common";
 
 export const queuePlugin = createFrontendPlugin({
   metadata: pluginMetadata,
-  apis: [
-    {
-      ref: queueApiRef,
-      factory: (deps: { get: <T>(ref: ApiRef<T>) => T }): QueueApiClient => {
-        const rpcApi = deps.get(rpcApiRef);
-        return rpcApi.forPlugin(QueueApi);
-      },
-    },
-  ],
   routes: [
     {
       route: queueRoutes.routes.config,
       element: <QueueConfigPage />,
-      permission: permissions.queueRead,
+      accessRule: queueAccess.settings.read,
     },
   ],
   extensions: [
@@ -42,3 +29,4 @@ export const queuePlugin = createFrontendPlugin({
 });
 
 export * from "./api";
+export { QueueLagAlert } from "./components/QueueLagAlert";

package/src/pages/QueueConfigPage.tsx

@@ -1,11 +1,15 @@
 import { useEffect, useState } from "react";
 import {
-  useApi,
   wrapInSuspense,
-  permissionApiRef,
+  accessApiRef,
+  useApi,
+  usePluginClient,
 } from "@checkstack/frontend-api";
-import { queueApiRef } from "../api";
-import { QueuePluginDto } from "@checkstack/queue-common";
+import {
+  QueuePluginDto,
+  queueAccess,
+  QueueApi,
+} from "@checkstack/queue-common";
 import {
   Button,
   Alert,
@@ -20,105 +24,173 @@ import {
   CardTitle,
   useToast,
 } from "@checkstack/ui";
-import { AlertTriangle, Save } from "lucide-react";
+import { AlertTriangle, Save, Info, Gauge, Activity } from "lucide-react";
+import { QueueLagAlert } from "../components/QueueLagAlert";
 
 const QueueConfigPageContent = () => {
-  const api = useApi(queueApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const queueClient = usePluginClient(QueueApi);
+  const accessApi = useApi(accessApiRef);
   const toast = useToast();
-  const { allowed: canRead, loading: permissionLoading } =
-    permissionApi.useResourcePermission("queue", "read");
-  const { allowed: canUpdate } = permissionApi.useManagePermission("queue");
+  const { allowed: canRead, loading: accessLoading } = accessApi.useAccess(
+    queueAccess.settings.read
+  );
+  const { allowed: canUpdate } = accessApi.useAccess(
+    queueAccess.settings.manage
+  );
+
+  // Fetch plugins and configuration
+  const { data: pluginsList } = queueClient.getPlugins.useQuery();
+  const { data: configuration, refetch: refetchConfig } =
+    queueClient.getConfiguration.useQuery();
+  const updateConfigMutation = queueClient.updateConfiguration.useMutation();
 
-  const [plugins, setPlugins] = useState<QueuePluginDto[]>([]);
   const [selectedPluginId, setSelectedPluginId] = useState<string>("");
   const [config, setConfig] = useState<Record<string, unknown>>({});
-  const [isSaving, setIsSaving] = useState(false);
 
+  // Sync state with fetched data
   useEffect(() => {
-    const fetchData = async () => {
-      const [pluginsList, configuration] = await Promise.all([
-        api.getPlugins(),
-        api.getConfiguration(),
-      ]);
-      setPlugins(pluginsList);
+    if (configuration) {
       setSelectedPluginId(configuration.pluginId);
       setConfig(configuration.config);
-    };
-    fetchData();
-  }, [api]);
+    }
+  }, [configuration]);
 
   const handleSave = async () => {
     if (!selectedPluginId) return;
-    setIsSaving(true);
     try {
-      await api.updateConfiguration({
+      await updateConfigMutation.mutateAsync({
         pluginId: selectedPluginId,
         config,
       });
       toast.success("Configuration saved successfully!");
+      refetchConfig();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       toast.error(`Failed to save configuration: ${message}`);
-    } finally {
-      setIsSaving(false);
     }
   };
 
   const isMemoryQueue = selectedPluginId === "memory";
+  const plugins: QueuePluginDto[] = pluginsList ?? [];
+  const isSaving = updateConfigMutation.isPending;
 
   return (
     <PageLayout
       title="Queue Settings"
       subtitle="Configure the queue system for background jobs"
-      loading={permissionLoading}
+      loading={accessLoading}
       allowed={canRead}
       maxWidth="3xl"
     >
-      <Card>
-        <CardHeader>
-          <CardTitle>Queue Configuration</CardTitle>
-          <p className="text-sm text-muted-foreground">
-            Select and configure the queue plugin
-          </p>
-        </CardHeader>
-        <CardContent className="space-y-6">
-          {isMemoryQueue && (
-            <Alert variant="warning">
-              <AlertTriangle className="h-5 w-5" />
-              <div>
-                <AlertTitle>In-Memory Queue Warning</AlertTitle>
-                <AlertDescription>
-                  The in-memory queue is suitable for development and
-                  single-instance deployments only. It will not scale across
-                  multiple instances and jobs will be lost on restart. For
-                  production environments with multiple instances, consider
-                  using a persistent queue implementation.
-                </AlertDescription>
+      <QueueLagAlert requireAccess={false} />
+      <div className="space-y-6">
+        <Card>
+          <CardHeader>
+            <CardTitle>Queue Configuration</CardTitle>
+            <p className="text-sm text-muted-foreground">
+              Select and configure the queue plugin
+            </p>
+          </CardHeader>
+          <CardContent className="space-y-6">
+            {isMemoryQueue && (
+              <Alert variant="warning">
+                <AlertTriangle className="h-5 w-5" />
+                <div>
+                  <AlertTitle>In-Memory Queue Warning</AlertTitle>
+                  <AlertDescription>
+                    The in-memory queue is suitable for development and
+                    single-instance deployments only. It will not scale across
+                    multiple instances and jobs will be lost on restart. For
+                    production environments with multiple instances, consider
+                    using a persistent queue implementation.
+                  </AlertDescription>
+                </div>
+              </Alert>
+            )}
+
+            <PluginConfigForm
+              label="Queue Plugin"
+              plugins={plugins}
+              selectedPluginId={selectedPluginId}
+              onPluginChange={(value) => {
+                setSelectedPluginId(value);
+                setConfig({});
+              }}
+              config={config}
+              onConfigChange={setConfig}
+              disabled={!canUpdate}
+            />
+          </CardContent>
+          <CardFooter className="flex justify-end gap-2">
+            <Button onClick={handleSave} disabled={!canUpdate || isSaving}>
+              <Save className="mr-2 h-4 w-4" />
+              {isSaving ? "Saving..." : "Save Configuration"}
+            </Button>
+          </CardFooter>
+        </Card>
+
+        {/* Performance Guidance */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">
+              <Info className="h-5 w-5" />
+              Performance Tuning
+            </CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div className="grid gap-4 md:grid-cols-2">
+              <div className="space-y-2">
+                <h4 className="flex items-center gap-2 font-medium">
+                  <Gauge className="h-4 w-4" />
+                  Concurrency Settings
+                </h4>
+                <ul className="text-sm text-muted-foreground space-y-1 list-disc list-inside">
+                  <li>
+                    <strong>Default (10)</strong>: Conservative, safe for most
+                    workloads
+                  </li>
+                  <li>
+                    <strong>Moderate (25-50)</strong>: Good for I/O-bound health
+                    checks
+                  </li>
+                  <li>
+                    <strong>Aggressive (100)</strong>: Maximum, monitor resource
+                    usage
+                  </li>
+                </ul>
+                <p className="text-xs text-muted-foreground mt-2">
+                  Formula: throughput ≈ concurrency / avg_job_duration
+                </p>
               </div>
-            </Alert>
-          )}
 
-          <PluginConfigForm
-            label="Queue Plugin"
-            plugins={plugins}
-            selectedPluginId={selectedPluginId}
-            onPluginChange={(value) => {
-              setSelectedPluginId(value);
-              setConfig({});
-            }}
-            config={config}
-            onConfigChange={setConfig}
-            disabled={!canUpdate}
-          />
-        </CardContent>
-        <CardFooter className="flex justify-end gap-2">
-          <Button onClick={handleSave} disabled={!canUpdate || isSaving}>
-            <Save className="mr-2 h-4 w-4" />
-            {isSaving ? "Saving..." : "Save Configuration"}
-          </Button>
-        </CardFooter>
-      </Card>
+              <div className="space-y-2">
+                <h4 className="flex items-center gap-2 font-medium">
+                  <Activity className="h-4 w-4" />
+                  Bottleneck Indicators
+                </h4>
+                <ul className="text-sm text-muted-foreground space-y-1 list-disc list-inside">
+                  <li>
+                    <strong>Jobs queueing</strong>: Increase concurrency or
+                    scale horizontally
+                  </li>
+                  <li>
+                    <strong>High CPU (&gt;70%)</strong>: Scale horizontally,
+                    don't increase concurrency
+                  </li>
+                  <li>
+                    <strong>DB connection errors</strong>: Reduce concurrency or
+                    increase pool
+                  </li>
+                  <li>
+                    <strong>Rate limit errors</strong>: Reduce concurrency for
+                    external checks
+                  </li>
+                </ul>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
     </PageLayout>
   );
 };