bunqueue-dashboard 0.0.35 → 0.0.36

package/agent/workflow/runtimeRoutes.ts

@@ -0,0 +1,162 @@
+import type { ExecutionState } from 'bunqueue/workflow';
+import { assertManagedTarget } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import { readLimitedJsonBody } from '../server/jsonBody';
+import type {
+  ManagedRuntimeAdmission,
+  ManagedRuntimeSnapshot,
+} from '../server/managedRuntime';
+import type { WorkflowRuntimePort } from './runtime';
+
+const MAX_WORKFLOW_BODY_BYTES = 1024 * 1024;
+
+export interface WorkflowRuntimeRouteResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+const TERMINAL_STATES = new Set<ExecutionState>(['completed', 'failed']);
+
+export async function routeWorkflowRuntimeRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  runtime: WorkflowRuntimePort,
+  serverRunning: boolean,
+  admission?: ManagedRuntimeAdmission
+): Promise<WorkflowRuntimeRouteResponse | null> {
+  if (!isRuntimePath(pathname, method)) return null;
+  const query = exactTargetQuery(request.url);
+  assertManagedTarget(query, config);
+  const admitted = <T>(
+    requiresRunning: boolean,
+    operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
+  ): Promise<T> => {
+    const execute = async (snapshot: ManagedRuntimeSnapshot) => {
+      assertManagedTarget(query, snapshot.config);
+      if (requiresRunning && !snapshot.running) {
+        throw new Error('Start the managed Bunqueue server before workflow control.');
+      }
+      return operation(snapshot);
+    };
+    return admission ? admission(execute) : execute({ config, running: serverRunning });
+  };
+  if (pathname === '/workflows/runtime' && method === 'GET') {
+    return success(
+      await admitted(false, ({ config: current, running }) => runtime.status(current, running))
+    );
+  }
+  if (!serverRunning) throw new Error('Start the managed Bunqueue server before workflow control.');
+  if (pathname === '/workflows/runtime/reload') {
+    return success(await admitted(true, ({ config: current }) => runtime.reload(current)));
+  }
+  if (pathname === '/workflows/start') {
+    const body = record(await workflowBody(request), ['workflowName', 'input']);
+    const workflowName = bounded(body.workflowName, 'workflowName', 256);
+    return success({
+      run: await admitted(true, ({ config: current }) =>
+        runtime.start(current, workflowName, body.input)
+      ),
+    });
+  }
+  if (pathname === '/workflows/recover') {
+    return success({
+      recovered: await admitted(true, ({ config: current }) => runtime.recover(current)),
+    });
+  }
+  if (pathname === '/workflows/archive' || pathname === '/workflows/cleanup') {
+    const body = record(await workflowBody(request), ['maxAgeMs', 'states']);
+    const maxAgeMs = boundedAge(body.maxAgeMs);
+    const states = terminalStates(body.states);
+    const affected = await admitted(true, ({ config: current }) =>
+      pathname === '/workflows/archive'
+        ? runtime.archive(current, maxAgeMs, states)
+        : runtime.cleanup(current, maxAgeMs, states)
+    );
+    return success({ affected });
+  }
+  const match = pathname.match(/^\/workflows\/([^/]+)\/(signal|resume-compensation|abandon-compensation)$/);
+  if (!match) return null;
+  const id = bounded(decodeURIComponent(match[1]), 'executionId', 1024);
+  if (match[2] === 'signal') {
+    const body = record(await workflowBody(request), ['event', 'payload']);
+    const event = bounded(body.event, 'event', 256);
+    await admitted(true, ({ config: current }) =>
+      runtime.signal(current, id, event, body.payload)
+    );
+  } else if (match[2] === 'resume-compensation') {
+    await admitted(true, ({ config: current }) => runtime.resumeCompensation(current, id));
+  } else {
+    await admitted(true, ({ config: current }) => runtime.abandonCompensation(current, id));
+  }
+  return success({ applied: true });
+}
+
+function isRuntimePath(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)
+  );
+}
+
+function exactTargetQuery(url: string): URLSearchParams {
+  const query = new URL(url).searchParams;
+  for (const key of query.keys()) {
+    if (key !== 'target') throw new Error(`Unknown workflow control option: ${key}`);
+    if (query.getAll(key).length !== 1) throw new Error(`Duplicate workflow control option: ${key}`);
+  }
+  return query;
+}
+
+function success(value: unknown): WorkflowRuntimeRouteResponse {
+  return { status: 200, body: { ok: true, result: value } };
+}
+
+function record(value: unknown, allowed: string[]): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Workflow control body must be an object');
+  }
+  const body = value as Record<string, unknown>;
+  const unknown = Object.keys(body).find((key) => !allowed.includes(key));
+  if (unknown) throw new Error(`Unknown workflow control option: ${unknown}`);
+  return body;
+}
+
+function workflowBody(request: Request): Promise<unknown> {
+  return readLimitedJsonBody(request, {
+    scope: 'Workflow control',
+    maxBytes: MAX_WORKFLOW_BODY_BYTES,
+    limitLabel: '1 MiB',
+  });
+}
+
+function bounded(value: unknown, label: string, maximum: number): string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > maximum) {
+    throw new Error(`Workflow ${label} must contain 1–${maximum} characters`);
+  }
+  return value;
+}
+
+function boundedAge(value: unknown): number {
+  const tenYears = 10 * 365 * 24 * 60 * 60 * 1_000;
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) > tenYears) {
+    throw new Error('Workflow maxAgeMs must be an integer between 0 and ten years');
+  }
+  return value as number;
+}
+
+function terminalStates(value: unknown): ExecutionState[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > TERMINAL_STATES.size) {
+    throw new Error('Workflow maintenance states must contain completed and/or failed');
+  }
+  const states = value.map((state) => {
+    if (!TERMINAL_STATES.has(state as ExecutionState)) {
+      throw new Error('Workflow maintenance accepts only terminal completed/failed states');
+    }
+    return state as ExecutionState;
+  });
+  return Array.from(new Set(states));
+}

package/agent/workflow/sqlite.ts

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { MissingDbError } from '../db';
+import type { WorkflowStoreKind } from './types';
+
+export interface WorkflowSchema {
+  table: string;
+  hasMeta: boolean;
+}
+
+const REQUIRED_COLUMNS = [
+  'id',
+  'workflow_name',
+  'state',
+  'input',
+  'steps',
+  'current_node_index',
+  'resolved_steps',
+  'signals',
+  'created_at',
+  'updated_at',
+];
+
+export function openWorkflowDatabase(path: string): Database {
+  if (!existsSync(path)) {
+    throw new MissingDbError(
+      `Database not found at "${path}" — configure the Workflow Engine dataPath and start it once.`
+    );
+  }
+  try {
+    return new Database(path, { readonly: true });
+  } catch (error) {
+    throw new Error(`Could not open workflow database: ${(error as Error).message}`);
+  }
+}
+
+export function workflowSchema(
+  db: Database,
+  kind: WorkflowStoreKind
+): WorkflowSchema | null {
+  const table = kind === 'archive' ? 'workflow_executions_archive' : 'workflow_executions';
+  if (!db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) {
+    return null;
+  }
+  const found = new Set(
+    (db.query(`PRAGMA table_info("${table}")`).all() as { name: string }[]).map((row) => row.name)
+  );
+  const missing = REQUIRED_COLUMNS.filter((name) => !found.has(name));
+  if (kind === 'archive' && !found.has('archived_at')) missing.push('archived_at');
+  if (missing.length > 0) throw new Error(`Invalid ${table} schema: missing ${missing.join(', ')}`);
+  return { table, hasMeta: found.has('meta') };
+}

package/agent/workflow/stats.ts

@@ -0,0 +1,79 @@
+import { openWorkflowDatabase, workflowSchema } from './sqlite';
+import {
+  WORKFLOW_LIMITS,
+  WORKFLOW_STATES,
+  type WorkflowExecutionState,
+  type WorkflowStats,
+} from './types';
+
+export function workflowStats(
+  path: string,
+  /** @internal Deterministic seam for the SQLite snapshot regression test. */
+  afterActiveTotals?: () => void
+): WorkflowStats {
+  const db = openWorkflowDatabase(path);
+  try {
+    const active = workflowSchema(db, 'active');
+    const archive = workflowSchema(db, 'archive');
+    const states = Object.fromEntries(WORKFLOW_STATES.map((state) => [state, 0])) as Record<
+      WorkflowExecutionState,
+      number
+    >;
+    if (!active) {
+      return { available: false, activeTotal: 0, archiveTotal: 0, states, workflowNames: [] };
+    }
+    const snapshot = db.transaction((): WorkflowStats => {
+      const stateColumns = WORKFLOW_STATES.map(
+        (state, index) => `SUM(CASE WHEN state = '${state}' THEN 1 ELSE 0 END) AS state_${index}`
+      ).join(', ');
+      const totals = db
+        .query(`SELECT COUNT(*) AS total, ${stateColumns} FROM workflow_executions`)
+        .get() as { total: number } & Record<`state_${number}`, number | null>;
+      for (const [index, state] of WORKFLOW_STATES.entries()) {
+        states[state] = totals[`state_${index}`] ?? 0;
+      }
+      if (Object.values(states).reduce((sum, count) => sum + count, 0) !== totals.total) {
+        throw new Error('Workflow store contains an unknown execution state');
+      }
+      afterActiveTotals?.();
+      const names = workflowNames(db, Boolean(archive));
+      const archiveTotal = archive
+        ? ((db.query('SELECT COUNT(*) AS count FROM workflow_executions_archive').get() as { count: number }).count ?? 0)
+        : 0;
+      return {
+        available: true,
+        activeTotal: totals.total,
+        archiveTotal,
+        states,
+        workflowNames: names,
+      };
+    });
+    return snapshot.deferred();
+  } finally {
+    db.close();
+  }
+}
+
+function workflowNames(db: import('bun:sqlite').Database, hasArchive: boolean): string[] {
+  const rows = db
+    .query(
+      hasArchive
+        ? `SELECT workflow_name FROM (
+             SELECT workflow_name FROM workflow_executions
+             UNION
+             SELECT workflow_name FROM workflow_executions_archive
+           ) ORDER BY workflow_name LIMIT 500`
+        : 'SELECT DISTINCT workflow_name FROM workflow_executions ORDER BY workflow_name LIMIT 500'
+    )
+    .all() as { workflow_name: unknown }[];
+  return rows.map((row) => {
+    if (
+      typeof row.workflow_name !== 'string' ||
+      row.workflow_name.length < 1 ||
+      row.workflow_name.length > WORKFLOW_LIMITS.filter
+    ) {
+      throw new Error('Workflow store contains an invalid workflow name');
+    }
+    return row.workflow_name;
+  });
+}

package/agent/workflow/types.ts

@@ -0,0 +1,81 @@
+export const WORKFLOW_STATES = [
+  'running',
+  'waiting',
+  'completed',
+  'failed',
+  'compensating',
+  'compensation-stuck',
+] as const;
+
+export type WorkflowExecutionState = (typeof WORKFLOW_STATES)[number];
+export type WorkflowStateFilter = WorkflowExecutionState | 'compensation';
+export type WorkflowStoreKind = 'active' | 'archive';
+
+export const WORKFLOW_LIMITS = {
+  page: 100,
+  offset: 1_000_000,
+  filter: 256,
+  detailBlob: 4 * 1024 * 1024,
+  metaBlob: 256 * 1024,
+  jsonNodes: 25_000,
+  jsonDepth: 40,
+  string: 250_000,
+} as const;
+
+export interface WorkflowRow {
+  id: string;
+  workflow_name: string;
+  state: string;
+  current_node_index: number;
+  created_at: number;
+  updated_at: number;
+  archived_at?: number | null;
+  meta?: Uint8Array | null;
+}
+
+export interface WorkflowExecutionSummary {
+  id: string;
+  workflowName: string;
+  state: WorkflowExecutionState;
+  currentNodeIndex: number;
+  createdAt: number;
+  updatedAt: number;
+  archivedAt?: number;
+  rollbackStatus?: string;
+  failureReason?: string;
+  parentExecutionId?: string;
+  definitionHash?: string;
+}
+
+export interface WorkflowExecutionDetail extends WorkflowExecutionSummary {
+  input: unknown;
+  steps: Record<string, unknown>;
+  resolvedSteps?: string[];
+  signals: Record<string, unknown>;
+  decisions?: Record<string, unknown>;
+  committedAt?: number;
+}
+
+export interface WorkflowStats {
+  available: boolean;
+  activeTotal: number;
+  archiveTotal: number;
+  states: Record<WorkflowExecutionState, number>;
+  workflowNames: string[];
+}
+
+export interface WorkflowListOptions {
+  kind?: WorkflowStoreKind;
+  workflowName?: string;
+  state?: WorkflowStateFilter;
+  limit?: number;
+  offset?: number;
+}
+
+export interface WorkflowPage {
+  available: boolean;
+  executions: WorkflowExecutionSummary[];
+  total: number;
+  limit: number;
+  offset: number;
+}

package/agent/workflow/validation.ts

@@ -0,0 +1,114 @@
+import { decodeWorkflowObject } from './codec';
+import {
+  WORKFLOW_LIMITS,
+  WORKFLOW_STATES,
+  type WorkflowExecutionState,
+  type WorkflowExecutionSummary,
+  type WorkflowRow,
+} from './types';
+
+const STEP_STATES = new Set(['pending', 'running', 'completed', 'failed']);
+const COMPENSATION_STATES = new Set([
+  'compensated',
+  'compensation-failed',
+  'compensation-skipped',
+]);
+
+export function validWorkflowState(value: string): value is WorkflowExecutionState {
+  return (WORKFLOW_STATES as readonly string[]).includes(value);
+}
+
+export function assertWorkflowRow(row: WorkflowRow): WorkflowExecutionSummary {
+  if (
+    typeof row.id !== 'string' ||
+    typeof row.workflow_name !== 'string' ||
+    row.workflow_name.length < 1 ||
+    row.workflow_name.length > WORKFLOW_LIMITS.filter ||
+    !validWorkflowState(row.state) ||
+    !Number.isSafeInteger(row.current_node_index) ||
+    !Number.isFinite(row.created_at) ||
+    !Number.isFinite(row.updated_at)
+  ) {
+    throw new Error('Workflow store contains an invalid execution row');
+  }
+  const meta = decodeWorkflowObject(row.meta, WORKFLOW_LIMITS.metaBlob, 'meta');
+  return {
+    id: row.id,
+    workflowName: row.workflow_name,
+    state: row.state,
+    currentNodeIndex: row.current_node_index,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    ...(typeof row.archived_at === 'number' ? { archivedAt: row.archived_at } : {}),
+    ...(typeof meta.rollbackStatus === 'string' ? { rollbackStatus: meta.rollbackStatus } : {}),
+    ...(typeof meta.failureReason === 'string' ? { failureReason: meta.failureReason } : {}),
+    ...(typeof meta.parentExecutionId === 'string' ? { parentExecutionId: meta.parentExecutionId } : {}),
+    ...(typeof meta.definitionHash === 'string' ? { definitionHash: meta.definitionHash } : {}),
+  };
+}
+
+export function assertWorkflowSteps(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Workflow steps must decode to an object');
+  }
+  for (const [name, candidate] of Object.entries(value)) {
+    if (!name || candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
+      throw new Error('Workflow store contains an invalid step record');
+    }
+    assertStep(candidate as Record<string, unknown>);
+  }
+  return value as Record<string, unknown>;
+}
+
+function assertStep(step: Record<string, unknown>): void {
+  if (
+    typeof step.status !== 'string' ||
+    !STEP_STATES.has(step.status) ||
+    invalidOptionalType(step, 'error', 'string') ||
+    invalidOptionalType(step, 'compensatable', 'boolean') ||
+    invalidOptionalType(step, 'idempotencyKey', 'string') ||
+    invalidOptionalType(step, 'childExecutionId', 'string') ||
+    !optionalFinite(step, 'startedAt') ||
+    !optionalFinite(step, 'completedAt') ||
+    !optionalInteger(step, 'attempts') ||
+    !optionalInteger(step, 'loopIndex') ||
+    !optionalInteger(step, 'occurrence')
+  ) {
+    throw new Error('Workflow store contains an invalid step record');
+  }
+  if (Object.hasOwn(step, 'compensation')) assertCompensation(step.compensation);
+}
+
+function assertCompensation(candidate: unknown): void {
+  if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error('Workflow store contains an invalid compensation record');
+  }
+  const compensation = candidate as Record<string, unknown>;
+  if (
+    typeof compensation.status !== 'string' ||
+    !COMPENSATION_STATES.has(compensation.status) ||
+    typeof compensation.at !== 'number' ||
+    !Number.isFinite(compensation.at) ||
+    invalidOptionalType(compensation, 'error', 'string')
+  ) {
+    throw new Error('Workflow store contains an invalid compensation record');
+  }
+}
+
+function invalidOptionalType(
+  record: Record<string, unknown>,
+  key: string,
+  type: 'string' | 'boolean'
+): boolean {
+  return Object.hasOwn(record, key) && typeof record[key] !== type;
+}
+
+function optionalFinite(record: Record<string, unknown>, key: string): boolean {
+  return !Object.hasOwn(record, key) ||
+    (typeof record[key] === 'number' && Number.isFinite(record[key]));
+}
+
+function optionalInteger(record: Record<string, unknown>, key: string): boolean {
+  return !Object.hasOwn(record, key) ||
+    (typeof record[key] === 'number' && Number.isSafeInteger(record[key]) && record[key] >= 0);
+}