bunqueue-dashboard 0.0.47 → 1.0.1

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)
@@ -58,9 +58,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,8 +129,8 @@ 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
 

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,6 +123,7 @@ export async function routeAgentRequest(
           return sqliteOnly('S3 backup', currentStorageMode);
         }
         return manager.withStoppedMaintenance('restoring a backup', async () => {
+          await closeWorkflowRuntime(runtime);
           return executePreparedBackupRequest(
             prepared,
             restoreConfig,

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;