bunqueue-dashboard 0.0.41 → 0.0.43

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.4 npm client
 contracts; it never patches Bunqueue internals.
 
 ## Features
@@ -108,7 +108,7 @@ contracts; it never patches Bunqueue internals.
 | **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 |
@@ -118,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
@@ -262,8 +262,10 @@ 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:tls` | Queue, Flow and Workflow over verified native TLS, including untrusted-certificate rejection |
+| `bun run test:e2e:upgrade` | Real npm Bunqueue 2.9.2 SQLite schema-35 → 2.9.4 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.2 brokers + three agents sharing disposable PostgreSQL 18.6 |
+| `bun run test:e2e:postgres-fleet` | Three authenticated Bunqueue 2.9.4 brokers + three agents sharing disposable PostgreSQL 18.6 |
 
 ## Docker
 
@@ -310,11 +312,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,
+The E2E stage starts disposable Bunqueue 2.9.4 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, and rate-limit behavior. Run it alone with `bun run test:e2e` (Docker
-is required for the PostgreSQL stage).
+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/flow/routes.ts

@@ -1,3 +1,4 @@
+import { assertFlowOperationAllowed } from '../../shared/flowOperationPolicy';
 import type { ServerConfig } from '../manager';
 import { assertManagedTarget, type ManagedTargetPolicy } from '../managedTarget';
 import type {
@@ -160,6 +161,7 @@ export async function routeFlowRequest(
     const payload = MUTATIONS_WITH_BODY.has(mutation)
       ? await readFlowJsonBody(request)
       : (assertNoFlowBody(request), {});
+    assertFlowOperationAllowed(mutation);
     return success(
       await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
         operations(dependencies).mutate(current, target, mutation, payload)

package/agent/flow/service.ts

@@ -7,7 +7,8 @@ import {
   type JobNode,
 } from 'bunqueue/client';
 import type { ServerConfig } from '../manager';
-import { managedAuthToken } from '../managedTarget';
+import { managedConnection } from '../managedConnection';
+import { assertFlowOperationAllowed, assertFlowOperationState } from '../../shared/flowOperationPolicy';
 import {
   asFlowRecord,
   assertFlowBodySize,
@@ -119,11 +120,15 @@ export async function mutateFlowJob(
   operation: FlowMutationOperation,
   input: unknown
 ): Promise<unknown> {
+  assertFlowOperationAllowed(operation);
   assertFlowBodySize(input);
   const payload = asFlowRecord(input);
   validateMutationPayload(operation, payload);
   const { producer, job } = await loadJob(config, target);
   try {
+    if (['promote', 'changeDelay', 'changePriority'].includes(operation)) {
+      assertFlowOperationState(operation, await job.getState());
+    }
     switch (operation) {
       case 'removeChildDependency': return { removed: await job.removeChildDependency() };
       case 'removeUnprocessedChildren': await job.removeUnprocessedChildren(); break;
@@ -173,7 +178,7 @@ function producerFor(
 }
 
 function connectionFor(config: ServerConfig) {
-  return { host: '127.0.0.1', port: config.tcpPort, token: managedAuthToken(config) };
+  return managedConnection(config);
 }
 
 async function loadJob(

package/agent/managedConnection.ts

@@ -0,0 +1,35 @@
+import { isAbsolute } from 'node:path';
+import { statSync } from 'node:fs';
+import type { ConnectionOptions } from 'bunqueue/client';
+import type { ServerConfig } from './manager';
+import { managedAuthToken } from './managedTarget';
+
+/** Same environment precedence as the managed child; never disables verification. */
+export function managedConnection(config: ServerConfig): ConnectionOptions {
+  const env = (key: string) =>
+    (Object.hasOwn(config.extraEnv, key) ? config.extraEnv[key] : process.env[key])?.trim();
+  const mode = env('BUNQUEUE_AGENT_TCP_TLS');
+  if (mode && mode !== 'true' && mode !== 'false') {
+    throw new Error('BUNQUEUE_AGENT_TCP_TLS must be true or false.');
+  }
+  const caFile = env('BUNQUEUE_AGENT_TCP_CA_FILE');
+  const serverTls = Boolean(env('TLS_CERT_FILE') || env('TLS_KEY_FILE'));
+  if (mode === 'false' && (serverTls || caFile)) {
+    throw new Error('Cannot disable agent TCP TLS when server TLS or a CA is configured.');
+  }
+  if (caFile) {
+    if (!isAbsolute(caFile)) throw new Error('BUNQUEUE_AGENT_TCP_CA_FILE must be absolute.');
+    try {
+      if (!statSync(caFile).isFile()) throw new Error();
+    } catch {
+      throw new Error('BUNQUEUE_AGENT_TCP_CA_FILE must point to a readable CA file.');
+    }
+  }
+  const tls = mode === 'true' || serverTls || Boolean(caFile);
+  return {
+    host: '127.0.0.1',
+    port: config.tcpPort,
+    token: managedAuthToken(config),
+    ...(tls ? { tls: { rejectUnauthorized: true, ...(caFile ? { caFile } : {}) } } : {}),
+  };
+}

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.4 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/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

@@ -1,5 +1,5 @@
 import { Queue, type QueueMetricType, type QueueMetrics } from 'bunqueue/client';
-import { managedAuthToken } from '../managedTarget';
+import { managedConnection } from '../managedConnection';
 import type { ServerConfig } from '../manager';
 import type { QueueGroupSnapshot, QueueLimitSnapshot, QueueOperationsPort } from './types';
 import { QueueOperationsUnavailableError } from './types';
@@ -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,
@@ -174,7 +220,7 @@ export class QueueOperationsRuntime implements QueueOperationsPort {
 }
 
 function connectionFor(config: ServerConfig) {
-  return { host: '127.0.0.1', port: config.tcpPort, token: managedAuthToken(config) };
+  return managedConnection(config);
 }
 
 function defaultClient(config: ServerConfig, queue: string): QueueOperationsClient {

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/workflow/runtime.ts

@@ -7,7 +7,7 @@ import {
   type ExecutionState,
   type Workflow,
 } from 'bunqueue/workflow';
-import { managedAuthToken } from '../managedTarget';
+import { managedConnection } from '../managedConnection';
 import type { ServerConfig } from '../manager';
 import {
   configuredWorkflowModule,
@@ -188,11 +188,7 @@ export class WorkflowRuntime implements WorkflowRuntimePort {
       dataPath: config.dataPath,
       queueName: options.queueName,
       concurrency: options.concurrency,
-      connection: {
-        host: '127.0.0.1',
-        port: config.tcpPort,
-        token: managedAuthToken(config),
-      },
+      connection: managedConnection(config),
     });
     const active: ActiveRuntime = {
       engine,

package/agent/workflow/runtimeConfig.ts

@@ -1,6 +1,6 @@
 import { basename } from 'node:path';
 import { safeErrorMessage } from '../errorMessage';
-import { managedAuthToken } from '../managedTarget';
+import { managedConnection } from '../managedConnection';
 import type { ServerConfig } from '../manager';
 import type { WorkflowRuntimeStatus } from './runtime';
 
@@ -53,7 +53,7 @@ export function workflowRuntimeSignature(
     modified,
     config.dataPath,
     config.tcpPort,
-    managedAuthToken(config),
+    managedConnection(config),
     options.queueName,
     options.concurrency,
   ]);

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';