bunqueue-dashboard 0.0.47 → 1.0.2

package/README.md

@@ -26,7 +26,7 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Documentation](https://img.shields.io/badge/docs-online-db2777)](https://egeominotti.github.io/bunqueue-dashboard/docs/)
 [![Live demo](https://img.shields.io/badge/live%20demo-online-22c55e)](https://egeominotti.github.io/bunqueue-dashboard/)
-![Status: Beta](https://img.shields.io/badge/status-beta-f59e0b)
+![Status: Stable](https://img.shields.io/badge/status-stable-22c55e)
 
 ![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)
 ![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
@@ -36,9 +36,11 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 
 <br />
 
-<img src="docs/public/tour.gif" alt="A guided tour of the bunqueue dashboard, clicking through the overview, queues, jobs, the dead-letter queue, flows, the SQLite inspector, and the AI Copilot" width="900" />
+<a href="https://www.youtube.com/watch?v=1bQRFXGClcc" title="Watch the full bunqueue dashboard tour on YouTube"><img src="docs/public/video-tour.png" alt="Watch the narrated 4K tour of bunqueue dashboard on YouTube" width="900" /></a>
 
-<sub>A quick tour. <a href="https://egeominotti.github.io/bunqueue-dashboard/">Try it live →</a></sub>
+### [▶ Watch the full tour on YouTube](https://www.youtube.com/watch?v=1bQRFXGClcc)
+
+<sub>A narrated 4K walkthrough (7:45, English with subtitles) recorded against a real bunqueue server under live traffic. <a href="https://egeominotti.github.io/bunqueue-dashboard/">Or try the live demo →</a></sub>
 
 <br /><br />
 
@@ -58,9 +60,9 @@ The live demo uses sample data. The docs explain how to connect and operate a re
 
 ---
 
-> ⚠️ **Beta.** bunqueue dashboard is under active development, interfaces and
-> behavior may change between releases. Review it before relying on it for
-> unattended production use.
+> ✅ **Stable (1.x).** The dashboard follows [Semantic Versioning](https://semver.org/):
+> breaking changes to its configuration, routes or agent API only ship in a new
+> major version.
 
 ## 📚 Documentation
 
@@ -129,12 +131,12 @@ contracts; it never patches Bunqueue internals.
 > registration or flow order. Cancel, Discard, Drain, Clean, Obliterate and DLQ Purge also fail
 > closed. Bunqueue 2.9's `Queue.removeDlqJob()` also accepts only queue + job ID, so custom-ID reuse
 > prevents the dashboard from proving that a later deletion still targets the observed generation.
-> DLQ `maxAge`/`maxEntries` are read-only, auto-retry can only be disabled, and Copilot's only
-> mutations are Promote, Pause and Resume.
+> DLQ `maxAge`/`maxEntries` are read-only, and auto-retry can only be disabled. The in-app Copilot
+> is switched off in official builds (`VITE_ENABLE_COPILOT=1` opts a custom build back in).
 
 ## Quick start
 
-**Prerequisites:** [Bun](https://bun.sh) 1.4.2 and a reachable bunqueue server (or let the control
+**Prerequisites:** [Bun](https://bun.sh) 1.4.4 and a reachable bunqueue server (or let the control
 agent start one for you from the **Server** page).
 
 ### Run from npm (no clone)

package/agent/backup/routes.ts

@@ -190,18 +190,26 @@ function assertDatabaseSnapshot(value: unknown, current: DbStats): void {
     throw new Error('A database snapshot is required to authorize restore');
   }
   const expected = value as Record<string, unknown>;
-  const allowed = ['path', 'exists', 'size', 'walSize', 'shmSize', 'totalSize', 'mtimeMs'];
-  const unknown = Object.keys(expected).find((key) => !allowed.includes(key));
+  const allowed = ['path', 'exists', 'size', 'walSize', 'shmSize', 'totalSize', 'mtimeMs'] as const;
+  const unknown = Object.keys(expected).find((key) => !(allowed as readonly string[]).includes(key));
   if (unknown) throw new Error(`Unknown database snapshot option: ${unknown}`);
-  if (
-    expected.path !== current.path ||
-    expected.exists !== current.exists ||
-    expected.size !== current.size ||
-    expected.walSize !== current.walSize ||
-    expected.shmSize !== current.shmSize ||
-    expected.totalSize !== current.totalSize ||
-    expected.mtimeMs !== current.mtimeMs
-  ) {
-    throw new Error('Database changed after restore confirmation; reload status and confirm again');
+  // Compare what reflects the data. The -shm file is SQLite's shared-memory WAL
+  // index: it appears and disappears as connections open and close (the last one
+  // deletes it) without any write, so it, and the total that includes it, would
+  // reject valid confirmations. Writes still move the main file or the WAL.
+  const compared = ['path', 'exists', 'size', 'walSize', 'mtimeMs'] as const;
+  // Name every field that moved so a rejected restore is diagnosable.
+  const changed = compared
+    .filter((field) => expected[field] !== current[field])
+    .map((field) => `${field} ${shown(expected[field])} → ${shown(current[field])}`);
+  if (changed.length > 0) {
+    throw new Error(
+      `Database changed after restore confirmation (${changed.join(', ')}); reload status and confirm again`
+    );
   }
 }
+
+function shown(value: unknown): string {
+  const text = String(value);
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}

package/agent/managedTarget.ts

@@ -72,7 +72,9 @@ function assertLocalTarget(target: string, config: ServerConfig, label: string):
   } catch {
     throw new Error(`${label} must be an absolute local HTTP URL`);
   }
-  const local = ['localhost', '127.0.0.1', '::1'].includes(url.hostname);
+  // URL keeps IPv6 brackets in hostname (`[::1]`), so compare without them.
+  const host = url.hostname.replace(/^\[(.*)\]$/, '$1');
+  const local = ['localhost', '127.0.0.1', '::1'].includes(host);
   const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
   if (!local || port !== config.httpPort || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
     throw new Error(

package/agent/manager/commandLine.ts

@@ -0,0 +1,33 @@
+/**
+ * Split the managed launch command into argv without a shell. Whitespace
+ * separates arguments; a balanced pair of double or single quotes groups an
+ * argument that contains spaces (`"C:\Program Files\bun\bun.exe" run main.ts`).
+ * Backslashes are literal so Windows paths need no escaping. A command with an
+ * unbalanced quote (an apostrophe in a path) keeps the legacy whitespace split,
+ * so a configuration that launched before still launches the same way.
+ */
+export function splitCommandLine(command: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | null = null;
+  let inArgument = false;
+  for (const char of command.trim()) {
+    if (quote) {
+      if (char === quote) quote = null;
+      else current += char;
+    } else if (char === '"' || char === "'") {
+      quote = char;
+      inArgument = true;
+    } else if (/\s/.test(char)) {
+      if (inArgument) args.push(current);
+      current = '';
+      inArgument = false;
+    } else {
+      current += char;
+      inArgument = true;
+    }
+  }
+  if (quote) return command.trim().split(/\s+/);
+  if (inArgument) args.push(current);
+  return args;
+}

package/agent/manager/errors.ts

@@ -0,0 +1,4 @@
+/** The managed child survived SIGKILL: a server-side failure, not a bad request. */
+export class ManagedProcessStuckError extends Error {
+  override name = 'ManagedProcessStuckError';
+}

package/agent/manager/process.ts

@@ -1,5 +1,7 @@
 import { copyConfig, defaultConfig, validateConfigPatch, validateServerConfig } from './config';
 import { ProcessLogs } from './logs';
+import { splitCommandLine } from './commandLine';
+import { ManagedProcessStuckError } from './errors';
 import type { ConfigStore } from './configStore';
 import { databaseStats } from './storage';
 import { removeSqlitePaths, validateManagedStorage } from './storageMode';
@@ -118,7 +120,7 @@ export class ProcessManager {
 
     const launchConfig = validateServerConfig(this.config);
     const storageMode = validateManagedStorage(launchConfig);
-    const [command, ...args] = launchConfig.command.trim().split(/\s+/);
+    const [command, ...args] = splitCommandLine(launchConfig.command);
     this.status = 'starting';
     this.exitCode = null;
     const token = ++this.procToken;
@@ -219,7 +221,7 @@ export class ProcessManager {
       if (!(await exitsWithin(process, this.stopTimeoutMs))) {
         const message = `pid ${process.pid} did not exit after SIGKILL`;
         this.output.push('sys', `${message} — retaining failed-process tracking`);
-        throw new Error(message);
+        throw new ManagedProcessStuckError(message);
       }
     }
     this.output.cancel(token);

package/agent/manager.ts

@@ -1,5 +1,6 @@
 /** Public compatibility entrypoint for managed bunqueue process supervision. */
 export { validateConfigPatch } from './manager/config';
+export { ManagedProcessStuckError } from './manager/errors';
 export { ProcessManager } from './manager/process';
 export {
   managedPostgresNamespace,

package/agent/server/controlRoutes.ts

@@ -123,6 +123,16 @@ export function assertManagedControl(controlTarget: ServerControlTarget): void {
   }
 }
 
+/**
+ * Release the Workflow Engine's read-write SQLite connection before the data
+ * file is replaced. A broker that crashed (or was killed externally) leaves the
+ * engine open; after a restore it would keep writing to the unlinked file.
+ */
+export async function closeWorkflowRuntime(runtime: WorkflowRuntimePort): Promise<void> {
+  const closeResult = await settle(() => runtime.close());
+  if (!closeResult.ok) throw workflowCloseError(closeResult.error);
+}
+
 async function stopWithRuntimeCleanup(
   manager: ProcessManager,
   runtime: WorkflowRuntimePort

package/agent/server/controlStatus.ts

@@ -4,6 +4,7 @@ import {
   managedStorageMode,
   type ProcessManager,
 } from '../manager';
+import { managedConnection } from '../managedConnection';
 import { probeExternalHealth, type ServerControlTarget } from './controlTarget';
 
 export async function statusWithHealth(
@@ -30,12 +31,10 @@ export async function statusWithHealth(
   }
   let healthy = false;
   let version: string | undefined;
+  const effectiveConfig = snapshot.runningConfig ?? snapshot.config;
   if (snapshot.status === 'running') {
-    const port = snapshot.runningConfig?.httpPort ?? snapshot.config.httpPort;
     try {
-      const response = await fetch(`http://127.0.0.1:${port}/health`, {
-        signal: AbortSignal.timeout(1500),
-      });
+      const response = await fetchManagedHealth(effectiveConfig);
       if (response.ok) {
         const body: unknown = await response.json();
         if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
@@ -48,7 +47,6 @@ export async function statusWithHealth(
       // The managed process is not healthy yet.
     }
   }
-  const effectiveConfig = snapshot.runningConfig ?? snapshot.config;
   const storageMode = statusStorageMode(effectiveConfig);
   const database = await statusDatabase(manager, effectiveConfig);
   const current = manager.getStatus();
@@ -85,6 +83,29 @@ export async function statusWithHealth(
   };
 }
 
+/**
+ * Bunqueue serves HTTPS on its HTTP port once server TLS is configured, so the
+ * probe follows the same TLS resolution (and private CA) as the agent's TCP
+ * clients; a plain-HTTP probe would report a healthy TLS server as down forever.
+ */
+async function fetchManagedHealth(
+  config: ReturnType<ProcessManager['getConfig']>
+): Promise<Response> {
+  let tls: ReturnType<typeof managedConnection>['tls'];
+  try {
+    tls = managedConnection(config).tls;
+  } catch {
+    // Invalid TLS settings are reported by the routes that use them.
+    tls = undefined;
+  }
+  const caFile = typeof tls === 'object' ? tls.caFile : undefined;
+  const ca = caFile ? await Bun.file(caFile).text() : undefined;
+  return fetch(`${tls ? 'https' : 'http'}://127.0.0.1:${config.httpPort}/health`, {
+    signal: AbortSignal.timeout(1500),
+    ...(ca ? { tls: { ca } } : {}),
+  });
+}
+
 async function statusDatabase(
   manager: ProcessManager,
   config: ReturnType<ProcessManager['getConfig']>

package/agent/server/errors.ts

@@ -4,6 +4,7 @@ import {
   MissingDbError,
 } from '../db';
 import { DbReadBusyError, DbReadUnavailableError } from '../db/types';
+import { ManagedProcessStuckError } from '../manager';
 import { safeErrorMessage } from '../errorMessage';
 import { QueueOperationsUnavailableError } from '../queue/types';
 import { WorkflowRuntimeUnavailableError } from '../workflow/runtime';
@@ -15,6 +16,7 @@ const CONFLICT_MESSAGES = [
   'Another backup operation is already running',
   'Another maintenance operation is already running',
   'Cannot start the managed Bunqueue server',
+  'Cannot start while the previous managed process',
   'Cannot restart the managed Bunqueue server',
   'BUNQUEUE_WORKFLOW_QUEUE_NAME must',
   'BUNQUEUE_WORKFLOW_CONCURRENCY must',
@@ -26,6 +28,7 @@ const CONFLICT_MESSAGES = [
 export function errorStatus(error: unknown): number {
   try {
     if (error instanceof AgentLifecycleClosedError) return 503;
+    if (error instanceof ManagedProcessStuckError) return 500;
     if (error instanceof MissingDbError) return 404;
     if (error instanceof DbReadBusyError) return 429;
     if (error instanceof DbReadUnavailableError) return 503;

package/agent/server/router.ts

@@ -10,7 +10,7 @@ import { routeQueueOperationsRequest } from '../queue/routes';
 import type { QueueOperationsPort } from '../queue/types';
 import type { WorkflowRuntimePort } from '../workflow/runtime';
 import { routeWorkflowRuntimeRequest } from '../workflow/runtimeRoutes';
-import { assertManagedControl, routeControlRequest } from './controlRoutes';
+import { assertManagedControl, closeWorkflowRuntime, routeControlRequest } from './controlRoutes';
 import type { ServerControlTarget } from './controlTarget';
 import { routeDatabaseRequest } from './databaseRoutes';
 import type { AgentLifecyclePort } from './lifecycle';
@@ -123,11 +123,16 @@ export async function routeAgentRequest(
           return sqliteOnly('S3 backup', currentStorageMode);
         }
         return manager.withStoppedMaintenance('restoring a backup', async () => {
+          // Measure what the operator confirmed before our own cleanup: releasing
+          // the Workflow Engine's connection checkpoints the WAL, which changes the
+          // files without any other writer and would void a valid confirmation.
+          const confirmedDatabase = await manager.dbStats(restoreConfig.dataPath);
+          await closeWorkflowRuntime(runtime);
           return executePreparedBackupRequest(
             prepared,
             restoreConfig,
             current.status === 'running',
-            await manager.dbStats(restoreConfig.dataPath),
+            confirmedDatabase,
             backupRunner,
             undefined,
             managedTargetPolicy

package/agent/shutdown.ts

@@ -2,7 +2,8 @@ import { logger } from './logger';
 import { safeErrorMessage } from './errorMessage';
 import type { AgentFetchHandler } from './server';
 
-const DEFAULT_GRACE_MS = 30_000;
+/** Upper bound for a graceful agent drain; supervisors must wait at least this long. */
+export const AGENT_SHUTDOWN_GRACE_MS = 30_000;
 
 export interface AgentShutdownOptions {
   /** Stop listeners synchronously; returned promises drain in-flight HTTP requests. */
@@ -28,7 +29,7 @@ export function createAgentShutdown(
   options: AgentShutdownOptions = {}
 ): (signal: string) => void {
   const exit = options.exit ?? ((code: number) => process.exit(code));
-  const graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
+  const graceMs = options.graceMs ?? AGENT_SHUTDOWN_GRACE_MS;
   let shuttingDown = false;
   let finished = false;
   let graceTimer: ReturnType<typeof setTimeout> | null = null;