bunqueue-dashboard 0.0.46 → 1.0.1

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/configStore.ts

@@ -0,0 +1,65 @@
+import { closeSync, constants, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { copyConfig, validateServerConfig } from './config';
+import type { ServerConfig } from './types';
+
+export interface ConfigStore {
+  load(fallback: ServerConfig): ServerConfig;
+  save(config: ServerConfig): void;
+}
+
+const MAX_CONFIG_BYTES = 1024 * 1024;
+
+/** Private atomic snapshots. Errors never include configuration secrets. */
+export class FileConfigStore implements ConfigStore {
+  constructor(readonly path: string) {}
+
+  load(fallback: ServerConfig): ServerConfig {
+    let descriptor: number;
+    try {
+      descriptor = openSync(this.path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return copyConfig(fallback);
+      throw new Error('Cannot read saved agent configuration');
+    }
+    try {
+      if (fstatSync(descriptor).size > MAX_CONFIG_BYTES) throw new Error('oversize');
+      const raw = readFileSync(descriptor);
+      if (raw.byteLength > MAX_CONFIG_BYTES) throw new Error('oversize');
+      const saved = JSON.parse(raw.toString()) as { version?: unknown; config?: unknown };
+      if (saved?.version !== 1) throw new Error('unsupported format');
+      return copyConfig(validateServerConfig(saved.config));
+    } catch {
+      throw new Error('Saved agent configuration is invalid; repair or remove AGENT_CONFIG_PATH before restarting');
+    } finally {
+      closeSync(descriptor);
+    }
+  }
+
+  save(config: ServerConfig): void {
+    const content = JSON.stringify({ version: 1, config: validateServerConfig(config) }) + '\n';
+    if (Buffer.byteLength(content) > MAX_CONFIG_BYTES) throw new Error('Agent configuration exceeds 1 MiB');
+    const directory = dirname(this.path);
+    const temporary = `${this.path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    let descriptor: number | undefined;
+    try {
+      mkdirSync(directory, { recursive: true, mode: 0o700 });
+      descriptor = openSync(temporary, 'wx', 0o600);
+      writeFileSync(descriptor, content);
+      fsyncSync(descriptor);
+      closeSync(descriptor);
+      descriptor = undefined;
+      renameSync(temporary, this.path);
+    } catch {
+      throw new Error('Cannot persist agent configuration; the change was not applied');
+    } finally {
+      if (descriptor !== undefined) closeSync(descriptor);
+      rmSync(temporary, { force: true });
+    }
+  }
+}
+
+/** Paths resolve against the launch directory, just like the database path. Use one path per agent. */
+export function agentConfigStore(env: NodeJS.ProcessEnv = process.env): FileConfigStore {
+  return new FileConfigStore(resolve(env.AGENT_CONFIG_PATH || '.bunqueue-dashboard/config.json'));
+}

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,8 @@
 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';
 import type {
@@ -40,7 +43,12 @@ export class ProcessManager {
   private maintenance: string | null = null;
   private output = new ProcessLogs();
 
-  constructor(private readonly stopTimeoutMs = STOP_TIMEOUT_MS) {}
+  constructor(
+    private readonly stopTimeoutMs = STOP_TIMEOUT_MS,
+    private readonly configStore?: ConfigStore
+  ) {
+    this.config = configStore?.load(this.config) ?? this.config;
+  }
 
   getConfig(): ServerConfig {
     return copyConfig(this.config);
@@ -63,6 +71,7 @@ export class ProcessManager {
       extraEnv: valid.extraEnv ?? this.config.extraEnv,
     });
     if (!sameConfig(this.config, next)) {
+      this.configStore?.save(next);
       this.config = next;
       this.configRevision = nextConfigRevision(this.configRevision);
     }
@@ -111,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;
@@ -212,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/databaseRoutes.ts

@@ -1,10 +1,6 @@
+import { readWithTimeout } from '../db/queryTimeout';
 import {
   type DbFilter,
-  dbCell,
-  dbInfo,
-  dbRows,
-  dbSchema,
-  dbTables,
   exportWithTimeout,
   queryWithTimeout,
 } from '../db';
@@ -105,15 +101,15 @@ export async function routeDatabaseRequest(
   admission?: ManagedDatabaseAdmission
 ): Promise<RouteResponse | Response | null> {
   if (pathname === '/db/info' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...dbInfo(path) },
+      body: { ok: true, ...(await readWithTimeout('dbInfo', [path], request.signal)) },
     }));
   }
   if (pathname === '/db/tables' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, tables: dbTables(path) },
+      body: { ok: true, tables: await readWithTimeout('dbTables', [path], request.signal) },
     }));
   }
   if (pathname.startsWith('/db/tables/') && method === 'GET') {
@@ -126,20 +122,20 @@ export async function routeDatabaseRequest(
       );
     }
     if (segments.length === 2 && subresource === 'schema') {
-      return withDatabase(dataPath, admission, (path) => ({
+      return withDatabase(dataPath, admission, async (path) => ({
         status: 200,
-        body: { ok: true, ...dbSchema(path, table) },
+        body: { ok: true, ...(await readWithTimeout('dbSchema', [path, table], request.signal)) },
       }));
     }
     if (segments.length === 2 && subresource === 'cell') {
       const query = new URL(request.url).searchParams;
       const rowid = query.get('rowid');
       if (rowid === null) throw new Error('rowid is required');
-      return withDatabase(dataPath, admission, (path) => ({
+      return withDatabase(dataPath, admission, async (path) => ({
         status: 200,
         body: {
           ok: true,
-          ...dbCell(path, table, rowid, query.get('column') ?? ''),
+          ...(await readWithTimeout('dbCell', [path, table, rowid, query.get('column') ?? ''], request.signal)),
         },
       }));
     }
@@ -147,11 +143,11 @@ export async function routeDatabaseRequest(
       return { status: 404, body: { ok: false, error: 'Not found' } };
     }
     const query = new URL(request.url).searchParams;
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
       body: {
         ok: true,
-        ...dbRows(
+        ...(await readWithTimeout('dbRows', [
           path,
           table,
           Number(query.get('limit')) || 50,
@@ -159,7 +155,7 @@ export async function routeDatabaseRequest(
           query.get('orderBy') || undefined,
           query.get('dir') === 'desc' ? 'desc' : 'asc',
           browseFilter(query)
-        ),
+        ], request.signal)),
       },
     }));
   }
@@ -171,7 +167,7 @@ export async function routeDatabaseRequest(
     })) as { sql?: string };
     return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...(await queryWithTimeout(path, sql ?? '')) },
+      body: { ok: true, ...(await queryWithTimeout(path, sql ?? '', request.signal)) },
     }));
   }
   return null;

package/agent/server/errors.ts

@@ -3,6 +3,8 @@ import {
   DbExportUnavailableError,
   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';
@@ -14,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',
@@ -25,7 +28,10 @@ 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;
     if (error instanceof DbExportBusyError) return 429;
     if (error instanceof DbExportUnavailableError) return 503;
     if (error instanceof QueueOperationsUnavailableError) {

package/agent/server/handler.ts

@@ -1,3 +1,4 @@
+import { terminateDatabaseProcesses } from '../db/processWorker';
 import { BunqueueBackupRunner, type BackupRunnerPort } from '../backup/runner';
 import type { ProcessManager } from '../manager';
 import { QueueOperationsRuntime } from '../queue/runtime';
@@ -110,7 +111,7 @@ export function createFetchHandler(
     shuttingDown ??= closeThenShutdown(beginShutdown, manager);
     return shuttingDown;
   };
-  const forceShutdown = () => manager.forceShutdown();
+  const forceShutdown = () => { terminateDatabaseProcesses(); manager.forceShutdown(); };
   return Object.assign(handle, { close, beginShutdown, shutdown, forceShutdown });
 }
 

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/server/workflowReadRoutes.ts

@@ -1,9 +1,7 @@
+import { readWithTimeout } from '../db/queryTimeout';
 import {
   type WorkflowStateFilter,
   type WorkflowStoreKind,
-  workflowExecution,
-  workflowExecutions,
-  workflowStats,
   WORKFLOW_STATES,
 } from '../workflows';
 import type { RouteResponse } from './types';
@@ -32,9 +30,9 @@ export async function routeWorkflowReadRequest(
   admission?: ManagedDatabaseAdmission
 ): Promise<RouteResponse | null> {
   if (pathname === '/workflows/stats' && method === 'GET') {
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...workflowStats(path) },
+      body: { ok: true, ...(await readWithTimeout('workflowStats', [path], request.signal)) },
     }));
   }
   if (pathname === '/workflows' && method === 'GET') {
@@ -52,17 +50,17 @@ export async function routeWorkflowReadRequest(
     ) {
       throw new Error('Unknown workflow execution state');
     }
-    return withDatabase(dataPath, admission, (path) => ({
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
       body: {
         ok: true,
-        ...workflowExecutions(path, {
+        ...(await readWithTimeout('workflowExecutions', [path, {
           kind: workflowKind(query),
           workflowName: query.get('workflowName') || undefined,
           state: state as WorkflowStateFilter | undefined,
           limit: integer(query, 'limit', 50),
           offset: integer(query, 'offset', 0),
-        }),
+        }], request.signal)),
       },
     }));
   }
@@ -78,8 +76,8 @@ export async function routeWorkflowReadRequest(
       throw new Error(`Duplicate workflow detail option: ${key}`);
     }
   }
-  return withDatabase(dataPath, admission, (path) => {
-    const execution = workflowExecution(path, decodeURIComponent(rawId), workflowKind(query));
+  return withDatabase(dataPath, admission, async (path) => {
+    const execution = await readWithTimeout('workflowExecution', [path, decodeURIComponent(rawId), workflowKind(query)], request.signal);
     return execution
       ? { status: 200, body: { ok: true, execution } }
       : { status: 404, body: { ok: false, error: 'Workflow execution not found' } };
@@ -89,7 +87,7 @@ export async function routeWorkflowReadRequest(
 function withDatabase<T>(
   dataPath: string,
   admission: ManagedDatabaseAdmission | undefined,
-  operation: (path: string) => T
+  operation: (path: string) => T | Promise<T>
 ): Promise<T> {
   return admission
     ? admission((snapshot) => operation(snapshot.dataPath))

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;

package/agent/workflow/sqlite.ts

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { Database } from 'bun:sqlite';
-import { MissingDbError } from '../db';
+import { MissingDbError } from '../db/types';
 import type { WorkflowStoreKind } from './types';
 
 export interface WorkflowSchema {