bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/workflow/codec.ts

@@ -0,0 +1,78 @@
+import { Unpackr } from 'msgpackr';
+import { WORKFLOW_LIMITS } from './types';
+
+const unpackr = new Unpackr({ structuredClone: true });
+
+export function decodeWorkflowValue(
+  blob: Uint8Array | null | undefined,
+  cap: number,
+  label: string
+): unknown {
+  if (!blob) return null;
+  if (!(blob instanceof Uint8Array)) throw new Error(`Workflow ${label} is not a BLOB`);
+  if (blob.byteLength > cap) {
+    throw new Error(`Workflow ${label} exceeds the ${cap}-byte inspection limit`);
+  }
+  try {
+    return unpackr.unpack(blob);
+  } catch (error) {
+    throw new Error(`Could not decode workflow ${label}: ${(error as Error).message}`);
+  }
+}
+
+export function decodeWorkflowObject(
+  blob: Uint8Array | null | undefined,
+  cap: number,
+  label: string
+): Record<string, unknown> {
+  const value = decodeWorkflowValue(blob, cap, label);
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`Workflow ${label} must decode to an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+/** Convert decoded MessagePack extensions to a bounded, JSON-safe value. */
+export function jsonSafeWorkflowValue(value: unknown): unknown {
+  let nodes = 0;
+  const seen = new WeakSet<object>();
+  const visit = (entry: unknown, depth: number): unknown => {
+    nodes++;
+    if (nodes > WORKFLOW_LIMITS.jsonNodes) throw new Error('Workflow detail exceeds the inspection node limit');
+    if (depth > WORKFLOW_LIMITS.jsonDepth) throw new Error('Workflow detail exceeds the inspection depth limit');
+    if (entry == null || typeof entry === 'boolean' || typeof entry === 'number') return entry;
+    if (typeof entry === 'string') {
+      if (entry.length > WORKFLOW_LIMITS.string) throw new Error('Workflow detail contains an oversized string');
+      return entry;
+    }
+    if (typeof entry === 'bigint') return entry.toString();
+    if (typeof entry === 'undefined') return null;
+    if (typeof entry !== 'object') return String(entry);
+    if (seen.has(entry)) throw new Error('Workflow detail contains a cyclic value');
+    seen.add(entry);
+    try {
+      if (entry instanceof Date) return entry.toISOString();
+      if (entry instanceof Uint8Array) return `<binary ${entry.byteLength} B>`;
+      if (entry instanceof Map) return mapValue(entry, visit, depth);
+      if (entry instanceof Set) return [...entry].map((item) => visit(item, depth + 1));
+      if (Array.isArray(entry)) return entry.map((item) => visit(item, depth + 1));
+      const out = Object.create(null) as Record<string, unknown>;
+      for (const [key, item] of Object.entries(entry)) out[key] = visit(item, depth + 1);
+      return out;
+    } finally {
+      seen.delete(entry);
+    }
+  };
+  return visit(value, 0);
+}
+
+function mapValue(
+  map: Map<unknown, unknown>,
+  visit: (entry: unknown, depth: number) => unknown,
+  depth: number
+): Record<string, unknown> {
+  const out = Object.create(null) as Record<string, unknown>;
+  for (const [key, item] of map) out[String(key)] = visit(item, depth + 1);
+  return out;
+}

package/agent/workflow/detail.ts

@@ -0,0 +1,63 @@
+import { decodeWorkflowObject, decodeWorkflowValue, jsonSafeWorkflowValue } from './codec';
+import { openWorkflowDatabase, workflowSchema } from './sqlite';
+import {
+  WORKFLOW_LIMITS,
+  type WorkflowExecutionDetail,
+  type WorkflowRow,
+  type WorkflowStoreKind,
+} from './types';
+import { assertWorkflowRow, assertWorkflowSteps } from './validation';
+
+interface WorkflowDetailRow extends WorkflowRow {
+  input: Uint8Array | null;
+  steps: Uint8Array | null;
+  resolved_steps: Uint8Array | null;
+  signals: Uint8Array | null;
+}
+
+export function workflowExecution(
+  path: string,
+  id: string,
+  kind: WorkflowStoreKind = 'active'
+): WorkflowExecutionDetail | null {
+  if (!id || id.length > 1024) throw new Error('Workflow execution id must contain 1–1024 characters');
+  const db = openWorkflowDatabase(path);
+  try {
+    const info = workflowSchema(db, kind);
+    if (!info) return null;
+    const row = db.query(`SELECT * FROM ${info.table} WHERE id = ?`).get(id) as WorkflowDetailRow | null;
+    if (!row) return null;
+    const summary = assertWorkflowRow(row);
+    const input = safeDecode(row.input, 'input');
+    const steps = assertWorkflowSteps(safeObject(row.steps, 'steps'));
+    const resolved = safeDecode(row.resolved_steps, 'resolved steps');
+    const signals = safeObject(row.signals, 'signals');
+    const meta = decodeWorkflowObject(row.meta, WORKFLOW_LIMITS.metaBlob, 'meta');
+    if (resolved != null && (!Array.isArray(resolved) || resolved.some((item) => typeof item !== 'string'))) {
+      throw new Error('Workflow resolved steps must decode to a string array');
+    }
+    return {
+      ...summary,
+      input,
+      steps,
+      ...(resolved ? { resolvedSteps: resolved as string[] } : {}),
+      signals,
+      ...(meta.decisions && typeof meta.decisions === 'object'
+        ? { decisions: jsonSafeWorkflowValue(meta.decisions) as Record<string, unknown> }
+        : {}),
+      ...(typeof meta.committedAt === 'number' ? { committedAt: meta.committedAt } : {}),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function safeDecode(blob: Uint8Array | null, label: string): unknown {
+  return jsonSafeWorkflowValue(decodeWorkflowValue(blob, WORKFLOW_LIMITS.detailBlob, label));
+}
+
+function safeObject(blob: Uint8Array | null, label: string): Record<string, unknown> {
+  return jsonSafeWorkflowValue(
+    decodeWorkflowObject(blob, WORKFLOW_LIMITS.detailBlob, label)
+  ) as Record<string, unknown>;
+}

package/agent/workflow/list.ts

@@ -0,0 +1,87 @@
+import { openWorkflowDatabase, workflowSchema } from './sqlite';
+import {
+  WORKFLOW_LIMITS,
+  type WorkflowListOptions,
+  type WorkflowPage,
+  type WorkflowRow,
+} from './types';
+import { assertWorkflowRow, validWorkflowState } from './validation';
+
+export function workflowExecutions(
+  path: string,
+  options: WorkflowListOptions = {},
+  /** @internal Deterministic seam for the SQLite snapshot regression test. */
+  afterRowsRead?: () => void
+): WorkflowPage {
+  const kind = options.kind ?? 'active';
+  const limit = options.limit ?? 50;
+  const offset = options.offset ?? 0;
+  validateListOptions(options, limit, offset);
+  const db = openWorkflowDatabase(path);
+  try {
+    const info = workflowSchema(db, kind);
+    if (!info) return { available: false, executions: [], total: 0, limit, offset };
+    const { predicate, bindings } = listPredicate(options);
+    const archiveColumn = kind === 'archive' ? ', archived_at' : '';
+    const metaColumn = info.hasMeta ? ', meta' : '';
+    db.run('BEGIN');
+    let transactionOpen = true;
+    try {
+      const rows = db
+        .query(
+          `SELECT id, workflow_name, state, current_node_index, created_at, updated_at${archiveColumn}${metaColumn}
+           FROM ${info.table}${predicate} ORDER BY created_at DESC, id DESC LIMIT ? OFFSET ?`
+        )
+        .all(...bindings, limit, offset) as WorkflowRow[];
+      afterRowsRead?.();
+      const count = db.query(`SELECT COUNT(*) AS count FROM ${info.table}${predicate}`).get(...bindings) as { count: number };
+      const executions = rows.map(assertWorkflowRow);
+      db.run('COMMIT');
+      transactionOpen = false;
+      return { available: true, executions, total: count.count, limit, offset };
+    } finally {
+      if (transactionOpen) rollbackQuietly(db);
+    }
+  } finally {
+    db.close();
+  }
+}
+
+function validateListOptions(options: WorkflowListOptions, limit: number, offset: number): void {
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > WORKFLOW_LIMITS.page) {
+    throw new Error(`Workflow limit must be an integer between 1 and ${WORKFLOW_LIMITS.page}`);
+  }
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > WORKFLOW_LIMITS.offset) {
+    throw new Error(`Workflow offset must be an integer between 0 and ${WORKFLOW_LIMITS.offset}`);
+  }
+  if (options.workflowName !== undefined && (!options.workflowName || options.workflowName.length > WORKFLOW_LIMITS.filter)) {
+    throw new Error(`Workflow name must contain 1–${WORKFLOW_LIMITS.filter} characters`);
+  }
+  if (options.state !== undefined && options.state !== 'compensation' && !validWorkflowState(options.state)) {
+    throw new Error('Unknown workflow execution state');
+  }
+}
+
+function listPredicate(options: WorkflowListOptions): { predicate: string; bindings: string[] } {
+  const where: string[] = [];
+  const bindings: string[] = [];
+  if (options.workflowName) {
+    where.push('workflow_name = ?');
+    bindings.push(options.workflowName);
+  }
+  if (options.state === 'compensation') {
+    where.push("state IN ('compensating', 'compensation-stuck')");
+  } else if (options.state) {
+    where.push('state = ?');
+    bindings.push(options.state);
+  }
+  return { predicate: where.length ? ` WHERE ${where.join(' AND ')}` : '', bindings };
+}
+
+function rollbackQuietly(db: import('bun:sqlite').Database): void {
+  try {
+    db.run('ROLLBACK');
+  } catch {
+    // Preserve the original query or decoding error if SQLite already closed the transaction.
+  }
+}

package/agent/workflow/runtime.ts

@@ -0,0 +1,274 @@
+import { realpath, stat } from 'node:fs/promises';
+import { basename, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import {
+  Engine,
+  type EngineOptions,
+  type ExecutionState,
+  type Workflow,
+} from 'bunqueue/workflow';
+import { managedAuthToken } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import {
+  configuredWorkflowModule,
+  messageOf,
+  readyRuntimeStatus,
+  stoppedRuntimeStatus,
+  WorkflowRuntimeUnavailableError,
+  workflowRuntimeOptions,
+  workflowRuntimeSignature,
+} from './runtimeConfig';
+
+export { WorkflowRuntimeUnavailableError } from './runtimeConfig';
+
+export interface WorkflowRuntimeStatus {
+  configured: boolean;
+  ready: boolean;
+  moduleName?: string;
+  workflowNames: string[];
+  queueName?: string;
+  concurrency?: number;
+  error?: string;
+}
+
+export interface WorkflowRuntimePort {
+  status(config: ServerConfig, activate?: boolean): Promise<WorkflowRuntimeStatus>;
+  reload(config: ServerConfig): Promise<WorkflowRuntimeStatus>;
+  start(config: ServerConfig, workflowName: string, input?: unknown): Promise<unknown>;
+  signal(config: ServerConfig, id: string, event: string, payload?: unknown): Promise<void>;
+  recover(config: ServerConfig): Promise<unknown>;
+  resumeCompensation(config: ServerConfig, id: string): Promise<void>;
+  abandonCompensation(config: ServerConfig, id: string): Promise<void>;
+  archive(config: ServerConfig, maxAgeMs: number, states: ExecutionState[]): Promise<number>;
+  cleanup(config: ServerConfig, maxAgeMs: number, states: ExecutionState[]): Promise<number>;
+  close(): Promise<void>;
+}
+
+interface ActiveRuntime {
+  engine: Engine;
+  signature: string;
+  moduleName: string;
+  workflowNames: string[];
+  queueName: string;
+  concurrency: number;
+  initializationFailure?: string;
+  closeFailure?: string;
+}
+
+interface RuntimeModule {
+  workflows?: Workflow[];
+  workflowNames?: string[];
+  registerWorkflowRuntime?: (engine: Engine) => unknown | Promise<unknown>;
+  default?: (engine: Engine) => unknown | Promise<unknown>;
+}
+
+export type WorkflowEngineFactory = (options: EngineOptions) => Engine;
+
+export class WorkflowRuntime implements WorkflowRuntimePort {
+  private active: ActiveRuntime | null = null;
+  private gate: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly createEngine: WorkflowEngineFactory = (options) => new Engine(options)
+  ) {}
+
+  status(config: ServerConfig, activate = true): Promise<WorkflowRuntimeStatus> {
+    return this.serial(async () => {
+      const modulePath = configuredWorkflowModule(config);
+      try {
+        if (!modulePath) {
+          await this.closeActive();
+          return { configured: false, ready: false, workflowNames: [] };
+        }
+        if (!activate) {
+          await this.closeActive();
+          return stoppedRuntimeStatus(config, modulePath);
+        }
+        const active = await this.ensure(config);
+        return readyRuntimeStatus(active);
+      } catch (error) {
+        const active = this.active;
+        return {
+          configured: Boolean(modulePath),
+          ready: false,
+          moduleName: modulePath ? basename(modulePath) : active?.moduleName,
+          workflowNames: [],
+          queueName: active?.queueName,
+          concurrency: active?.concurrency,
+          error: messageOf(error),
+        };
+      }
+    });
+  }
+
+  reload(config: ServerConfig): Promise<WorkflowRuntimeStatus> {
+    return this.serial(async () => {
+      await this.closeActive();
+      return readyRuntimeStatus(await this.ensure(config));
+    });
+  }
+
+  start(config: ServerConfig, workflowName: string, input?: unknown): Promise<unknown> {
+    return this.run(config, (engine) => engine.start(workflowName, input));
+  }
+
+  signal(config: ServerConfig, id: string, event: string, payload?: unknown): Promise<void> {
+    return this.run(config, (engine) => engine.signal(id, event, payload));
+  }
+
+  recover(config: ServerConfig): Promise<unknown> {
+    return this.run(config, (engine) => engine.recover());
+  }
+
+  resumeCompensation(config: ServerConfig, id: string): Promise<void> {
+    return this.run(config, (engine) => engine.resumeCompensation(id));
+  }
+
+  abandonCompensation(config: ServerConfig, id: string): Promise<void> {
+    return this.run(config, (engine) => engine.abandonCompensation(id));
+  }
+
+  archive(
+    config: ServerConfig,
+    maxAgeMs: number,
+    states: ExecutionState[]
+  ): Promise<number> {
+    return this.run(config, (engine) => engine.archive(maxAgeMs, states));
+  }
+
+  cleanup(
+    config: ServerConfig,
+    maxAgeMs: number,
+    states: ExecutionState[]
+  ): Promise<number> {
+    return this.run(config, (engine) => engine.cleanup(maxAgeMs, states));
+  }
+
+  close(): Promise<void> {
+    return this.serial(() => this.closeActive());
+  }
+
+  private run<T>(config: ServerConfig, operation: (engine: Engine) => Promise<T> | T): Promise<T> {
+    return this.serial(async () => operation((await this.ensure(config)).engine));
+  }
+
+  private async ensure(config: ServerConfig): Promise<ActiveRuntime> {
+    if (this.active?.closeFailure !== undefined) {
+      throw quarantinedRuntimeError(this.active);
+    }
+    const requested = configuredWorkflowModule(config);
+    if (!requested) {
+      throw new WorkflowRuntimeUnavailableError(
+        'Set BUNQUEUE_WORKFLOW_MODULE in Server extraEnv to an absolute runtime module path.'
+      );
+    }
+    if (!isAbsolute(requested)) {
+      throw new WorkflowRuntimeUnavailableError('BUNQUEUE_WORKFLOW_MODULE must be absolute.');
+    }
+    const path = await realpath(requested).catch(() => {
+      throw new WorkflowRuntimeUnavailableError(
+        'The configured workflow runtime module was not found.'
+      );
+    });
+    const modified = (await stat(path)).mtimeMs;
+    const options = workflowRuntimeOptions(config);
+    const signature = workflowRuntimeSignature(config, path, modified, options);
+    if (this.active?.signature === signature) return this.active;
+
+    await this.closeActive();
+    const imported = (await import(`${pathToFileURL(path).href}?v=${modified}`)) as RuntimeModule;
+    const definitions = Array.isArray(imported.workflows) ? imported.workflows : [];
+    const register = imported.registerWorkflowRuntime ?? imported.default;
+    if (!register && definitions.length === 0) {
+      throw new WorkflowRuntimeUnavailableError(
+        'Workflow module must export workflows[] or registerWorkflowRuntime(engine).'
+      );
+    }
+    const engine = this.createEngine({
+      dataPath: config.dataPath,
+      queueName: options.queueName,
+      concurrency: options.concurrency,
+      connection: {
+        host: '127.0.0.1',
+        port: config.tcpPort,
+        token: managedAuthToken(config),
+      },
+    });
+    const active: ActiveRuntime = {
+      engine,
+      signature,
+      moduleName: basename(path),
+      workflowNames: [],
+      ...options,
+    };
+    this.active = active;
+    try {
+      const names = new Set<string>();
+      const originalRegister = engine.register.bind(engine);
+      engine.register = ((workflow: Workflow) => {
+        const registered = originalRegister(workflow);
+        names.add(workflowName(workflow.name));
+        return registered;
+      }) as Engine['register'];
+      try {
+        for (const workflow of definitions) engine.register(workflow);
+        if (register) await register(engine);
+      } finally {
+        engine.register = originalRegister as Engine['register'];
+      }
+      if (imported.workflowNames !== undefined && !Array.isArray(imported.workflowNames)) {
+        throw new WorkflowRuntimeUnavailableError('workflowNames must be an array of strings.');
+      }
+      for (const name of imported.workflowNames ?? []) names.add(workflowName(name));
+      active.workflowNames = Array.from(names).sort();
+      return active;
+    } catch (error) {
+      try {
+        active.initializationFailure ??= messageOf(error);
+      } finally {
+        await this.closeActive();
+      }
+      throw error;
+    }
+  }
+
+  private async closeActive(): Promise<void> {
+    const previous = this.active;
+    if (!previous) return;
+    try {
+      await previous.engine.close(true);
+    } catch (error) {
+      previous.closeFailure ??= messageOf(error);
+      throw quarantinedRuntimeError(previous);
+    }
+    if (this.active === previous) this.active = null;
+  }
+
+  private serial<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.gate.then(operation, operation);
+    this.gate = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+function quarantinedRuntimeError(active: ActiveRuntime): WorkflowRuntimeUnavailableError {
+  const initialization = active.initializationFailure !== undefined
+    ? ` Initialization failed: ${active.initializationFailure}.`
+    : '';
+  return new WorkflowRuntimeUnavailableError(
+    `Workflow Engine is quarantined.${initialization} Shutdown failed: ${active.closeFailure}. ` +
+      'Restart the control agent before running or reloading workflows.'
+  );
+}
+
+function workflowName(value: unknown): string {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+    throw new WorkflowRuntimeUnavailableError(
+      'workflowNames must contain strings between 1 and 256 characters.'
+    );
+  }
+  return value;
+}

package/agent/workflow/runtimeConfig.ts

@@ -0,0 +1,103 @@
+import { basename } from 'node:path';
+import { safeErrorMessage } from '../errorMessage';
+import { managedAuthToken } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import type { WorkflowRuntimeStatus } from './runtime';
+
+export class WorkflowRuntimeUnavailableError extends Error {}
+
+export interface WorkflowRuntimeOptions {
+  queueName: string;
+  concurrency: number;
+}
+
+export interface RuntimeStatusSource extends WorkflowRuntimeOptions {
+  moduleName: string;
+  workflowNames: string[];
+}
+
+export function configuredWorkflowModule(config: ServerConfig): string | undefined {
+  return effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_MODULE')?.trim() || undefined;
+}
+
+export function workflowRuntimeOptions(config: ServerConfig): WorkflowRuntimeOptions {
+  const queueName = effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_QUEUE_NAME')?.trim() || '__wf:steps';
+  if (queueName.length > 256 || /[\u0000-\u001f\u007f]/.test(queueName)) {
+    throw new WorkflowRuntimeUnavailableError(
+      'BUNQUEUE_WORKFLOW_QUEUE_NAME must contain 1–256 printable characters.'
+    );
+  }
+  const rawConcurrency = effectiveEnvironment(config, 'BUNQUEUE_WORKFLOW_CONCURRENCY')?.trim();
+  const concurrency = rawConcurrency ? Number(rawConcurrency) : 5;
+  if (
+    (rawConcurrency !== undefined && !/^\d+$/.test(rawConcurrency)) ||
+    !Number.isSafeInteger(concurrency) ||
+    concurrency < 1 ||
+    concurrency > 1_000
+  ) {
+    throw new WorkflowRuntimeUnavailableError(
+      'BUNQUEUE_WORKFLOW_CONCURRENCY must be an integer between 1 and 1000.'
+    );
+  }
+  return { queueName, concurrency };
+}
+
+export function workflowRuntimeSignature(
+  config: ServerConfig,
+  path: string,
+  modified: number,
+  options: WorkflowRuntimeOptions
+): string {
+  return JSON.stringify([
+    path,
+    modified,
+    config.dataPath,
+    config.tcpPort,
+    managedAuthToken(config),
+    options.queueName,
+    options.concurrency,
+  ]);
+}
+
+export function stoppedRuntimeStatus(
+  config: ServerConfig,
+  modulePath: string
+): WorkflowRuntimeStatus {
+  try {
+    return {
+      configured: true,
+      ready: false,
+      moduleName: basename(modulePath),
+      workflowNames: [],
+      ...workflowRuntimeOptions(config),
+      error: 'Managed Bunqueue server is stopped.',
+    };
+  } catch (error) {
+    return {
+      configured: true,
+      ready: false,
+      moduleName: basename(modulePath),
+      workflowNames: [],
+      error: messageOf(error),
+    };
+  }
+}
+
+export function readyRuntimeStatus(active: RuntimeStatusSource): WorkflowRuntimeStatus {
+  return {
+    configured: true,
+    ready: true,
+    moduleName: active.moduleName,
+    workflowNames: active.workflowNames,
+    queueName: active.queueName,
+    concurrency: active.concurrency,
+  };
+}
+
+export function messageOf(error: unknown): string {
+  return safeErrorMessage(error);
+}
+
+function effectiveEnvironment(config: ServerConfig, key: string): string | undefined {
+  return Object.hasOwn(config.extraEnv, key) ? config.extraEnv[key] : process.env[key];
+}