bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/server/router.ts

@@ -0,0 +1,161 @@
+import { routeBackupRequest } 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 { 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 type { ServerControlTarget } from './controlTarget';
+import { routeDatabaseRequest } from './databaseRoutes';
+import type { AgentLifecyclePort } from './lifecycle';
+import { managedRuntimeAdmission } from './managedRuntime';
+import type { RouteResponse } from './types';
+import { routeWorkflowReadRequest } from './workflowReadRoutes';
+
+export async function routeAgentRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  manager: ProcessManager,
+  runtime: WorkflowRuntimePort,
+  backupRunner: BackupRunnerPort,
+  queueRuntime: QueueOperationsPort,
+  lifecycle: AgentLifecyclePort,
+  origin: string | null,
+  allowedOrigins: string[],
+  controlTarget: ServerControlTarget,
+  managedTargetPolicy?: ManagedTargetPolicy
+): Promise<RouteResponse | Response | null> {
+  if (pathname.startsWith('/control/')) {
+    const control = await routeControlRequest(
+      request,
+      pathname,
+      method,
+      manager,
+      runtime,
+      lifecycle,
+      controlTarget
+    );
+    if (control) return control;
+  }
+
+  const snapshot = manager.getStatus();
+  const managedConfig = snapshot.runningConfig ?? snapshot.config;
+  const admission = managedRuntimeAdmission(manager, lifecycle, snapshot);
+  if (pathname.startsWith('/flows/')) {
+    const flow = await routeFlowRequest(
+      request,
+      pathname,
+      method,
+      managedConfig,
+      snapshot.status === 'running',
+      { admission, targetPolicy: managedTargetPolicy }
+    );
+    if (flow) return flow;
+  }
+
+  // Runtime control must precede the generic /workflows/:executionId reader,
+  // otherwise GET /workflows/runtime is interpreted as an execution lookup.
+  if (isWorkflowRuntimeRoute(pathname, method)) {
+    const workflowRuntime = await routeWorkflowRuntimeRequest(
+      request,
+      pathname,
+      method,
+      managedConfig,
+      runtime,
+      snapshot.status === 'running',
+      admission,
+      managedTargetPolicy
+    );
+    if (workflowRuntime) return workflowRuntime;
+  }
+
+  const desiredConfig = manager.getConfig();
+  const workflowRead = routeWorkflowReadRequest(
+    request,
+    pathname,
+    method,
+    managedConfig.dataPath
+  );
+  if (workflowRead) return workflowRead;
+
+  if (pathname.startsWith('/queue-operations/')) {
+    const queueOperation = await routeQueueOperationsRequest(
+      request,
+      pathname,
+      method,
+      managedConfig,
+      queueRuntime,
+      snapshot.status === 'running',
+      admission,
+      managedTargetPolicy
+    );
+    if (queueOperation) return queueOperation;
+  }
+
+  if (pathname.startsWith('/backup/')) {
+    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 database = await manager.dbStats();
+    const backupConfig = { ...managedConfig, extraEnv: desiredConfig.extraEnv };
+    const backup = await routeBackupRequest(
+      request,
+      pathname,
+      method,
+      backupConfig,
+      snapshot.status === 'running',
+      database,
+      backupRunner,
+      (extraEnv) => manager.setConfig({ extraEnv }),
+      managedTargetPolicy
+    );
+    if (backup) return backup;
+  }
+
+  return routeDatabaseRequest(
+    request,
+    pathname,
+    method,
+    desiredConfig.dataPath,
+    origin,
+    allowedOrigins
+  );
+}
+
+function isWorkflowRuntimeRoute(pathname: string, method: string): boolean {
+  if (method === 'GET') return pathname === '/workflows/runtime';
+  if (method !== 'POST') return false;
+  return (
+    [
+      '/workflows/runtime/reload',
+      '/workflows/start',
+      '/workflows/recover',
+      '/workflows/archive',
+      '/workflows/cleanup',
+    ].includes(pathname) ||
+    /^\/workflows\/[^/]+\/(signal|resume-compensation|abandon-compensation)$/.test(pathname)
+  );
+}

package/agent/server/types.ts

@@ -0,0 +1,46 @@
+import type { WorkflowRuntimePort } from '../workflow/runtime';
+import type { ServerControlTarget } from './controlTarget';
+
+export interface AgentOptions {
+  allowedOrigins: string[];
+  /** DNS-rebinding defense; compared by hostname only. */
+  allowedHosts?: string[];
+  /** On loopback, when set, changing requests must present this token. */
+  token?: string;
+  /** Network exposure: require token on every non-OPTIONS request. */
+  requireTokenForAll?: boolean;
+  /** Managed child by default; external mode makes lifecycle routes attach-only. */
+  controlTarget?: ServerControlTarget;
+  /** Exact browser-visible `/api` alias accepted by target-pinned agent routes. */
+  managedProxyPath?: string;
+  /** Upstream URL the alias must resolve to; it still passes the local-target gate. */
+  managedProxyUrl?: string;
+}
+
+export interface AgentFetchHandler {
+  (request: Request): Promise<Response>;
+  /** Release the handler's persistent SDK resources. */
+  close(): Promise<void>;
+  /** Synchronously close admission and latch the process manager, then drain resources. */
+  beginShutdown(): Promise<void>;
+  /** Close resources through the lifecycle gate, then stop the managed process. */
+  shutdown(): Promise<void>;
+  /** Send SIGKILL to the managed process after terminal grace is exhausted. */
+  forceShutdown(): void;
+}
+
+export interface RouteResponse {
+  status: number;
+  body: unknown;
+}
+
+export type JsonResponder = (
+  data: unknown,
+  status: number,
+  origin: string | null
+) => Response;
+
+export interface HandlerResources {
+  runtime: WorkflowRuntimePort;
+  close(): Promise<void>;
+}

package/agent/server/workflowReadRoutes.ts

@@ -0,0 +1,80 @@
+import {
+  type WorkflowStateFilter,
+  type WorkflowStoreKind,
+  workflowExecution,
+  workflowExecutions,
+  workflowStats,
+  WORKFLOW_STATES,
+} from '../workflows';
+import type { RouteResponse } from './types';
+
+function workflowKind(query: URLSearchParams): WorkflowStoreKind {
+  const kind = query.get('kind') ?? 'active';
+  if (kind !== 'active' && kind !== 'archive') {
+    throw new Error('Workflow kind must be "active" or "archive"');
+  }
+  return kind;
+}
+
+function integer(query: URLSearchParams, name: 'limit' | 'offset', fallback: number): number {
+  const raw = query.get(name);
+  if (raw === null) return fallback;
+  if (!/^\d+$/.test(raw)) throw new Error(`Workflow ${name} must be an integer`);
+  return Number(raw);
+}
+
+export function routeWorkflowReadRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  dataPath: string
+): RouteResponse | null {
+  if (pathname === '/workflows/stats' && method === 'GET') {
+    return { status: 200, body: { ok: true, ...workflowStats(dataPath) } };
+  }
+  if (pathname === '/workflows' && method === 'GET') {
+    const query = new URL(request.url).searchParams;
+    const allowed = new Set(['kind', 'workflowName', 'state', 'limit', 'offset']);
+    for (const key of query.keys()) {
+      if (!allowed.has(key)) throw new Error(`Unknown workflow option: ${key}`);
+      if (query.getAll(key).length !== 1) throw new Error(`Duplicate workflow option: ${key}`);
+    }
+    const state = query.get('state') || undefined;
+    if (
+      state &&
+      state !== 'compensation' &&
+      !(WORKFLOW_STATES as readonly string[]).includes(state)
+    ) {
+      throw new Error('Unknown workflow execution state');
+    }
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        ...workflowExecutions(dataPath, {
+          kind: workflowKind(query),
+          workflowName: query.get('workflowName') || undefined,
+          state: state as WorkflowStateFilter | undefined,
+          limit: integer(query, 'limit', 50),
+          offset: integer(query, 'offset', 0),
+        }),
+      },
+    };
+  }
+  if (!pathname.startsWith('/workflows/') || method !== 'GET') return null;
+  const rawId = pathname.slice('/workflows/'.length);
+  if (!rawId || rawId.includes('/')) {
+    return { status: 404, body: { ok: false, error: 'Not found' } };
+  }
+  const query = new URL(request.url).searchParams;
+  for (const key of query.keys()) {
+    if (key !== 'kind') throw new Error(`Unknown workflow detail option: ${key}`);
+    if (query.getAll(key).length !== 1) {
+      throw new Error(`Duplicate workflow detail option: ${key}`);
+    }
+  }
+  const execution = workflowExecution(dataPath, decodeURIComponent(rawId), workflowKind(query));
+  return execution
+    ? { status: 200, body: { ok: true, execution } }
+    : { status: 404, body: { ok: false, error: 'Workflow execution not found' } };
+}