bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/server/databaseRoutes.ts

@@ -0,0 +1,165 @@
+import {
+  type DbFilter,
+  dbCell,
+  dbInfo,
+  dbRows,
+  dbSchema,
+  dbTables,
+  exportWithTimeout,
+  queryWithTimeout,
+} from '../db';
+import { corsHeaders } from './policy';
+import { readLimitedJsonBody } from './jsonBody';
+import type { RouteResponse } from './types';
+
+const MAX_QUERY_BODY_BYTES = 64 * 1024;
+
+function exportFilter(query: URLSearchParams): DbFilter | undefined {
+  const column = query.get('fcol');
+  const operation = query.get('fop');
+  const value = query.get('fval');
+  const hasPart = column !== null || operation !== null || value !== null;
+  if (!hasPart) return undefined;
+  if (
+    !column ||
+    !value ||
+    (operation !== 'contains' && operation !== 'eq' && operation !== 'ne')
+  ) {
+    throw new Error('Database export filter requires valid fcol, fop and fval values');
+  }
+  return { column, op: operation, value };
+}
+
+function validateExportQuery(query: URLSearchParams): void {
+  const allowed = new Set(['orderBy', 'dir', 'fcol', 'fop', 'fval']);
+  for (const key of query.keys()) {
+    if (!allowed.has(key)) throw new Error(`Unknown database export option: ${key}`);
+    if (query.getAll(key).length !== 1) {
+      throw new Error(`Duplicate database export option: ${key}`);
+    }
+  }
+}
+
+async function exportTable(
+  request: Request,
+  table: string,
+  dataPath: string,
+  origin: string | null,
+  allowedOrigins: string[]
+): Promise<Response> {
+  const query = new URL(request.url).searchParams;
+  validateExportQuery(query);
+  const orderBy = query.get('orderBy');
+  if (orderBy === '') throw new Error('Database export orderBy must not be empty');
+  const direction = query.get('dir');
+  if (direction !== null && direction !== 'asc' && direction !== 'desc') {
+    throw new Error('Database export dir must be "asc" or "desc"');
+  }
+  const exported = await exportWithTimeout(
+    dataPath,
+    table,
+    orderBy ?? undefined,
+    direction === 'desc' ? 'desc' : 'asc',
+    exportFilter(query),
+    request.signal
+  );
+  return new Response(exported.content, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/csv; charset=utf-8',
+      'Content-Length': String(exported.bytes),
+      'Cache-Control': 'no-store, no-transform',
+      'X-Content-Type-Options': 'nosniff',
+      'X-Bunqueue-Db-Export-Version': '1',
+      'X-Bunqueue-Db-Export-Table': encodeURIComponent(exported.table),
+      'X-Bunqueue-Db-Export-Rows': String(exported.rowCount),
+      'X-Bunqueue-Db-Export-Bytes': String(exported.bytes),
+      'X-Bunqueue-Db-Export-Cap': exported.cap ?? 'none',
+      'Access-Control-Expose-Headers':
+        'Content-Length, X-Bunqueue-Db-Export-Version, X-Bunqueue-Db-Export-Table, X-Bunqueue-Db-Export-Rows, X-Bunqueue-Db-Export-Bytes, X-Bunqueue-Db-Export-Cap',
+      ...corsHeaders(origin, allowedOrigins),
+    },
+  });
+}
+
+function browseFilter(query: URLSearchParams): DbFilter | undefined {
+  const column = query.get('fcol');
+  const operation = query.get('fop');
+  const value = query.get('fval');
+  if (!column || !value) return undefined;
+  return {
+    column,
+    op: operation === 'eq' ? 'eq' : operation === 'ne' ? 'ne' : 'contains',
+    value,
+  };
+}
+
+export async function routeDatabaseRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  dataPath: string,
+  origin: string | null,
+  allowedOrigins: string[]
+): Promise<RouteResponse | Response | null> {
+  if (pathname === '/db/info' && method === 'GET') {
+    return { status: 200, body: { ok: true, ...dbInfo(dataPath) } };
+  }
+  if (pathname === '/db/tables' && method === 'GET') {
+    return { status: 200, body: { ok: true, tables: dbTables(dataPath) } };
+  }
+  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);
+    }
+    if (segments.length === 2 && subresource === 'schema') {
+      return { status: 200, body: { ok: true, ...dbSchema(dataPath, 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 {
+        status: 200,
+        body: {
+          ok: true,
+          ...dbCell(dataPath, 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 {
+      status: 200,
+      body: {
+        ok: true,
+        ...dbRows(
+          dataPath,
+          table,
+          Number(query.get('limit')) || 50,
+          Number(query.get('offset')) || 0,
+          query.get('orderBy') || undefined,
+          query.get('dir') === 'desc' ? 'desc' : 'asc',
+          browseFilter(query)
+        ),
+      },
+    };
+  }
+  if (pathname === '/db/query' && method === 'POST') {
+    const { sql } = (await readLimitedJsonBody(request, {
+      scope: 'Database query',
+      maxBytes: MAX_QUERY_BODY_BYTES,
+      limitLabel: '64 KiB',
+    })) as { sql?: string };
+    return {
+      status: 200,
+      body: { ok: true, ...(await queryWithTimeout(dataPath, sql ?? '')) },
+    };
+  }
+  return null;
+}

package/agent/server/errors.ts

@@ -0,0 +1,49 @@
+import {
+  DbExportBusyError,
+  DbExportUnavailableError,
+  MissingDbError,
+} from '../db';
+import { safeErrorMessage } from '../errorMessage';
+import { QueueOperationsUnavailableError } from '../queue/types';
+import { WorkflowRuntimeUnavailableError } from '../workflow/runtime';
+import { AgentLifecycleClosedError } from './lifecycle';
+
+const CONFLICT_MESSAGES = [
+  'Start the managed Bunqueue server',
+  'Stop the managed Bunqueue server',
+  'Another backup operation is already running',
+  'Another maintenance operation is already running',
+  'Cannot start the managed Bunqueue server',
+  'Cannot restart the managed Bunqueue server',
+  'BUNQUEUE_WORKFLOW_QUEUE_NAME must',
+  'BUNQUEUE_WORKFLOW_CONCURRENCY must',
+  'Managed Bunqueue server restarted',
+  'Server lifecycle is disabled in external mode',
+];
+
+export function errorStatus(error: unknown): number {
+  try {
+    if (error instanceof AgentLifecycleClosedError) return 503;
+    if (error instanceof MissingDbError) return 404;
+    if (error instanceof DbExportBusyError) return 429;
+    if (error instanceof DbExportUnavailableError) return 503;
+    if (error instanceof QueueOperationsUnavailableError) {
+      return error.message.includes('runtime is closed') ? 503 : 409;
+    }
+    if (error instanceof WorkflowRuntimeUnavailableError) {
+      // Configuration shape is actionable by the caller; a missing/unreadable
+      // configured module is an unavailable server-side dependency.
+      return /^(Set BUNQUEUE_WORKFLOW_MODULE|BUNQUEUE_WORKFLOW_MODULE must|BUNQUEUE_WORKFLOW_QUEUE_NAME must|BUNQUEUE_WORKFLOW_CONCURRENCY must|Workflow module must|workflowNames must)/.test(error.message)
+        ? 409
+        : 503;
+    }
+  } catch {
+    return 500;
+  }
+  const message = safeErrorMessage(error);
+  return CONFLICT_MESSAGES.some((prefix) => message.startsWith(prefix)) ? 409 : 400;
+}
+
+export function errorMessage(error: unknown): string {
+  return safeErrorMessage(error);
+}

package/agent/server/handler.ts

@@ -0,0 +1,155 @@
+import { BunqueueBackupRunner, type BackupRunnerPort } from '../backup/runner';
+import type { ProcessManager } from '../manager';
+import { QueueOperationsRuntime } from '../queue/runtime';
+import type { QueueOperationsPort } from '../queue/types';
+import { WorkflowRuntime, type WorkflowRuntimePort } from '../workflow/runtime';
+import { resolveManagedTargetPolicy } from '../managedTarget';
+import { errorMessage, errorStatus } from './errors';
+import { MANAGED_CONTROL_TARGET } from './controlTarget';
+import { AgentLifecycleGate, type AgentLifecyclePort } from './lifecycle';
+import { corsHeaders, isHostAllowed, isOriginAllowed, tokenOk } from './policy';
+import { routeAgentRequest } from './router';
+import type { AgentFetchHandler, AgentOptions, RouteResponse } from './types';
+
+function responseOf(
+  result: RouteResponse | Response | null,
+  origin: string | null,
+  allowedOrigins: string[]
+): Response {
+  if (result instanceof Response) return result;
+  const routed = result ?? { status: 404, body: { ok: false, error: 'Not found' } };
+  return new Response(JSON.stringify(routed.body), {
+    status: routed.status,
+    headers: {
+      'Content-Type': 'application/json',
+      ...corsHeaders(origin, allowedOrigins),
+    },
+  });
+}
+
+/** Build a network-independent request handler with persistent SDK resources. */
+export function createFetchHandler(
+  manager: ProcessManager,
+  options: AgentOptions,
+  runtime: WorkflowRuntimePort = new WorkflowRuntime(),
+  backupRunner: BackupRunnerPort = new BunqueueBackupRunner(),
+  queueRuntime: QueueOperationsPort = new QueueOperationsRuntime(),
+  lifecycle: AgentLifecyclePort = new AgentLifecycleGate()
+): AgentFetchHandler {
+  const {
+    allowedOrigins,
+    allowedHosts,
+    token,
+    requireTokenForAll = false,
+    controlTarget = MANAGED_CONTROL_TARGET,
+  } = options;
+  const managedTargetPolicy = resolveManagedTargetPolicy(
+    options.managedProxyPath,
+    options.managedProxyUrl
+  );
+  const json = (body: unknown, status: number, origin: string | null) =>
+    responseOf({ body, status }, origin, allowedOrigins);
+
+  const handle = async (request: Request): Promise<Response> => {
+    const { pathname } = new URL(request.url);
+    const method = request.method;
+    const origin = request.headers.get('origin');
+    if (!isHostAllowed(request.headers.get('host'), allowedHosts)) {
+      return json({ ok: false, error: 'Host not allowed' }, 403, origin);
+    }
+    if (!isOriginAllowed(origin, allowedOrigins)) {
+      return json({ ok: false, error: 'Origin not allowed' }, 403, origin);
+    }
+    if (method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: corsHeaders(origin, allowedOrigins) });
+    }
+    const mutating = method === 'POST' || method === 'PUT';
+    const authRequired = requireTokenForAll || (mutating && Boolean(token));
+    if (authRequired && !tokenOk(request, token)) {
+      return json({ ok: false, error: 'Unauthorized' }, 401, origin);
+    }
+
+    try {
+      lifecycle.assertOpen();
+      const result = await routeAgentRequest(
+        request,
+        pathname,
+        method,
+        manager,
+        runtime,
+        backupRunner,
+        queueRuntime,
+        lifecycle,
+        origin,
+        allowedOrigins,
+        controlTarget,
+        managedTargetPolicy
+      );
+      return responseOf(result, origin, allowedOrigins);
+    } catch (error) {
+      return json({ ok: false, error: errorMessage(error) }, errorStatus(error), origin);
+    }
+  };
+  let closing: Promise<void> | null = null;
+  const close = () => {
+    closing ??= lifecycle.close(() =>
+      settleResourceClosures([
+        () => runtime.close(),
+        () => backupRunner.close(),
+        () => queueRuntime.close(),
+      ])
+    );
+    return closing;
+  };
+  const beginShutdown = () => {
+    manager.beginShutdown();
+    return close();
+  };
+  let shuttingDown: Promise<void> | null = null;
+  const shutdown = () => {
+    shuttingDown ??= closeThenShutdown(beginShutdown, manager);
+    return shuttingDown;
+  };
+  const forceShutdown = () => manager.forceShutdown();
+  return Object.assign(handle, { close, beginShutdown, shutdown, forceShutdown });
+}
+
+async function closeThenShutdown(
+  beginShutdown: () => Promise<void>,
+  manager: ProcessManager
+): Promise<void> {
+  const closeResult = await settle(beginShutdown);
+  const shutdownResult = await settle(() => manager.shutdown());
+  if (!closeResult.ok && !shutdownResult.ok) {
+    throw new AggregateError(
+      [closeResult.error, shutdownResult.error],
+      'Agent resources and managed server both failed to shut down'
+    );
+  }
+  if (!closeResult.ok) throw closeResult.error;
+  if (!shutdownResult.ok) throw shutdownResult.error;
+}
+
+async function settleResourceClosures(closures: Array<() => Promise<void>>): Promise<void> {
+  const settled = await Promise.allSettled(
+    closures.map((closeResource) => Promise.resolve().then(closeResource))
+  );
+  const failures = settled.flatMap((result) =>
+    result.status === 'rejected' ? [result.reason] : []
+  );
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) {
+    throw new AggregateError(failures, 'Multiple agent resources failed to close');
+  }
+}
+
+type SettledOperation = { ok: true } | { ok: false; error: unknown };
+
+async function settle(operation: () => Promise<unknown>): Promise<SettledOperation> {
+  try {
+    await operation();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}

package/agent/server/jsonBody.ts

@@ -0,0 +1,109 @@
+export interface LimitedJsonBodyOptions {
+  scope: string;
+  maxBytes: number;
+  limitLabel: string;
+  invalidContentLengthMessage?: string;
+  exceedsMessage?: string;
+  missingMessage?: string;
+  invalidUtf8Message?: string;
+  invalidJsonMessage?: string;
+}
+
+/** Read and parse a JSON body without ever buffering more than maxBytes. */
+export async function readLimitedJsonBody(
+  request: Request,
+  options: LimitedJsonBodyOptions
+): Promise<unknown> {
+  validateContentLength(request.headers.get('content-length'), options);
+  if (!request.body) throw new Error(message(options, 'missing'));
+
+  const reader = request.body.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const textChunks: string[] = [];
+  let totalBytes = 0;
+  try {
+    for (;;) {
+      const next = await reader.read();
+      if (next.done) break;
+      totalBytes += next.value.byteLength;
+      if (totalBytes > options.maxBytes) {
+        throw new Error(message(options, 'exceeds'));
+      }
+      textChunks.push(decode(decoder, next.value, true, options));
+    }
+    textChunks.push(decode(decoder, undefined, false, options));
+  } catch (error) {
+    await cancelQuietly(reader);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+
+  if (totalBytes === 0) throw new Error(message(options, 'missing'));
+  try {
+    return JSON.parse(textChunks.join(''));
+  } catch {
+    throw new Error(message(options, 'invalidJson'));
+  }
+}
+
+function validateContentLength(
+  declared: string | null,
+  options: LimitedJsonBodyOptions
+): void {
+  if (declared === null) return;
+  if (!/^\d+$/.test(declared)) {
+    throw new Error(message(options, 'invalidContentLength'));
+  }
+  const normalized = declared.replace(/^0+/, '') || '0';
+  const maximum = String(options.maxBytes);
+  if (
+    normalized.length > maximum.length ||
+    (normalized.length === maximum.length && normalized > maximum)
+  ) {
+    throw new Error(message(options, 'exceeds'));
+  }
+}
+
+function decode(
+  decoder: TextDecoder,
+  value: Uint8Array | undefined,
+  stream: boolean,
+  options: LimitedJsonBodyOptions
+): string {
+  try {
+    return decoder.decode(value, { stream });
+  } catch {
+    throw new Error(message(options, 'invalidUtf8'));
+  }
+}
+
+async function cancelQuietly(reader: { cancel(reason?: unknown): Promise<void> }): Promise<void> {
+  await reader.cancel().catch(() => undefined);
+}
+
+type MessageKind =
+  | 'invalidContentLength'
+  | 'exceeds'
+  | 'missing'
+  | 'invalidUtf8'
+  | 'invalidJson';
+
+function message(options: LimitedJsonBodyOptions, kind: MessageKind): string {
+  if (kind === 'invalidContentLength') {
+    return (
+      options.invalidContentLengthMessage ??
+      `${options.scope} Content-Length must be a non-negative integer`
+    );
+  }
+  if (kind === 'exceeds') {
+    return options.exceedsMessage ?? `${options.scope} request exceeds ${options.limitLabel}`;
+  }
+  if (kind === 'missing') {
+    return options.missingMessage ?? `${options.scope} request body is required`;
+  }
+  if (kind === 'invalidUtf8') {
+    return options.invalidUtf8Message ?? `${options.scope} request body must use valid UTF-8`;
+  }
+  return options.invalidJsonMessage ?? `${options.scope} request body must contain valid JSON`;
+}

package/agent/server/lifecycle.ts

@@ -0,0 +1,72 @@
+/** Coordinates exclusive process transitions with concurrent SDK leases. */
+export interface AgentLifecyclePort {
+  assertOpen(): void;
+  lease<T>(operation: () => Promise<T>): Promise<T>;
+  run<T>(operation: () => Promise<T>): Promise<T>;
+  close(operation: () => Promise<void>): Promise<void>;
+}
+
+export class AgentLifecycleClosedError extends Error {
+  constructor() {
+    super('The Bunqueue control agent is closing');
+    this.name = 'AgentLifecycleClosedError';
+  }
+}
+
+export class AgentLifecycleGate implements AgentLifecyclePort {
+  private barrier: Promise<void> = Promise.resolve();
+  private leases = new Set<Promise<void>>();
+  private closed = false;
+  private closing: Promise<void> | null = null;
+
+  assertOpen(): void {
+    if (this.closed) throw new AgentLifecycleClosedError();
+  }
+
+  lease<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      this.assertOpen();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    const result = this.barrier.then(operation);
+    const batch = this.leases;
+    const completion = result.then(
+      () => undefined,
+      () => undefined
+    );
+    batch.add(completion);
+    void completion.then(() => batch.delete(completion));
+    return result;
+  }
+
+  run<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      this.assertOpen();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.enqueueTransition(operation);
+  }
+
+  close(operation: () => Promise<void>): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true;
+    this.closing = this.enqueueTransition(operation);
+    return this.closing;
+  }
+
+  private enqueueTransition<T>(operation: () => Promise<T>): Promise<T> {
+    const precedingBarrier = this.barrier;
+    const precedingLeases = this.leases;
+    this.leases = new Set();
+    const result = precedingBarrier
+      .then(() => Promise.all(precedingLeases))
+      .then(operation);
+    this.barrier = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}

package/agent/server/managedRuntime.ts

@@ -0,0 +1,41 @@
+import type { ProcessManager, ServerConfig, StatusSnapshot } from '../manager';
+import type { AgentLifecyclePort } from './lifecycle';
+
+export interface ManagedRuntimeSnapshot {
+  config: ServerConfig;
+  running: boolean;
+}
+
+export type ManagedRuntimeAdmission = <T>(
+  operation: (snapshot: ManagedRuntimeSnapshot) => 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.
+ */
+export function managedRuntimeAdmission(
+  manager: ProcessManager,
+  lifecycle: AgentLifecyclePort,
+  initial: StatusSnapshot
+): ManagedRuntimeAdmission {
+  return (operation) =>
+    lifecycle.lease(async () => {
+      const current = manager.getStatus();
+      if (generationChanged(initial, current)) {
+        throw new Error('Managed Bunqueue server restarted while the request was prepared');
+      }
+      return operation({
+        config: current.runningConfig ?? current.config,
+        running: current.status === 'running',
+      });
+    });
+}
+
+function generationChanged(initial: StatusSnapshot, current: StatusSnapshot): boolean {
+  return (
+    initial.status === 'running' &&
+    current.status === 'running' &&
+    initial.generation !== current.generation
+  );
+}

package/agent/server/policy.ts

@@ -0,0 +1,60 @@
+const DEFAULT_ORIGINS = ['http://localhost:5273', 'http://127.0.0.1:5273'];
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '::1', '0.0.0.0'];
+
+export function resolveAllowedOrigins(env = process.env): string[] {
+  const extra = (env.AGENT_ALLOWED_ORIGINS ?? '')
+    .split(',')
+    .map((origin) => origin.trim().replace(/\/$/, ''))
+    .filter(Boolean);
+  return Array.from(new Set([...DEFAULT_ORIGINS, ...extra]));
+}
+
+/** Extract a lowercase bare hostname from a Host header or origin. */
+export function hostnameOf(host: string): string {
+  const stripped = host.trim().replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  const ipv6 = stripped.match(/^\[([^\]]+)\]/);
+  if (ipv6) return ipv6[1].toLowerCase();
+  const firstColon = stripped.indexOf(':');
+  if (firstColon === -1) return stripped.toLowerCase();
+  if (firstColon !== stripped.lastIndexOf(':')) return stripped.toLowerCase();
+  return stripped.slice(0, firstColon).toLowerCase();
+}
+
+export function resolveAllowedHosts(env = process.env, extra: string[] = []): string[] {
+  const fromEnvironment = (env.AGENT_ALLOWED_HOSTS ?? '')
+    .split(',')
+    .map((host) => hostnameOf(host.trim()))
+    .filter(Boolean);
+  const extraHosts = extra.map(hostnameOf).filter(Boolean);
+  return Array.from(new Set([...LOOPBACK_HOSTS, ...extraHosts, ...fromEnvironment]));
+}
+
+export function isOriginAllowed(origin: string | null, allowed: string[]): boolean {
+  if (!origin) return true;
+  return allowed.includes(origin.replace(/\/$/, ''));
+}
+
+export function isHostAllowed(host: string | null, allowed?: string[]): boolean {
+  if (!allowed) return true;
+  if (!host) return false;
+  return allowed.includes(hostnameOf(host));
+}
+
+export function corsHeaders(origin: string | null, allowed: string[]): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Agent-Token',
+    Vary: 'Origin',
+  };
+  if (origin && allowed.includes(origin.replace(/\/$/, ''))) {
+    headers['Access-Control-Allow-Origin'] = origin;
+  }
+  return headers;
+}
+
+export function tokenOk(request: Request, token?: string): boolean {
+  if (!token) return false;
+  const authorization = request.headers.get('authorization') ?? '';
+  const bearer = authorization.startsWith('Bearer ') ? authorization.slice(7) : '';
+  return bearer === token || request.headers.get('x-agent-token') === token;
+}