@checkstack/queue-backend 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/queue-backend
 
+## 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
+
+### Patch Changes
+
+- Updated dependencies [180be38]
+- Updated dependencies [7a23261]
+  - @checkstack/queue-common@0.2.0
+  - @checkstack/queue-api@0.1.0
+  - @checkstack/common@0.3.0
+  - @checkstack/backend-api@0.3.2
+
 ## 0.1.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/queue-backend",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "./dist/index.d.ts",

package/src/router.test.ts

@@ -31,10 +31,21 @@ describe("Queue Router", () => {
     setActiveBackend: mock(() =>
       Promise.resolve({ success: true, migratedRecurringJobs: 0, warnings: [] })
     ),
+    getAggregatedStats: mock(() =>
+      Promise.resolve({
+        pending: 50,
+        processing: 5,
+        completed: 100,
+        failed: 2,
+        consumerGroups: 3,
+      })
+    ),
   };
 
   const mockConfigService: any = {
     getRedacted: mock(() => Promise.resolve({ concurrency: 10 })),
+    get: mock(() => Promise.resolve(undefined)),
+    set: mock(() => Promise.resolve()),
   };
 
   const router = createQueueRouter(mockConfigService);
@@ -81,4 +92,131 @@ describe("Queue Router", () => {
     expect(result.pluginId).toBe("memory");
     expect(mockManager.setActiveBackend).toHaveBeenCalled();
   });
+
+  describe("Queue Stats", () => {
+    it("getStats returns aggregated stats from QueueManager", async () => {
+      const context = createMockRpcContext({
+        user: mockUser,
+        queueManager: mockManager,
+      });
+
+      const result = await call(router.getStats, undefined, { context });
+      expect(result.pending).toBe(50);
+      expect(result.processing).toBe(5);
+      expect(result.completed).toBe(100);
+      expect(result.failed).toBe(2);
+      expect(mockManager.getAggregatedStats).toHaveBeenCalled();
+    });
+  });
+
+  describe("Queue Lag Status", () => {
+    it("getLagStatus returns 'none' severity when pending is below warning threshold", async () => {
+      const lowPendingManager = {
+        ...mockManager,
+        getAggregatedStats: mock(() => Promise.resolve({ pending: 50 })),
+      };
+      const context = createMockRpcContext({
+        user: mockUser,
+        queueManager: lowPendingManager,
+      });
+
+      const result = await call(router.getLagStatus, undefined, { context });
+      expect(result.severity).toBe("none");
+      expect(result.pending).toBe(50);
+      expect(result.thresholds.warningThreshold).toBe(100);
+      expect(result.thresholds.criticalThreshold).toBe(500);
+    });
+
+    it("getLagStatus returns 'warning' severity when pending exceeds warning threshold", async () => {
+      const warningPendingManager = {
+        ...mockManager,
+        getAggregatedStats: mock(() => Promise.resolve({ pending: 150 })),
+      };
+      const context = createMockRpcContext({
+        user: mockUser,
+        queueManager: warningPendingManager,
+      });
+
+      const result = await call(router.getLagStatus, undefined, { context });
+      expect(result.severity).toBe("warning");
+      expect(result.pending).toBe(150);
+    });
+
+    it("getLagStatus returns 'critical' severity when pending exceeds critical threshold", async () => {
+      const criticalPendingManager = {
+        ...mockManager,
+        getAggregatedStats: mock(() => Promise.resolve({ pending: 600 })),
+      };
+      const context = createMockRpcContext({
+        user: mockUser,
+        queueManager: criticalPendingManager,
+      });
+
+      const result = await call(router.getLagStatus, undefined, { context });
+      expect(result.severity).toBe("critical");
+      expect(result.pending).toBe(600);
+    });
+
+    it("getLagStatus uses custom thresholds from config", async () => {
+      const customConfigService = {
+        ...mockConfigService,
+        get: mock(() =>
+          Promise.resolve({
+            warningThreshold: 20,
+            criticalThreshold: 50,
+          })
+        ),
+      };
+      const customRouter = createQueueRouter(customConfigService);
+      const pendingManager = {
+        ...mockManager,
+        getAggregatedStats: mock(() => Promise.resolve({ pending: 30 })),
+      };
+      const context = createMockRpcContext({
+        user: mockUser,
+        queueManager: pendingManager,
+      });
+
+      const result = await call(customRouter.getLagStatus, undefined, {
+        context,
+      });
+      expect(result.severity).toBe("warning");
+      expect(result.thresholds.warningThreshold).toBe(20);
+      expect(result.thresholds.criticalThreshold).toBe(50);
+    });
+  });
+
+  describe("Update Lag Thresholds", () => {
+    it("updateLagThresholds stores new thresholds", async () => {
+      const context = createMockRpcContext({
+        user: mockUser,
+      });
+
+      const result = await call(
+        router.updateLagThresholds,
+        { warningThreshold: 200, criticalThreshold: 1000 },
+        { context }
+      );
+
+      expect(result.warningThreshold).toBe(200);
+      expect(result.criticalThreshold).toBe(1000);
+      expect(mockConfigService.set).toHaveBeenCalled();
+    });
+
+    it("updateLagThresholds rejects if warning >= critical", async () => {
+      const context = createMockRpcContext({
+        user: mockUser,
+      });
+
+      await expect(
+        call(
+          router.updateLagThresholds,
+          { warningThreshold: 500, criticalThreshold: 100 },
+          { context }
+        )
+      ).rejects.toThrow(
+        "Warning threshold must be less than critical threshold"
+      );
+    });
+  });
 });

package/src/router.ts

@@ -4,13 +4,43 @@ import {
   RpcContext,
   autoAuthMiddleware,
 } from "@checkstack/backend-api";
-import { queueContract } from "@checkstack/queue-common";
+import {
+  queueContract,
+  QueueLagThresholdsSchema,
+  type QueueLagThresholds,
+  type LagSeverity,
+} from "@checkstack/queue-common";
 import { implement, ORPCError } from "@orpc/server";
 
 const os = implement(queueContract)
   .$context<RpcContext>()
   .use(autoAuthMiddleware);
 
+// Config key for lag thresholds
+const LAG_THRESHOLDS_KEY = "queue:lag-thresholds";
+
+// Default thresholds
+const DEFAULT_THRESHOLDS: QueueLagThresholds = {
+  warningThreshold: 100,
+  criticalThreshold: 500,
+};
+
+/**
+ * Calculate lag severity based on pending count and thresholds
+ */
+function calculateSeverity(
+  pending: number,
+  thresholds: QueueLagThresholds
+): LagSeverity {
+  if (pending >= thresholds.criticalThreshold) {
+    return "critical";
+  }
+  if (pending >= thresholds.warningThreshold) {
+    return "warning";
+  }
+  return "none";
+}
+
 export const createQueueRouter = (configService: ConfigService) => {
   return os.router({
     getPlugins: os.getPlugins.handler(async ({ context }) => {
@@ -67,5 +97,54 @@ export const createQueueRouter = (configService: ConfigService) => {
         };
       }
     ),
+
+    getStats: os.getStats.handler(async ({ context }) => {
+      const stats = await context.queueManager.getAggregatedStats();
+      return stats;
+    }),
+
+    getLagStatus: os.getLagStatus.handler(async ({ context }) => {
+      const stats = await context.queueManager.getAggregatedStats();
+
+      // Load thresholds from config
+      const thresholds =
+        (await configService.get<QueueLagThresholds>(
+          LAG_THRESHOLDS_KEY,
+          QueueLagThresholdsSchema,
+          1
+        )) ?? DEFAULT_THRESHOLDS;
+
+      const severity = calculateSeverity(stats.pending, thresholds);
+
+      return {
+        pending: stats.pending,
+        severity,
+        thresholds,
+      };
+    }),
+
+    updateLagThresholds: os.updateLagThresholds.handler(
+      async ({ input, context }) => {
+        // Validate that warning < critical
+        if (input.warningThreshold >= input.criticalThreshold) {
+          throw new ORPCError("BAD_REQUEST", {
+            message: "Warning threshold must be less than critical threshold",
+          });
+        }
+
+        await configService.set(
+          LAG_THRESHOLDS_KEY,
+          QueueLagThresholdsSchema,
+          1,
+          input
+        );
+
+        context.logger.info(
+          `Queue lag thresholds updated: warning=${input.warningThreshold}, critical=${input.criticalThreshold}`
+        );
+
+        return input;
+      }
+    ),
   });
 };