bunqueue-dashboard 0.0.38 → 0.0.40

package/agent/server/controlRoutes.ts

@@ -7,54 +7,14 @@ import {
 import { readLimitedJsonBody } from './jsonBody';
 import {
   MANAGED_CONTROL_TARGET,
-  probeExternalHealth,
   type ServerControlTarget,
 } from './controlTarget';
+import { statusWithHealth } from './controlStatus';
 import type { AgentLifecyclePort } from './lifecycle';
 import type { RouteResponse } from './types';
 
 const MAX_CONFIG_BODY_BYTES = 64 * 1024;
 
-async function statusWithHealth(manager: ProcessManager, controlTarget: ServerControlTarget) {
-  const snapshot = manager.getStatus();
-  if (controlTarget.mode === 'external') {
-    const health = await probeExternalHealth(controlTarget);
-    return {
-      ...snapshot,
-      managementMode: 'external' as const,
-      healthy: health.healthy,
-      version: health.version,
-      reachable: health.reachable,
-      externalUrl: controlTarget.url,
-      healthStatus: health.statusCode,
-      healthError: health.error,
-      db: null,
-    };
-  }
-  let healthy = false;
-  let version: string | undefined;
-  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),
-      });
-      if (response.ok) {
-        const body: unknown = await response.json();
-        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
-          const health = body as Record<string, unknown>;
-          healthy = health.ok === true;
-          if (typeof health.version === 'string') version = health.version;
-        }
-      }
-    } catch {
-      // The managed process is not healthy yet.
-    }
-  }
-  const database = await manager.dbStats().catch(() => null);
-  return { ...snapshot, managementMode: 'managed' as const, healthy, version, db: database };
-}
-
 export async function routeControlRequest(
   request: Request,
   pathname: string,
@@ -65,7 +25,10 @@ export async function routeControlRequest(
   controlTarget: ServerControlTarget = MANAGED_CONTROL_TARGET
 ): Promise<RouteResponse | null> {
   if (pathname === '/control/status') {
-    return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+    return coordinatedLease(lifecycle, async () => ({
+      status: 200,
+      body: await statusWithHealth(manager, controlTarget),
+    }));
   }
   if (pathname === '/control/logs') {
     return { status: 200, body: { lines: manager.getLogs() } };
@@ -96,22 +59,62 @@ export async function routeControlRequest(
     });
   }
   if (pathname === '/control/config' && method === 'GET') {
-    return { status: 200, body: manager.getConfig() };
+    return { status: 200, body: configSnapshot(manager) };
   }
   if (pathname === '/control/config' && method === 'PUT') {
     assertManagedControl(controlTarget);
-    const patch = validateConfigPatch(
+    const update = configUpdate(
       await readLimitedJsonBody(request, {
         scope: 'Agent configuration',
         maxBytes: MAX_CONFIG_BODY_BYTES,
         limitLabel: '64 KiB',
       })
     );
-    return { status: 200, body: manager.setConfig(patch) };
+    return coordinated(lifecycle, async () => {
+      manager.setConfig(update.patch, update.expectedRevision);
+      return { status: 200, body: configSnapshot(manager) };
+    });
   }
   return null;
 }
 
+function configSnapshot(manager: ProcessManager) {
+  return { ...manager.getConfig(), configRevision: manager.getConfigRevision?.() ?? 0 };
+}
+
+function configUpdate(value: unknown): {
+  patch: ReturnType<typeof validateConfigPatch>;
+  expectedRevision?: number;
+} {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return { patch: validateConfigPatch(value) };
+  }
+  const input = { ...(value as Record<string, unknown>) };
+  const hasExpectedRevision = Object.hasOwn(input, 'expectedRevision');
+  const hasConfigRevision = Object.hasOwn(input, 'configRevision');
+  const expected = hasExpectedRevision
+    ? input.expectedRevision
+    : hasConfigRevision
+      ? input.configRevision
+      : undefined;
+  if (
+    hasExpectedRevision &&
+    hasConfigRevision &&
+    input.expectedRevision !== input.configRevision
+  ) {
+    throw new Error('expectedRevision and configRevision must match');
+  }
+  delete input.expectedRevision;
+  delete input.configRevision;
+  if (expected !== undefined && (!Number.isSafeInteger(expected) || (expected as number) < 0)) {
+    throw new Error('expectedRevision must be a non-negative safe integer');
+  }
+  return {
+    patch: validateConfigPatch(input),
+    ...(expected === undefined ? {} : { expectedRevision: expected as number }),
+  };
+}
+
 export function assertManagedControl(controlTarget: ServerControlTarget): void {
   if (controlTarget.mode === 'external') {
     throw new Error(
@@ -173,6 +176,13 @@ function coordinated<T>(
   return lifecycle ? lifecycle.run(operation) : operation();
 }
 
+function coordinatedLease<T>(
+  lifecycle: AgentLifecyclePort | undefined,
+  operation: () => Promise<T>
+): Promise<T> {
+  return lifecycle ? lifecycle.lease(operation) : operation();
+}
+
 type SettledOperation = { ok: true } | { ok: false; error: unknown };
 
 async function settle(operation: () => Promise<unknown>): Promise<SettledOperation> {

package/agent/server/controlStatus.ts

@@ -0,0 +1,115 @@
+import {
+  managedPostgresNamespace,
+  managedStorageMode,
+  type ProcessManager,
+} from '../manager';
+import { probeExternalHealth, type ServerControlTarget } from './controlTarget';
+
+export async function statusWithHealth(
+  manager: ProcessManager,
+  controlTarget: ServerControlTarget,
+  retryOnProcessChange = true
+) {
+  const snapshot = manager.getStatus();
+  const configRevision = snapshot.configRevision ?? manager.getConfigRevision?.() ?? 0;
+  if (controlTarget.mode === 'external') {
+    const health = await probeExternalHealth(controlTarget);
+    return {
+      ...snapshot,
+      configRevision,
+      managementMode: 'external' as const,
+      healthy: health.healthy,
+      version: health.version,
+      reachable: health.reachable,
+      externalUrl: controlTarget.url,
+      healthStatus: health.statusCode,
+      healthError: health.error,
+      db: null,
+    };
+  }
+  let healthy = false;
+  let version: string | undefined;
+  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),
+      });
+      if (response.ok) {
+        const body: unknown = await response.json();
+        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+          const health = body as Record<string, unknown>;
+          healthy = health.ok === true;
+          if (typeof health.version === 'string') version = health.version;
+        }
+      }
+    } catch {
+      // 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();
+  if (!sameProcessSnapshot(snapshot, current)) {
+    if (retryOnProcessChange) return statusWithHealth(manager, controlTarget, false);
+    const currentConfig = current.runningConfig ?? current.config;
+    const currentStorageMode = statusStorageMode(currentConfig);
+    return {
+      ...current,
+      configRevision: current.configRevision ?? manager.getConfigRevision?.() ?? 0,
+      managementMode: 'managed' as const,
+      healthy: false,
+      version: undefined,
+      storageMode: currentStorageMode,
+      postgresNamespace:
+        currentStorageMode === 'postgres' ? managedPostgresNamespace(currentConfig) : undefined,
+      db: await statusDatabase(manager, currentConfig),
+    };
+  }
+  return {
+    ...snapshot,
+    configRevision,
+    managementMode: 'managed' as const,
+    healthy,
+    version,
+    storageMode,
+    postgresNamespace:
+      storageMode === 'postgres' ? managedPostgresNamespace(effectiveConfig) : undefined,
+    db: database,
+  };
+}
+
+async function statusDatabase(
+  manager: ProcessManager,
+  config: ReturnType<ProcessManager['getConfig']>
+) {
+  try {
+    return managedStorageMode(config) === 'sqlite' ? await manager.dbStats(config.dataPath) : null;
+  } catch {
+    // Status must remain reachable so an invalid desired storage driver can be corrected.
+    return null;
+  }
+}
+
+function statusStorageMode(
+  config: ReturnType<ProcessManager['getConfig']>
+): ReturnType<typeof managedStorageMode> | undefined {
+  try {
+    return managedStorageMode(config);
+  } catch {
+    return undefined;
+  }
+}
+
+function sameProcessSnapshot(
+  initial: ReturnType<ProcessManager['getStatus']>,
+  current: ReturnType<ProcessManager['getStatus']>
+): boolean {
+  return (
+    initial.status === current.status &&
+    initial.generation === current.generation &&
+    initial.pid === current.pid &&
+    initial.configRevision === current.configRevision
+  );
+}

package/agent/server/databaseRoutes.ts

@@ -10,6 +10,7 @@ import {
 } from '../db';
 import { corsHeaders } from './policy';
 import { readLimitedJsonBody } from './jsonBody';
+import type { ManagedDatabaseAdmission } from './managedRuntime';
 import type { RouteResponse } from './types';
 
 const MAX_QUERY_BODY_BYTES = 64 * 1024;
@@ -100,46 +101,58 @@ export async function routeDatabaseRequest(
   method: string,
   dataPath: string,
   origin: string | null,
-  allowedOrigins: string[]
+  allowedOrigins: string[],
+  admission?: ManagedDatabaseAdmission
 ): Promise<RouteResponse | Response | null> {
   if (pathname === '/db/info' && method === 'GET') {
-    return { status: 200, body: { ok: true, ...dbInfo(dataPath) } };
+    return withDatabase(dataPath, admission, (path) => ({
+      status: 200,
+      body: { ok: true, ...dbInfo(path) },
+    }));
   }
   if (pathname === '/db/tables' && method === 'GET') {
-    return { status: 200, body: { ok: true, tables: dbTables(dataPath) } };
+    return withDatabase(dataPath, admission, (path) => ({
+      status: 200,
+      body: { ok: true, tables: dbTables(path) },
+    }));
   }
   if (pathname.startsWith('/db/tables/') && method === 'GET') {
     const segments = pathname.slice('/db/tables/'.length).split('/');
     const table = decodeURIComponent(segments[0] ?? '');
     const subresource = segments[1];
     if (segments.length === 2 && subresource === 'export') {
-      return exportTable(request, table, dataPath, origin, allowedOrigins);
+      return withDatabase(dataPath, admission, (path) =>
+        exportTable(request, table, path, origin, allowedOrigins)
+      );
     }
     if (segments.length === 2 && subresource === 'schema') {
-      return { status: 200, body: { ok: true, ...dbSchema(dataPath, table) } };
+      return withDatabase(dataPath, admission, (path) => ({
+        status: 200,
+        body: { ok: true, ...dbSchema(path, table) },
+      }));
     }
     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 {
+      return withDatabase(dataPath, admission, (path) => ({
         status: 200,
         body: {
           ok: true,
-          ...dbCell(dataPath, table, rowid, query.get('column') ?? ''),
+          ...dbCell(path, table, rowid, query.get('column') ?? ''),
         },
-      };
+      }));
     }
     if (segments.length !== 1) {
       return { status: 404, body: { ok: false, error: 'Not found' } };
     }
     const query = new URL(request.url).searchParams;
-    return {
+    return withDatabase(dataPath, admission, (path) => ({
       status: 200,
       body: {
         ok: true,
         ...dbRows(
-          dataPath,
+          path,
           table,
           Number(query.get('limit')) || 50,
           Number(query.get('offset')) || 0,
@@ -148,7 +161,7 @@ export async function routeDatabaseRequest(
           browseFilter(query)
         ),
       },
-    };
+    }));
   }
   if (pathname === '/db/query' && method === 'POST') {
     const { sql } = (await readLimitedJsonBody(request, {
@@ -156,10 +169,30 @@ export async function routeDatabaseRequest(
       maxBytes: MAX_QUERY_BODY_BYTES,
       limitLabel: '64 KiB',
     })) as { sql?: string };
-    return {
+    return withDatabase(dataPath, admission, async (path) => ({
       status: 200,
-      body: { ok: true, ...(await queryWithTimeout(dataPath, sql ?? '')) },
-    };
+      body: { ok: true, ...(await queryWithTimeout(path, sql ?? '')) },
+    }));
   }
   return null;
 }
+
+function withDatabase<T>(
+  dataPath: string,
+  admission: ManagedDatabaseAdmission | undefined,
+  operation: (path: string) => T | Promise<T>
+): Promise<T | RouteResponse> {
+  return admission
+    ? admission((snapshot) =>
+        snapshot.storageMode === 'sqlite'
+          ? operation(snapshot.dataPath)
+          : {
+              status: 409,
+              body: {
+                ok: false,
+                error: `Database inspection requires Bunqueue SQLite storage; ${snapshot.storageMode} is active`,
+              },
+            }
+      )
+    : Promise.resolve(operation(dataPath));
+}

package/agent/server/errors.ts

@@ -19,6 +19,7 @@ const CONFLICT_MESSAGES = [
   'BUNQUEUE_WORKFLOW_CONCURRENCY must',
   'Managed Bunqueue server restarted',
   'Server lifecycle is disabled in external mode',
+  'Configuration changed since revision',
 ];
 
 export function errorStatus(error: unknown): number {

package/agent/server/lifecycle.ts

@@ -18,6 +18,7 @@ export class AgentLifecycleGate implements AgentLifecyclePort {
   private leases = new Set<Promise<void>>();
   private closed = false;
   private closing: Promise<void> | null = null;
+  private pendingTransitions = 0;
 
   assertOpen(): void {
     if (this.closed) throw new AgentLifecycleClosedError();
@@ -29,14 +30,25 @@ export class AgentLifecycleGate implements AgentLifecyclePort {
     } catch (error) {
       return Promise.reject(error);
     }
-    const result = this.barrier.then(operation);
     const batch = this.leases;
-    const completion = result.then(
-      () => undefined,
-      () => undefined
-    );
+    let complete!: () => void;
+    const completion = new Promise<void>((resolve) => {
+      complete = resolve;
+    });
+    // Publish the lease before invoking user code. Its synchronous prefix may
+    // re-enter run()/close(), which must observe this lease and wait for it.
     batch.add(completion);
-    void completion.then(() => batch.delete(completion));
+    let result: Promise<T>;
+    if (this.pendingTransitions === 0) {
+      try {
+        result = Promise.resolve(operation());
+      } catch (error) {
+        result = Promise.reject(error);
+      }
+    } else {
+      result = this.barrier.then(operation);
+    }
+    void result.then(complete, complete).then(() => batch.delete(completion));
     return result;
   }
 
@@ -60,12 +72,17 @@ export class AgentLifecycleGate implements AgentLifecyclePort {
     const precedingBarrier = this.barrier;
     const precedingLeases = this.leases;
     this.leases = new Set();
+    this.pendingTransitions += 1;
     const result = precedingBarrier
       .then(() => Promise.all(precedingLeases))
       .then(operation);
     this.barrier = result.then(
-      () => undefined,
-      () => undefined
+      () => {
+        this.pendingTransitions -= 1;
+      },
+      () => {
+        this.pendingTransitions -= 1;
+      }
     );
     return result;
   }

package/agent/server/managedRuntime.ts

@@ -1,4 +1,6 @@
 import type { ProcessManager, ServerConfig, StatusSnapshot } from '../manager';
+import { managedStorageMode } from '../manager';
+import type { ManagedStorageMode } from '../manager/storageMode';
 import type { AgentLifecyclePort } from './lifecycle';
 
 export interface ManagedRuntimeSnapshot {
@@ -10,6 +12,15 @@ export type ManagedRuntimeAdmission = <T>(
   operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
 ) => Promise<T>;
 
+export interface ManagedDatabaseSnapshot {
+  dataPath: string;
+  storageMode: ManagedStorageMode;
+}
+
+export type ManagedDatabaseAdmission = <T>(
+  operation: (snapshot: ManagedDatabaseSnapshot) => T | Promise<T>
+) => Promise<T>;
+
 /**
  * Admit SDK work against one managed-process generation. The operation and its
  * final state/config check share the same lifecycle section as start/stop.
@@ -32,6 +43,22 @@ export function managedRuntimeAdmission(
     });
 }
 
+/** Pin DB-backed observability to the live process config for one reader lease. */
+export function managedDatabaseAdmission(
+  manager: ProcessManager,
+  lifecycle: AgentLifecyclePort
+): ManagedDatabaseAdmission {
+  return (operation) =>
+    lifecycle.lease(async () => {
+      const snapshot = manager.getStatus();
+      const config = snapshot.runningConfig ?? snapshot.config;
+      return operation({
+        dataPath: config.dataPath,
+        storageMode: managedStorageMode(config),
+      });
+    });
+}
+
 function generationChanged(initial: StatusSnapshot, current: StatusSnapshot): boolean {
   return (
     initial.status === 'running' &&

package/agent/server/router.ts

@@ -1,8 +1,11 @@
-import { routeBackupRequest } from '../backup/routes';
+import {
+  executePreparedBackupRequest,
+  prepareBackupRequest,
+} from '../backup/routes';
 import type { BackupRunnerPort } from '../backup/runner';
 import { routeFlowRequest } from '../flow/routes';
 import type { ManagedTargetPolicy } from '../managedTarget';
-import type { ProcessManager } from '../manager';
+import { managedStorageMode, type ProcessManager } from '../manager';
 import { routeQueueOperationsRequest } from '../queue/routes';
 import type { QueueOperationsPort } from '../queue/types';
 import type { WorkflowRuntimePort } from '../workflow/runtime';
@@ -11,7 +14,7 @@ import { assertManagedControl, routeControlRequest } from './controlRoutes';
 import type { ServerControlTarget } from './controlTarget';
 import { routeDatabaseRequest } from './databaseRoutes';
 import type { AgentLifecyclePort } from './lifecycle';
-import { managedRuntimeAdmission } from './managedRuntime';
+import { managedDatabaseAdmission, managedRuntimeAdmission } from './managedRuntime';
 import type { RouteResponse } from './types';
 import { routeWorkflowReadRequest } from './workflowReadRoutes';
 
@@ -44,7 +47,9 @@ export async function routeAgentRequest(
 
   const snapshot = manager.getStatus();
   const managedConfig = snapshot.runningConfig ?? snapshot.config;
+  const storageMode = managedStorageMode(managedConfig);
   const admission = managedRuntimeAdmission(manager, lifecycle, snapshot);
+  const databaseAdmission = managedDatabaseAdmission(manager, lifecycle);
   if (pathname.startsWith('/flows/')) {
     const flow = await routeFlowRequest(
       request,
@@ -73,14 +78,16 @@ export async function routeAgentRequest(
     if (workflowRuntime) return workflowRuntime;
   }
 
-  const desiredConfig = manager.getConfig();
-  const workflowRead = routeWorkflowReadRequest(
-    request,
-    pathname,
-    method,
-    managedConfig.dataPath
-  );
-  if (workflowRead) return workflowRead;
+  if (isWorkflowReadRoute(pathname, method)) {
+    const workflowRead = await routeWorkflowReadRequest(
+      request,
+      pathname,
+      method,
+      managedConfig.dataPath,
+      databaseAdmission
+    );
+    if (workflowRead) return workflowRead;
+  }
 
   if (pathname.startsWith('/queue-operations/')) {
     const queueOperation = await routeQueueOperationsRequest(
@@ -97,54 +104,93 @@ export async function routeAgentRequest(
   }
 
   if (pathname.startsWith('/backup/')) {
+    if (storageMode !== 'sqlite') return sqliteOnly('S3 backup', storageMode);
     if (pathname === '/backup/restore' && method === 'POST') {
       assertManagedControl(controlTarget);
-      return manager.withStoppedMaintenance('restoring a backup', async () => {
-        const stoppedSnapshot = manager.getStatus();
-        const restoreDesired = manager.getConfig();
-        const restoreConfig = {
-          ...(stoppedSnapshot.runningConfig ?? stoppedSnapshot.config),
-          extraEnv: restoreDesired.extraEnv,
-        };
-        return routeBackupRequest(
-          request,
-          pathname,
-          method,
-          restoreConfig,
-          stoppedSnapshot.status === 'running',
-          await manager.dbStats(),
-          backupRunner,
-          undefined,
-          managedTargetPolicy
-        );
+      const prepared = await prepareBackupRequest(
+        request,
+        pathname,
+        method,
+        managedConfig,
+        managedTargetPolicy
+      );
+      if (!prepared || prepared.operation !== 'restore') return null;
+      return lifecycle.run(async () => {
+        const current = manager.getStatus();
+        const restoreConfig = current.runningConfig ?? current.config;
+        const currentStorageMode = managedStorageMode(restoreConfig);
+        if (currentStorageMode !== 'sqlite') {
+          return sqliteOnly('S3 backup', currentStorageMode);
+        }
+        return manager.withStoppedMaintenance('restoring a backup', async () => {
+          return executePreparedBackupRequest(
+            prepared,
+            restoreConfig,
+            current.status === 'running',
+            await manager.dbStats(restoreConfig.dataPath),
+            backupRunner,
+            undefined,
+            managedTargetPolicy
+          );
+        });
       });
     }
-    const database = await manager.dbStats();
-    const backupConfig = { ...managedConfig, extraEnv: desiredConfig.extraEnv };
-    const backup = await routeBackupRequest(
+    const prepared = await prepareBackupRequest(
       request,
       pathname,
       method,
-      backupConfig,
-      snapshot.status === 'running',
-      database,
-      backupRunner,
-      (extraEnv) => manager.setConfig({ extraEnv }),
+      managedConfig,
       managedTargetPolicy
     );
-    if (backup) return backup;
+    if (prepared) {
+      const execute = async () => {
+        const current = manager.getStatus();
+        const desired = manager.getConfig();
+        const effective = current.runningConfig ?? current.config;
+        const backupConfig = { ...effective, extraEnv: desired.extraEnv };
+        const currentStorageMode = managedStorageMode(backupConfig);
+        if (currentStorageMode !== 'sqlite') {
+          return sqliteOnly('S3 backup', currentStorageMode);
+        }
+        return executePreparedBackupRequest(
+          prepared,
+          backupConfig,
+          current.status === 'running',
+          await manager.dbStats(backupConfig.dataPath),
+          backupRunner,
+          (extraEnv) => {
+            manager.setConfig({ extraEnv });
+          },
+          managedTargetPolicy
+        );
+      };
+      return prepared.operation === 'configure'
+        ? lifecycle.run(execute)
+        : lifecycle.lease(execute);
+    }
   }
 
+  if ((pathname === '/db' || pathname.startsWith('/db/')) && storageMode !== 'sqlite') {
+    return sqliteOnly('Database inspection', storageMode);
+  }
   return routeDatabaseRequest(
     request,
     pathname,
     method,
-    desiredConfig.dataPath,
+    managedConfig.dataPath,
     origin,
-    allowedOrigins
+    allowedOrigins,
+    databaseAdmission
   );
 }
 
+function sqliteOnly(feature: string, storageMode: 'memory' | 'postgres'): RouteResponse {
+  return {
+    status: 409,
+    body: { ok: false, error: `${feature} requires Bunqueue SQLite storage; ${storageMode} is active` },
+  };
+}
+
 function isWorkflowRuntimeRoute(pathname: string, method: string): boolean {
   if (method === 'GET') return pathname === '/workflows/runtime';
   if (method !== 'POST') return false;
@@ -159,3 +205,7 @@ function isWorkflowRuntimeRoute(pathname: string, method: string): boolean {
     /^\/workflows\/[^/]+\/(signal|resume-compensation|abandon-compensation)$/.test(pathname)
   );
 }
+
+function isWorkflowReadRoute(pathname: string, method: string): boolean {
+  return method === 'GET' && (pathname === '/workflows' || pathname.startsWith('/workflows/'));
+}