bunqueue-dashboard 0.0.34 → 0.0.36

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);
+}

package/agent/workflows.ts

@@ -0,0 +1,16 @@
+/**
+ * Read-only facade for Bunqueue 2.8.57 Workflow Engine observability.
+ * Persistence, decoding and validation live behind this stable public module.
+ */
+export { workflowExecution } from './workflow/detail';
+export { workflowExecutions } from './workflow/list';
+export { workflowStats } from './workflow/stats';
+export {
+  WORKFLOW_STATES,
+  type WorkflowExecutionDetail,
+  type WorkflowExecutionState,
+  type WorkflowExecutionSummary,
+  type WorkflowStateFilter,
+  type WorkflowStats,
+  type WorkflowStoreKind,
+} from './workflow/types';