@mayurbhusare/resilient-queue-ui 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 resilient-queue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,205 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @mayurbhusare/resilient-queue-ui
+
+An administration dashboard and REST API adapter for [`@mayurbhusare/resilient-queue`](https://www.npmjs.com/package/@mayurbhusare/resilient-queue).
+
+Provides real-time queue observability, metrics inspection, Dead-Letter Queue (DLQ) exploration, and deep job diagnostics with zero framework lock-in.
+
+---
+
+## Features
+
+- **Real-Time Queue Telemetry**: Inspect waiting, active, delayed, and dead-letter job counts in real time via atomic queue metrics.
+- **Dead-Letter Queue (DLQ) Explorer**: Browse and inspect failed jobs, complete with failure reasons, retry counts, stall metadata, and corrupted JSON resilience.
+- **Deep Job Diagnostics**: Search and inspect individual job descriptors by ID, displaying execution progress (0–100%), timestamps, data payloads, and return values.
+- **Framework-Agnostic Adapters**: Mount the dashboard seamlessly into existing **Express** or **Fastify** applications, or run it as a standalone monitoring server.
+- **Distributed Safety**: Supports multi-queue configurations and distributed Redis deployments without requiring invasive hooks in worker processes.
+
+---
+
+## Installation
+
+Install `@mayurbhusare/resilient-queue-ui` alongside its peer dependency, `@mayurbhusare/resilient-queue`:
+
+```bash
+# npm
+npm install @mayurbhusare/resilient-queue-ui @mayurbhusare/resilient-queue
+
+# yarn
+yarn add @mayurbhusare/resilient-queue-ui @mayurbhusare/resilient-queue
+
+# pnpm
+pnpm add @mayurbhusare/resilient-queue-ui @mayurbhusare/resilient-queue
+```
+
+### Runtime & Peer Dependency Requirements
+
+| Requirement | Supported Version Range |
+| :--- | :--- |
+| **Node.js** | `>=18.0.0` (LTS 18, 20, 22) |
+| [`@mayurbhusare/resilient-queue`](https://www.npmjs.com/package/@mayurbhusare/resilient-queue) | `^2.2.0` |
+
+---
+
+## Integration Examples
+
+The package is designed with a decoupled architecture where core dashboard dispatchers are wrapped by lightweight framework adapters.
+
+### 1. Express Integration
+
+```javascript
+const express = require("express");
+const { ResilientQueue } = require("@mayurbhusare/resilient-queue");
+const { createExpressAdapter } = require("@mayurbhusare/resilient-queue-ui");
+
+const app = express();
+
+const emailQueue = new ResilientQueue({ redisUrl: "redis://127.0.0.1:6379", keyPrefix: "rq:emails" });
+const videoQueue = new ResilientQueue({ redisUrl: "redis://127.0.0.1:6379", keyPrefix: "rq:video" });
+
+// Host application authentication (MANDATORY)
+app.use("/admin/queues", authMiddleware);
+
+// Mount dashboard UI & REST API
+app.use(
+  "/admin/queues",
+  createExpressAdapter({
+    queues: {
+      "emails": emailQueue,
+      "video-transcoding": videoQueue
+    }
+  })
+);
+
+app.listen(3000, () => {
+  console.log("Admin dashboard active at http://localhost:3000/admin/queues");
+});
+```
+
+### 2. Fastify Integration
+
+```javascript
+const fastify = require("fastify")();
+const { ResilientQueue } = require("@mayurbhusare/resilient-queue");
+const { fastifyDashboardPlugin } = require("@mayurbhusare/resilient-queue-ui");
+
+const orderQueue = new ResilientQueue({ redisUrl: "redis://127.0.0.1:6379", keyPrefix: "rq:orders" });
+
+// Register dashboard plugin under a prefix with auth hook
+fastify.register(fastifyDashboardPlugin, {
+  prefix: "/admin/queues",
+  queues: {
+    "orders": orderQueue
+  },
+  preHandler: fastifyAuthHook
+});
+
+fastify.listen({ port: 3000 });
+```
+
+---
+
+## Dashboard UI & Frontend Architecture
+
+The package includes a built-in, lightweight administration dashboard served directly by the Express and Fastify adapters:
+
+- **Clean, Responsive Layout**: Includes a sidebar navigation area and responsive drawer for mobile devices.
+- **Views**:
+  - **Queue Overview**: Consumes `GET /api/queues` with real-time aggregate telemetry cards, paused/active/closed/unavailable/error badges, client-side search and status filtering, multi-column sorting (with strict non-zero distinction for unavailable metrics), direct row-level navigation to DLQ Explorer and Job Inspector, and configurable background polling.
+  - **Dead Letter Queue (DLQ) Explorer**: Read-only browser for dead-letter jobs with pagination, sort order toggle, corrupted JSON resilience, failure diagnostics, payload inspection, and cross-linking to Job Inspector.
+  - **Job Inspector**: Comprehensive job inspection view supporting lookups by queue and job ID (`GET /api/queues/:queueName/jobs/:jobId`), displaying execution state badges, progress bar, lifecycle timestamps, failure diagnostics, input data payloads, and return values.
+- **Operational Diagnostics**: Actionable, structured guidance for known API error codes (`QUEUE_CLOSED`, `QUEUE_NOT_FOUND`, `JOB_NOT_FOUND`, `NOT_SUPPORTED`, `VALIDATION_ERROR`, `INTERNAL_ERROR`), clearly distinguishing core library version compatibility disclosures from missing queues, closed queue instances, and server errors.
+- **Robust UI States**: Handles loading spinners, empty states (with server configuration snippets), empty search filter states, and temporary sync failure banners with cached queue retention.
+- **Accessibility & Keyboard Usability**:
+  - **Full Keyboard Operability**: Complete keyboard accessibility across search filters, sort headers, drawer navigation, and table actions with high-contrast `:focus-visible` focus rings.
+  - **Skip to Main Content**: Accessible skip link (`#content-container`) enables assistive technology users to bypass repetitive navigation.
+  - **Discrete Screen-Reader Announcements**: Dedicated polite ARIA live announcer (`#live-announcer`) provides non-intrusive status updates during navigation and metric refreshes without DOM chattering.
+  - **Color-Independent Status**: Badges pair semantic colors with distinct visual glyphs (`●`, `⏸`, `■`, `⚠️`, `—`) and explicit ARIA labels so status is never conveyed by color alone.
+  - **Mobile Drawer Usability**: Includes focus trapping inside the mobile navigation menu, backdrop tap-to-dismiss, and Escape key dismissal with focus restoration to the trigger button.
+  - **Focus & Cursor Preservation**: Preserves active focus, input text, and cursor selection ranges across background metric auto-refresh cycles.
+  - **Reduced Motion Support**: Honored via `@media (prefers-reduced-motion: reduce)` to freeze animated spinners and disable non-essential transitions.
+- **Zero External Frontend Dependencies**: Pure semantic HTML5, modern CSS3 with CSS variables, and modular vanilla JavaScript.
+
+### Reusable Frontend API Client
+
+You can use the frontend API client directly in Node.js, bundlers, or the browser:
+
+```javascript
+const { ApiClient, ApiError } = require("@mayurbhusare/resilient-queue-ui");
+
+const client = new ApiClient({
+  baseUrl: "http://localhost:3000/admin/queues"
+});
+
+// Fetch all registered queues and metrics
+const { queues } = await client.getQueues();
+
+// Fetch metrics for a specific queue
+const metrics = await client.getQueueMetrics("emails");
+
+// Fetch DLQ entries with pagination
+const dlq = await client.getQueueDLQ("emails", { start: 0, limit: 25, order: "desc" });
+
+// Fetch individual job descriptor
+const { job } = await client.getJob("emails", "job-123");
+```
+
+### Core Compatibility & Version Support
+
+> [!NOTE]
+> - **Full Live Functionality (`>=2.2.0`)**: Real-time telemetry metrics, DLQ exploration, pause/resume detection, and deep job inspection via `queue.getJob(jobId)` are fully supported with [`@mayurbhusare/resilient-queue@>=2.2.0`](https://www.npmjs.com/package/@mayurbhusare/resilient-queue).
+> - **Legacy Compatibility (`<2.2.0`)**: If paired with an earlier core release lacking `getJob()` (such as `v2.0.2`), the dashboard adapter gracefully returns `501 NOT_SUPPORTED` and the UI renders a compatibility notice without crashing, while all other dashboard features (Overview telemetry, DLQ Explorer, and HTTP adapters) remain fully operational.
+
+---
+
+## Testing & Development
+
+Run the complete test suite:
+
+```bash
+# Run all tests (unit, integration, and frontend)
+npm test
+
+# Run frontend tests (ApiClient and UI views)
+npm run test:frontend
+
+# Run unit tests
+npm run test:unit
+
+# Run adapter integration tests
+npm run test:integration
+```
+
+## Security Considerations
+
+> [!CAUTION]
+> **Host Authentication & Authorization Required**:  
+> Job payloads (`job.data`), execution results (`job.result`), and error diagnostics (`job.failureReason`) may contain sensitive user information, credentials, financial details, or internal system errors.
+
+1. **No Built-in Authentication or Authorization**: The package provides zero built-in authentication, user models, or permission schemes. Host applications **must** guard both static UI routes and `/api/*` endpoints with authentication middleware.
+2. **Apply Authentication Barriers**: Protect all dashboard routes behind your application's existing authentication stack (e.g., Express sessions/JWT, Fastify `preHandler` hooks, or reverse-proxy authentication such as OAuth2-Proxy / Cloudflare Access / AWS ALB).
+3. **Queue-Level Authorization**: If different teams or tenants share the same service, apply queue-level authorization in host middleware to restrict specific queues by user role.
+4. **CORS is NOT Authentication**: Permissive CORS headers (e.g. `Access-Control-Allow-Origin: *`) do **not** protect or authenticate endpoints. Never enable unauthenticated cross-origin access to dashboard routes.
+5. **Caching Protection**: All API endpoints emit `Cache-Control: no-store` and `X-Content-Type-Options: nosniff` to prevent proxy or browser caching of sensitive job data.
+6. **Credential Redaction**: Internal Redis and database connection URIs (e.g., `redis://user:pass@host:port`) and auth tokens in 500 internal error responses are automatically scrubbed and redacted to `[redacted]`.
+7. **Never Expose Publicly**: Never mount `@mayurbhusare/resilient-queue-ui` routes on an unauthenticated, publicly accessible endpoint. Bind management processes to private VPC networks or loopback interfaces where possible.
+
+For full architectural details, threat models, Express and Fastify integration patterns, and the production checklist, see the [Security Guide (docs/security.md)](./docs/security.md) and runnable [Examples (examples/)](./examples/README.md).
+
+---
+
+## API Specification
+
+The REST API contract powering the dashboard is detailed in [docs/api-contract.md](./docs/api-contract.md).
+
+---
+
+## Architecture & Portability
+
+- **No Root Coupling**: This package maintains independent dependencies, configuration, and documentation, allowing seamless extraction into a dedicated repository.
+- **Strict Public API Usage**: The package interacts with `@mayurbhusare/resilient-queue` exclusively through its published public interface (`import { ResilientQueue } from "@mayurbhusare/resilient-queue"`), avoiding any reliance on internal submodule paths.
+
+---
+
+## License
+
+[MIT](./LICENSE) &copy; 2026 Resilient Queue.

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@mayurbhusare/resilient-queue-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Standalone administration dashboard and API adapter for @mayurbhusare/resilient-queue",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./api-client": "./src/ui/api-client.js",
+    "./ui/*": "./src/ui/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "commonjs",
+  "license": "MIT",
+  "author": "Mayur S. Bhusare",
+  "keywords": [
+    "redis",
+    "queue",
+    "dashboard",
+    "admin",
+    "ui",
+    "monitoring",
+    "resilient-queue",
+    "job-queue"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/resilient-queue/resilient-queue-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/resilient-queue/resilient-queue-ui/issues"
+  },
+  "homepage": "https://github.com/resilient-queue/resilient-queue-ui#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "node examples/dev-server.js",
+    "test": "node --test",
+    "test:frontend": "node --test tests/unit/api-client.test.js tests/unit/ui-components.test.js",
+    "test:unit": "node --test tests/unit/*.test.js",
+    "test:integration": "node --test tests/integration/*.test.js",
+    "test:browser": "node --test tests/e2e/*.test.js",
+    "test:e2e": "node --test tests/e2e/*.test.js"
+  },
+  "peerDependencies": {
+    "@mayurbhusare/resilient-queue": "^2.2.0"
+  },
+  "devDependencies": {
+    "@mayurbhusare/resilient-queue": "^2.2.0"
+  }
+}

package/src/adapters/express.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const {
+  createDashboardDispatcher,
+  createErrorResponse,
+  sanitizeErrorMessage,
+  sendJson
+} = require("../dispatcher");
+
+/**
+ * Creates an Express / Connect middleware adapter for the dashboard.
+ *
+ * @param {import("../dispatcher").DashboardAdapterOptions} options
+ * @returns {function(req: object, res: object, next: function): void}
+ */
+function createExpressAdapter(options) {
+  const dispatcher = createDashboardDispatcher(options);
+
+  return function expressAdapter(req, res, next) {
+    dispatcher.dispatch(req, res, next).catch((err) => {
+      if (typeof next === "function") {
+        next(err);
+      } else {
+        sendJson(
+          res,
+          500,
+          createErrorResponse(
+            "INTERNAL_ERROR",
+            sanitizeErrorMessage(err?.message)
+          )
+        );
+      }
+    });
+  };
+}
+
+module.exports = {
+  createExpressAdapter
+};

package/src/adapters/fastify.js

@@ -0,0 +1,192 @@
+"use strict";
+
+const {
+  createDashboardDispatcher,
+  resolveUiAssetPath,
+  sendStaticFile,
+  sanitizeErrorMessage
+} = require("../dispatcher");
+
+/**
+ * Fastify plugin adapter for @mayurbhusare/resilient-queue-ui.
+ *
+ * @param {object} fastify Fastify instance
+ * @param {object} options Plugin options
+ * @param {function} [done] Callback invoked when plugin registration completes
+ */
+function fastifyDashboardPlugin(fastify, options = {}, done) {
+  const dispatcher = createDashboardDispatcher(options);
+
+  const routeOptions = {};
+  if (
+    options &&
+    (typeof options.preHandler === "function" ||
+      Array.isArray(options.preHandler))
+  ) {
+    routeOptions.preHandler = options.preHandler;
+  }
+
+  fastify.get("/api/queues", routeOptions, async (request, reply) => {
+    try {
+      const result = await dispatcher.executeQueuesRoute();
+      reply
+        .header("Cache-Control", "no-store")
+        .header("X-Content-Type-Options", "nosniff")
+        .code(result.status)
+        .send(result.body);
+    } catch (err) {
+      reply
+        .header("Cache-Control", "no-store")
+        .header("X-Content-Type-Options", "nosniff")
+        .code(500)
+        .send({
+          error: {
+            code: "INTERNAL_ERROR",
+            message: sanitizeErrorMessage(err?.message || "Internal server error")
+          }
+        });
+    }
+  });
+
+  fastify.get(
+    "/api/queues/:queueName/metrics",
+    routeOptions,
+    async (request, reply) => {
+      try {
+        const rawQueueName = request?.params?.queueName;
+        const result = await dispatcher.executeMetricsRoute(rawQueueName);
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(result.status)
+          .send(result.body);
+      } catch (err) {
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(500)
+          .send({
+            error: {
+              code: "INTERNAL_ERROR",
+              message: sanitizeErrorMessage(err?.message || "Internal server error")
+            }
+          });
+      }
+    }
+  );
+
+  fastify.get(
+    "/api/queues/:queueName/dlq",
+    routeOptions,
+    async (request, reply) => {
+      try {
+        const rawQueueName = request?.params?.queueName;
+        const query = request?.query || {};
+        const result = await dispatcher.executeDLQRoute(rawQueueName, query);
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(result.status)
+          .send(result.body);
+      } catch (err) {
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(500)
+          .send({
+            error: {
+              code: "INTERNAL_ERROR",
+              message: sanitizeErrorMessage(err?.message || "Internal server error")
+            }
+          });
+      }
+    }
+  );
+
+  fastify.get(
+    "/api/queues/:queueName/jobs/:jobId",
+    routeOptions,
+    async (request, reply) => {
+      try {
+        const rawQueueName = request?.params?.queueName;
+        const rawJobId = request?.params?.jobId;
+        const result = await dispatcher.executeJobRoute(rawQueueName, rawJobId);
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(result.status)
+          .send(result.body);
+      } catch (err) {
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(500)
+          .send({
+            error: {
+              code: "INTERNAL_ERROR",
+              message: sanitizeErrorMessage(err?.message || "Internal server error")
+            }
+          });
+      }
+    }
+  );
+
+  const uiRoutes = [
+    "/",
+    "/index.html",
+    "/styles.css",
+    "/api-client.js",
+    "/app.js",
+    "/views/overview.js",
+    "/views/dlq.js",
+    "/views/job.js",
+    "/ui",
+    "/ui/",
+    "/ui/index.html",
+    "/ui/styles.css",
+    "/ui/api-client.js",
+    "/ui/app.js",
+    "/ui/views/overview.js",
+    "/ui/views/dlq.js",
+    "/ui/views/job.js"
+  ];
+
+  for (const route of uiRoutes) {
+    fastify.get(route, routeOptions, async (request, reply) => {
+      try {
+        const asset = resolveUiAssetPath(route);
+        if (asset) {
+          sendStaticFile(reply, asset.fullPath, asset.contentType);
+        } else {
+          reply
+            .header("Cache-Control", "no-store")
+            .header("X-Content-Type-Options", "nosniff")
+            .code(404)
+            .send({ error: { code: "ROUTE_NOT_FOUND", message: "Route not found" } });
+        }
+      } catch (err) {
+        reply
+          .header("Cache-Control", "no-store")
+          .header("X-Content-Type-Options", "nosniff")
+          .code(500)
+          .send({
+            error: {
+              code: "INTERNAL_ERROR",
+              message: sanitizeErrorMessage(err?.message || "Internal server error")
+            }
+          });
+      }
+    });
+  }
+
+  if (typeof done === "function") {
+    done();
+    return;
+  }
+
+  return Promise.resolve();
+}
+
+module.exports = {
+  fastifyDashboardPlugin
+};