bunqueue-dashboard 0.0.40 → 0.0.42

package/README.md

@@ -90,13 +90,13 @@ The full dashboard running on sample data, no server needed.
 bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and
 error-prone. This dashboard is a production-oriented operator console: it exposes the verified,
 safe subset of the API, fails closed where
-[Bunqueue 2.9.x](https://github.com/egeominotti/bunqueue/releases/tag/v2.9.2) lacks atomic
+[Bunqueue 2.9.x](https://github.com/egeominotti/bunqueue/releases/tag/v2.9.3) lacks atomic
 flow-safety guarantees, and also manages the
 server *process* through a separate guarded agent.
 
 It uses Bunqueue's public HTTP API (`:6790`) for ordinary remote observability and a small local
 **control agent** for process, FlowProducer, Workflow Engine, database, and backup operations. The
-agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.2 npm client
+agent is pinned to the server it manages and uses the exact installable Bunqueue 2.9.3 npm client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -104,10 +104,11 @@ contracts; it never patches Bunqueue internals.
 | Area | Where | What you can do |
 | --- | --- | --- |
 | **Home** | Overview | Live health banner, throughput, queue health, recent activity |
+| **Fleet** | Fleet | Probe and operate multiple Bunqueue APIs + paired agents; verify shared PostgreSQL target/namespace topology |
 | **Server** | Control ▸ Server | **Start / stop / restart** the server process, edit its config, tail process logs |
 | **Enqueue** | Control ▸ Add Job | Add jobs (single or bulk) with every option |
 | **Inspect** | Control ▸ Job Inspector | Look up any job; promote / re-prioritize / delay; view data & result |
-| **Queues** | Control ▸ Queue Control | Pause/resume/promote; desired-state writes plus live SDK limits, deduplication, metrics and journal retention |
+| **Queues** | Control ▸ Queue Control | Pause/resume/promote; desired-state writes plus live SDK limits, group jobs/priorities/pause/policies, deduplication, metrics and journal retention |
 | **Cron** | Control ▸ Cron Manager | Submit acknowledged cron/interval upserts and delete schedules |
 | **Workflow Engine** | Workflow ▸ Overview / Executions / Waiting / Compensation / Archive | Start, recover, signal, inspect, compensate, archive and clean durable executions |
 | **Job Flows** | Workflow ▸ Job Flows | Explore DAGs, run all FlowProducer create modes and operate safe Flow Job methods |
@@ -117,7 +118,7 @@ contracts; it never patches Bunqueue internals.
 | **S3 backup** | Management ▸ S3 Backup | Configure, inspect, list, create and guarded-restore official snapshots |
 | **Browse** | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |
 
-> Job actions are gated by the v2.9.2 flow contract. Every DLQ retry and completed-job requeue is
+> Job actions are gated by the v2.9.3 flow contract. Every DLQ retry and completed-job requeue is
 > unavailable: the DLQ GET + POST sequence has no atomic generation/state/topology precondition and
 > can target a job recreated under the same ID, while `retryCompleted` does not rebuild dependency
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
@@ -192,14 +193,22 @@ flowchart LR
 - **Writes** through the same HTTP API, with every mutation shape-verified against the live server.
 - **Process lifecycle**, the one thing HTTP can't do, is delegated to the local control agent.
 
+For multiple brokers, create one named Dashboard profile and one paired control
+agent per broker. The Fleet page probes all profiles without retargeting the
+active UI, groups brokers that share an exact PostgreSQL target + namespace,
+and drives each node's Start/Stop/Restart controls. Queue state is shared by
+PostgreSQL; lifecycle, process logs/config, in-memory webhooks, and each agent's
+Workflow Engine store remain node-local. See the
+[Fleet guide](https://egeominotti.github.io/bunqueue-dashboard/docs/guide/fleet).
+
 Two HTTP clients coexist on purpose: `src/lib/api.ts` (first-generation view pages) and
 `src/lib/bq.ts` (the complete, shape-verified client used by every `Control ▸ *` page). See
 [`docs/`](docs/README.md) for the full, source-verified reference.
 
 ## Configuration
 
-The `VITE_*` dashboard defaults are build-time values and can **also** be changed at runtime from
-the in-app **Settings** page. The all-in-one server reads the non-`VITE_*` runtime variables below.
+The `VITE_*` dashboard defaults are build-time values and can **also** seed the first named profile
+in **Settings**. Add up to 32 broker/agent profiles at runtime. The all-in-one server reads the non-`VITE_*` runtime variables below.
 Copy [`.env.example`](.env.example) to `.env` to set defaults.
 
 | Variable | Purpose | Default |
@@ -253,6 +262,9 @@ target-pinned Flow, Workflow, Queue and Backup agent operations.
 | `bun run check` | Oxlint + Oxfmt validation (the CI gate) |
 | `bun run check:fix` | Apply safe Oxlint fixes, then format with Oxfmt |
 | `bun test` | Unit + agent-lifecycle tests |
+| `bun run test:e2e:upgrade` | Real npm Bunqueue 2.9.2 SQLite schema-35 → 2.9.3 schema-37 migration and retention semantics |
+| `bun run test:e2e` | Real Flow, Workflow, Queue SDK, and three-broker PostgreSQL runtime tests |
+| `bun run test:e2e:postgres-fleet` | Three authenticated Bunqueue 2.9.3 brokers + three agents sharing disposable PostgreSQL 18.6 |
 
 ## Docker
 
@@ -299,8 +311,12 @@ The canonical gate must be green before a change is considered done; CI runs the
 bun run quality   # architecture, lint/build, size, docs, coverage, real E2E, packed-bin smoke, audit
 ```
 
-The E2E stage starts disposable Bunqueue 2.9.2 processes and exercises the complete FlowProducer,
-Workflow Engine, and Queue SDK operator bridges. Run it alone with `bun run test:e2e`.
+The E2E stage starts disposable Bunqueue 2.9.3 processes and exercises the complete FlowProducer,
+Workflow Engine, and Queue SDK operator bridges. It also starts PostgreSQL 18.6 in Docker with
+three authenticated brokers and paired agents, proving cross-broker enqueue/inspect/leased
+pull+ack, pause/resume, cron, rate limits, group admission, group priority and group pause/resume
+on PostgreSQL schema 20. Run it alone with `bun run test:e2e` (Docker is required for the
+PostgreSQL stage).
 
 The blocking browser job builds the production bundle under `/e2e/dashboard`, starts an
 authenticated disposable Bunqueue server, and drives the UI with Playwright on Chromium, Firefox,

package/agent/backup/resultValidation.ts

@@ -81,5 +81,5 @@ function validIsoDate(value: string): boolean {
 }
 
 function invalid(label: string): never {
-  throw new Error(`Bunqueue ${label} has an invalid 2.9.2 contract`);
+  throw new Error(`Bunqueue ${label} has an invalid 2.9.3 contract`);
 }

package/agent/manager/config.ts

@@ -10,7 +10,7 @@ const CONFIG_KEYS = new Set<keyof ServerConfig>([
 
 export function defaultConfig(): ServerConfig {
   return {
-    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.2 start',
+    command: process.env.BUNQUEUE_START_CMD || 'bunx bunqueue@2.9.3 start',
     httpPort: Number(process.env.HTTP_PORT) || 6790,
     tcpPort: Number(process.env.TCP_PORT) || 6789,
     dataPath: process.env.BUNQUEUE_DATA_PATH || './data/bunq.db',

package/agent/manager/storageMode.ts

@@ -23,6 +23,25 @@ export function managedPostgresNamespace(config: ServerConfig): string {
   );
 }
 
+/** Credential-free PostgreSQL cluster label safe to expose to authenticated operators. */
+export function managedPostgresTarget(config: ServerConfig): string | undefined {
+  const configured = managedPostgresUrl(config);
+  if (!configured) return undefined;
+  try {
+    const parsed = new URL(configured);
+    if (
+      (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') ||
+      !parsed.hostname
+    ) {
+      return undefined;
+    }
+    const database = decodeURIComponent(parsed.pathname.replace(/^\/+/, '')) || 'postgres';
+    return `${parsed.hostname}:${parsed.port || '5432'}/${database}`;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Fail before spawning when Bunqueue would reject an incomplete PostgreSQL config. */
 export function validateManagedStorage(config: ServerConfig): ManagedStorageMode {
   const mode = managedStorageMode(config);

package/agent/manager.ts

@@ -1,7 +1,11 @@
 /** Public compatibility entrypoint for managed bunqueue process supervision. */
 export { validateConfigPatch } from './manager/config';
 export { ProcessManager } from './manager/process';
-export { managedPostgresNamespace, managedStorageMode } from './manager/storageMode';
+export {
+  managedPostgresNamespace,
+  managedPostgresTarget,
+  managedStorageMode,
+} from './manager/storageMode';
 export type {
   DbStats,
   LogLine,

package/agent/queue/routes.ts

@@ -12,6 +12,7 @@ import {
   eventRetention,
   exactJsonBody,
   exactQuery,
+  groupJobsRange,
   metricsRange,
   optionalMaxCount,
   optionalMaxJobs,
@@ -23,7 +24,7 @@ import {
 
 const READ_ROUTE = /^\/queue-operations\/([^/]+)\/(limits|groups|deduplication|metrics)$/;
 const MUTATION_ROUTE =
-  /^\/queue-operations\/([^/]+)\/(groups\/(?:rate-limit|concurrency)(?:\/remove)?|deduplication\/remove|events\/trim)$/;
+  /^\/queue-operations\/([^/]+)\/(groups\/(?:(?:rate-limit|concurrency)(?:\/remove)?|pause|resume)|deduplication\/remove|events\/trim)$/;
 
 export async function routeQueueOperationsRequest(
   request: Request,
@@ -58,15 +59,26 @@ export async function routeQueueOperationsRequest(
       const query = pinnedQuery(
         request,
         config,
-        ['target', 'groupId', 'maxJobs', 'maxCount'],
+        ['target', 'groupId', 'maxJobs', 'maxCount', 'start', 'end'],
         targetPolicy
       );
       const groupId = requiredGroupId(query.get('groupId'));
       const maxJobs = optionalMaxJobs(query);
       const maxCount = optionalMaxCount(query);
+      const range = groupJobsRange(query);
       assertRunning(running);
       return admitted(query, config, running, admission, targetPolicy, async ({ config: current }) =>
-        ok({ group: await runtime.group(current, queue, groupId, maxJobs, maxCount) })
+        ok({
+          group: await runtime.group(
+            current,
+            queue,
+            groupId,
+            maxJobs,
+            maxCount,
+            range.start,
+            range.end
+          ),
+        })
       );
     }
     const query = pinnedQuery(request, config, ['target', 'type', 'start', 'end'], targetPolicy);
@@ -93,6 +105,24 @@ export async function routeQueueOperationsRequest(
       );
     }
     if (mutation[2].startsWith('groups/')) {
+      if (mutation[2] === 'groups/pause' || mutation[2] === 'groups/resume') {
+        const body = await exactJsonBody(request, ['groupId']);
+        const groupId = requiredGroupId(body.groupId);
+        return admitted(
+          query,
+          config,
+          running,
+          admission,
+          targetPolicy,
+          async ({ config: current }) =>
+            ok({
+              changed:
+                mutation[2] === 'groups/pause'
+                  ? await runtime.pauseGroup(current, queue, groupId)
+                  : await runtime.resumeGroup(current, queue, groupId),
+            })
+        );
+      }
       const remove = mutation[2].endsWith('/remove');
       const rateLimit = mutation[2].includes('/rate-limit');
       const allowed = remove

package/agent/queue/runtime.ts

@@ -21,6 +21,11 @@ export type QueueOperationsClient = Pick<
   | 'setGroupConcurrency'
   | 'getGroupConcurrency'
   | 'removeGroupConcurrency'
+  | 'pauseGroup'
+  | 'resumeGroup'
+  | 'isGroupPaused'
+  | 'getGroupJobs'
+  | 'getCountsPerPriorityForGroup'
   | 'getDeduplicationJobId'
   | 'removeDeduplicationKey'
   | 'removeDlqJob'
@@ -57,21 +62,62 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
     queue: string,
     groupId: string,
     maxJobs?: number,
-    maxCount?: number
+    maxCount?: number,
+    start?: number,
+    end?: number
   ): Promise<QueueGroupSnapshot> {
     return this.withQueue(config, queue, async (client) => {
-      const [jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency] = await Promise.all([
+      const [
+        jobs,
+        active,
+        totalGrouped,
+        rateLimit,
+        rateLimitTtl,
+        concurrency,
+        paused,
+        groupJobs,
+        priorityCounts,
+      ] = await Promise.all([
         client.getGroupJobsCount(groupId),
         client.getGroupActiveCount(groupId),
         client.getGroupsJobsCount(maxCount),
         client.getGroupRateLimit(groupId),
         client.getGroupRateLimitTtl(groupId, maxJobs),
         client.getGroupConcurrency(groupId),
+        client.isGroupPaused(groupId),
+        client.getGroupJobs(groupId, start, end),
+        client.getCountsPerPriorityForGroup(groupId),
       ]);
-      return { jobs, active, totalGrouped, rateLimit, rateLimitTtl, concurrency };
+      return {
+        jobs,
+        active,
+        totalGrouped,
+        rateLimit,
+        rateLimitTtl,
+        concurrency,
+        paused,
+        entries: groupJobs.map((job) => ({
+          id: job.id,
+          name: job.name,
+          priority: job.priority,
+          delay: job.delay,
+          timestamp: job.timestamp,
+        })),
+        priorityCounts: Object.fromEntries(
+          Object.entries(priorityCounts).map(([priority, count]) => [String(priority), count])
+        ),
+      };
     });
   }
 
+  pauseGroup(config: ServerConfig, queue: string, groupId: string): Promise<boolean> {
+    return this.withQueue(config, queue, (client) => client.pauseGroup(groupId));
+  }
+
+  resumeGroup(config: ServerConfig, queue: string, groupId: string): Promise<boolean> {
+    return this.withQueue(config, queue, (client) => client.resumeGroup(groupId));
+  }
+
   setGroupRateLimit(
     config: ServerConfig,
     queue: string,

package/agent/queue/types.ts

@@ -12,11 +12,22 @@ export interface QueueGroupSnapshot {
   jobs: number;
   active: number;
   totalGrouped: number;
+  paused: boolean;
+  entries: QueueGroupJobSummary[];
+  priorityCounts: Record<string, number>;
   rateLimit: { max: number; duration: number } | null;
   rateLimitTtl: number;
   concurrency: number | null;
 }
 
+export interface QueueGroupJobSummary {
+  id: string;
+  name: string;
+  priority: number;
+  delay: number;
+  timestamp: number;
+}
+
 export interface QueueOperationsPort {
   limits(config: ServerConfig, queue: string, maxJobs?: number): Promise<QueueLimitSnapshot>;
   group(
@@ -24,8 +35,12 @@ export interface QueueOperationsPort {
     queue: string,
     groupId: string,
     maxJobs?: number,
-    maxCount?: number
+    maxCount?: number,
+    start?: number,
+    end?: number
   ): Promise<QueueGroupSnapshot>;
+  pauseGroup(config: ServerConfig, queue: string, groupId: string): Promise<boolean>;
+  resumeGroup(config: ServerConfig, queue: string, groupId: string): Promise<boolean>;
   setGroupRateLimit(
     config: ServerConfig,
     queue: string,

package/agent/queue/validation.ts

@@ -45,6 +45,14 @@ export function optionalMaxCount(query: URLSearchParams): number | undefined {
   return raw === null ? undefined : boundedInteger(raw, 'maxCount', 1, 1_000_000);
 }
 
+export function groupJobsRange(query: URLSearchParams): { start: number; end: number } {
+  const start = optionalInteger(query.get('start'), 'start', 0, 1_000_000, 0);
+  const end = optionalInteger(query.get('end'), 'end', 0, 1_000_000, start + 24);
+  if (end < start) throw new Error('Group jobs end must be at least start');
+  if (end - start >= 100) throw new Error('Group jobs page must contain at most 100 jobs');
+  return { start, end };
+}
+
 export function requiredGroupId(value: unknown): string {
   if (typeof value !== 'string' || !value || value.length > 256 || value.includes('\0')) {
     throw new Error('groupId must be a non-empty string of at most 256 characters without NUL');

package/agent/server/controlStatus.ts

@@ -1,5 +1,6 @@
 import {
   managedPostgresNamespace,
+  managedPostgresTarget,
   managedStorageMode,
   type ProcessManager,
 } from '../manager';
@@ -64,6 +65,8 @@ export async function statusWithHealth(
       storageMode: currentStorageMode,
       postgresNamespace:
         currentStorageMode === 'postgres' ? managedPostgresNamespace(currentConfig) : undefined,
+      postgresTarget:
+        currentStorageMode === 'postgres' ? managedPostgresTarget(currentConfig) : undefined,
       db: await statusDatabase(manager, currentConfig),
     };
   }
@@ -76,6 +79,8 @@ export async function statusWithHealth(
     storageMode,
     postgresNamespace:
       storageMode === 'postgres' ? managedPostgresNamespace(effectiveConfig) : undefined,
+    postgresTarget:
+      storageMode === 'postgres' ? managedPostgresTarget(effectiveConfig) : undefined,
     db: database,
   };
 }

package/agent/workflows.ts

@@ -1,5 +1,5 @@
 /**
- * Read-only facade for Bunqueue 2.9.2 Workflow Engine observability.
+ * Read-only facade for Bunqueue 2.9.3 Workflow Engine observability.
  * Persistence, decoding and validation live behind this stable public module.
  */
 export { workflowExecution } from './workflow/detail';