bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/errorMessage.ts

@@ -0,0 +1,9 @@
+/** Convert any thrown JavaScript value without invoking a failure-prone boundary. */
+export function safeErrorMessage(error: unknown): string {
+  try {
+    const message = error instanceof Error ? error.message : String(error);
+    return typeof message === 'string' && message.length > 0 ? message : 'Unknown error';
+  } catch {
+    return 'Unprintable error';
+  }
+}

package/agent/flow/routes.ts

@@ -0,0 +1,251 @@
+import type { ServerConfig } from '../manager';
+import { assertManagedTarget, type ManagedTargetPolicy } from '../managedTarget';
+import type {
+  ManagedRuntimeAdmission,
+  ManagedRuntimeSnapshot,
+} from '../server/managedRuntime';
+import { assertNoFlowBody, readFlowJsonBody } from './validation';
+import {
+  createFlow,
+  inspectFlowJob,
+  mutateFlowJob,
+  readParentResults,
+  readFlow,
+  waitForFlowJob,
+} from './service';
+import type { FlowInspectOperation, FlowMutationOperation } from './types';
+
+export interface FlowOperationsPort {
+  create: typeof createFlow;
+  inspect: typeof inspectFlowJob;
+  mutate: typeof mutateFlowJob;
+  parentResults: typeof readParentResults;
+  read: typeof readFlow;
+  wait: typeof waitForFlowJob;
+}
+
+export interface FlowRouteDependencies {
+  admission?: ManagedRuntimeAdmission;
+  operations?: FlowOperationsPort;
+  targetPolicy?: ManagedTargetPolicy;
+}
+
+const DEFAULT_OPERATIONS: FlowOperationsPort = {
+  create: createFlow,
+  inspect: inspectFlowJob,
+  mutate: mutateFlowJob,
+  parentResults: readParentResults,
+  read: readFlow,
+  wait: waitForFlowJob,
+};
+
+export interface FlowRouteResponse {
+  status: number;
+  body: Record<string, unknown>;
+}
+
+const INSPECTIONS = new Set<FlowInspectOperation>([
+  'getState',
+  'isWaiting',
+  'isActive',
+  'isDelayed',
+  'isCompleted',
+  'isFailed',
+  'isWaitingChildren',
+  'toJSON',
+  'asJSON',
+  'getChildrenValues',
+  'getDependencies',
+  'getDependenciesCount',
+  'getFailedChildrenValues',
+  'getIgnoredChildrenFailures',
+]);
+const MUTATIONS = new Set<FlowMutationOperation>([
+  'removeChildDependency',
+  'removeUnprocessedChildren',
+  'updateData',
+  'updateProgress',
+  'log',
+  'changeDelay',
+  'changePriority',
+  'clearLogs',
+  'removeDeduplicationKey',
+  'retry',
+  'promote',
+  'remove',
+]);
+const MUTATIONS_WITH_BODY = new Set<FlowMutationOperation>([
+  'updateData',
+  'updateProgress',
+  'log',
+  'changeDelay',
+  'changePriority',
+  'clearLogs',
+]);
+
+export async function routeFlowRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  config: ServerConfig,
+  serverRunning = true,
+  dependencies: FlowRouteDependencies = {}
+): Promise<FlowRouteResponse | null> {
+  if (isFlowRoute(pathname, method) && !serverRunning) {
+    throw new Error('Start the managed Bunqueue server before Flow operations.');
+  }
+  if (pathname === '/flows/create' && method === 'POST') {
+    const query = exactQuery(request.url, ['target']);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
+    const body = await readFlowJsonBody(request);
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).create(current, body)
+      )
+    );
+  }
+  if (pathname === '/flows/tree' && method === 'GET') {
+    const query = exactQuery(request.url, ['id', 'queueName', 'depth', 'maxChildren', 'target']);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
+    const target = {
+      id: required(query, 'id'),
+      queueName: required(query, 'queueName'),
+      depth: optionalInteger(query, 'depth'),
+      maxChildren: optionalInteger(query, 'maxChildren'),
+    };
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).read(current, target)
+      )
+    );
+  }
+  if (pathname === '/flows/results' && method === 'POST') {
+    const query = exactQuery(request.url, ['target']);
+    assertManagedTarget(query, config, dependencies.targetPolicy);
+    const body = await readFlowJsonBody(request);
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).parentResults(current, body)
+      )
+    );
+  }
+  const match = pathname.match(/^\/flows\/jobs\/([^/]+)\/([^/]+)$/);
+  if (!match) return null;
+  const query = exactQuery(
+    request.url,
+    operationFromPath(pathname) === 'waitUntilFinished'
+      ? ['queueName', 'target', 'ttl']
+      : ['queueName', 'target']
+  );
+  assertManagedTarget(query, config, dependencies.targetPolicy);
+  const target = { id: decodeURIComponent(match[1]), queueName: required(query, 'queueName') };
+  const operation = match[2];
+  if (method === 'GET' && operation === 'waitUntilFinished') {
+    const ttl = requiredInteger(query, 'ttl', 1, 60_000);
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).wait(current, target, ttl)
+      )
+    );
+  }
+  if (method === 'GET' && INSPECTIONS.has(operation as FlowInspectOperation)) {
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).inspect(current, target, operation as FlowInspectOperation)
+      )
+    );
+  }
+  if (method === 'POST' && MUTATIONS.has(operation as FlowMutationOperation)) {
+    const mutation = operation as FlowMutationOperation;
+    const payload = MUTATIONS_WITH_BODY.has(mutation)
+      ? await readFlowJsonBody(request)
+      : (assertNoFlowBody(request), {});
+    return success(
+      await admitted(query, config, serverRunning, dependencies, ({ config: current }) =>
+        operations(dependencies).mutate(current, target, mutation, payload)
+      )
+    );
+  }
+  return { status: 404, body: { ok: false, error: 'Unknown flow operation' } };
+}
+
+function admitted<T>(
+  query: URLSearchParams,
+  config: ServerConfig,
+  running: boolean,
+  dependencies: FlowRouteDependencies,
+  operation: (snapshot: ManagedRuntimeSnapshot) => Promise<T>
+): Promise<T> {
+  const execute = async (snapshot: ManagedRuntimeSnapshot) => {
+    assertManagedTarget(query, snapshot.config, dependencies.targetPolicy);
+    assertRunning(snapshot.running);
+    return operation(snapshot);
+  };
+  return dependencies.admission
+    ? dependencies.admission(execute)
+    : execute({ config, running });
+}
+
+function operations(dependencies: FlowRouteDependencies): FlowOperationsPort {
+  return dependencies.operations ?? DEFAULT_OPERATIONS;
+}
+
+function assertRunning(running: boolean): void {
+  if (!running) throw new Error('Start the managed Bunqueue server before Flow operations.');
+}
+
+function isFlowRoute(pathname: string, method: string): boolean {
+  if (method === 'GET' && pathname === '/flows/tree') return true;
+  if (method === 'POST' && ['/flows/create', '/flows/results'].includes(pathname)) return true;
+  return (
+    (method === 'GET' || method === 'POST') &&
+    /^\/flows\/jobs\/[^/]+\/[^/]+$/.test(pathname)
+  );
+}
+
+function operationFromPath(pathname: string): string {
+  return pathname.slice(pathname.lastIndexOf('/') + 1);
+}
+
+function success(value: unknown): FlowRouteResponse {
+  return { status: 200, body: { ok: true, result: value } };
+}
+
+function exactQuery(url: string, allowed: string[]): URLSearchParams {
+  const query = new URL(url).searchParams;
+  for (const key of query.keys()) {
+    if (!allowed.includes(key)) throw new Error(`Unknown flow option: ${key}`);
+    if (query.getAll(key).length !== 1) throw new Error(`Duplicate flow option: ${key}`);
+  }
+  return query;
+}
+
+function required(query: URLSearchParams, key: string): string {
+  const value = query.get(key);
+  if (!value) throw new Error(`Flow ${key} is required`);
+  return value;
+}
+
+function optionalInteger(query: URLSearchParams, key: string): number | undefined {
+  const raw = query.get(key);
+  if (raw === null) return undefined;
+  if (!/^\d+$/.test(raw)) throw new Error(`Flow ${key} must be a non-negative integer`);
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value > 500) throw new Error(`Flow ${key} must be at most 500`);
+  return value;
+}
+
+function requiredInteger(
+  query: URLSearchParams,
+  key: string,
+  minimum: number,
+  maximum: number
+): number {
+  const raw = required(query, key);
+  if (!/^\d+$/.test(raw)) throw new Error(`Flow ${key} must be an integer`);
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(`Flow ${key} must be from ${minimum} to ${maximum}`);
+  }
+  return value;
+}

package/agent/flow/service.ts

@@ -0,0 +1,266 @@
+import {
+  FlowProducer,
+  TcpConnectionPool,
+  type FlowJob,
+  type FlowOpts,
+  type FlowStep,
+  type JobNode,
+} from 'bunqueue/client';
+import type { ServerConfig } from '../manager';
+import { managedAuthToken } from '../managedTarget';
+import {
+  asFlowRecord,
+  assertFlowBodySize,
+  assertExactFlowKeys,
+  normalizeFlowProgressPayload,
+  validateFlowTarget,
+  validateMutationPayload,
+  validateParentIds,
+} from './validation';
+import type { FlowInspectOperation, FlowJobTarget, FlowMutationOperation } from './types';
+
+type CreateOperation =
+  | { operation: 'add'; flow: FlowJob; options?: FlowOpts }
+  | { operation: 'addBulk'; flows: FlowJob[] }
+  | { operation: 'addChain'; steps: FlowStep[] }
+  | { operation: 'addBulkThen'; parallel: FlowStep[]; final: FlowStep }
+  | { operation: 'addTree'; root: FlowStep };
+
+type ParentResultRequest =
+  | { operation: 'getParentResult'; parentId: string }
+  | { operation: 'getParentResults'; parentIds: string[] };
+
+export async function createFlow(config: ServerConfig, input: unknown): Promise<unknown> {
+  assertFlowBodySize(input);
+  const request = createRequest(input);
+  const producer = producerFor(config);
+  try {
+    switch (request.operation) {
+      case 'add':
+        return { operation: request.operation, root: await serializeNode(await producer.add(request.flow, request.options)) };
+      case 'addBulk':
+        return { operation: request.operation, roots: await Promise.all((await producer.addBulk(request.flows)).map(serializeNode)) };
+      case 'addChain':
+        return { operation: request.operation, ...(await producer.addChain(request.steps)) };
+      case 'addBulkThen':
+        return { operation: request.operation, ...(await producer.addBulkThen(request.parallel, request.final)) };
+      case 'addTree':
+        return { operation: request.operation, ...(await producer.addTree(request.root)) };
+      default:
+        throw new Error('Unknown FlowProducer create operation');
+    }
+  } finally {
+    await producer.close();
+  }
+}
+
+export async function readFlow(
+  config: ServerConfig,
+  target: FlowJobTarget & { depth?: number; maxChildren?: number }
+): Promise<unknown> {
+  validateFlowTarget(target);
+  const producer = producerFor(config);
+  try {
+    const node = await producer.getFlow(target);
+    return node ? { flow: await serializeNode(node) } : { flow: null };
+  } finally {
+    await producer.close();
+  }
+}
+
+export async function readParentResults(config: ServerConfig, input: unknown): Promise<unknown> {
+  assertFlowBodySize(input);
+  const request = parentResultRequest(input);
+  const producer = producerFor(config);
+  try {
+    if (request.operation === 'getParentResult') {
+      const value = await producer.getParentResult(request.parentId);
+      return { operation: request.operation, parentId: request.parentId, value };
+    }
+    const values = await producer.getParentResults(request.parentIds);
+    return { operation: request.operation, entries: Array.from(values.entries()) };
+  } finally {
+    await producer.close();
+  }
+}
+
+export async function inspectFlowJob(
+  config: ServerConfig,
+  target: FlowJobTarget,
+  operation: FlowInspectOperation
+): Promise<unknown> {
+  const { producer, job } = await loadJob(config, target);
+  try {
+    switch (operation) {
+      case 'getState': return { state: await job.getState() };
+      case 'isWaiting': return { matches: await job.isWaiting() };
+      case 'isActive': return { matches: await job.isActive() };
+      case 'isDelayed': return { matches: await job.isDelayed() };
+      case 'isCompleted': return { matches: await job.isCompleted() };
+      case 'isFailed': return { matches: await job.isFailed() };
+      case 'isWaitingChildren': return { matches: await job.isWaitingChildren() };
+      case 'toJSON': return { job: job.toJSON() };
+      case 'asJSON': return { job: job.asJSON() };
+      case 'getChildrenValues': return { values: await job.getChildrenValues() };
+      case 'getDependencies': return { dependencies: await job.getDependencies() };
+      case 'getDependenciesCount': return { counts: await job.getDependenciesCount() };
+      case 'getFailedChildrenValues': return { values: await job.getFailedChildrenValues() };
+      case 'getIgnoredChildrenFailures': return { values: await job.getIgnoredChildrenFailures() };
+      default: throw new Error('Unknown flow inspection operation');
+    }
+  } finally {
+    await producer.close();
+  }
+}
+
+export async function mutateFlowJob(
+  config: ServerConfig,
+  target: FlowJobTarget,
+  operation: FlowMutationOperation,
+  input: unknown
+): Promise<unknown> {
+  assertFlowBodySize(input);
+  const payload = asFlowRecord(input);
+  validateMutationPayload(operation, payload);
+  const { producer, job } = await loadJob(config, target);
+  try {
+    switch (operation) {
+      case 'removeChildDependency': return { removed: await job.removeChildDependency() };
+      case 'removeUnprocessedChildren': await job.removeUnprocessedChildren(); break;
+      case 'updateData': await job.updateData(payload.data); break;
+      case 'updateProgress': await updateProgress(config, target, payload); break;
+      case 'log': await job.log(payload.message as string); break;
+      case 'changeDelay': await job.changeDelay(payload.delay as number); break;
+      case 'changePriority': await job.changePriority({ priority: payload.priority as number, ...(payload.lifo === undefined ? {} : { lifo: payload.lifo as boolean }) }); break;
+      case 'clearLogs': await job.clearLogs(payload.keepLogs as number | undefined); break;
+      case 'removeDeduplicationKey': return { removed: await job.removeDeduplicationKey() };
+      case 'retry': await job.retry(); break;
+      case 'promote': await job.promote(); break;
+      case 'remove': await job.remove(); break;
+      default: throw new Error('Unknown flow mutation operation');
+    }
+    return { applied: true };
+  } finally {
+    await producer.close();
+  }
+}
+
+export async function waitForFlowJob(
+  config: ServerConfig,
+  target: FlowJobTarget,
+  ttl: number
+): Promise<unknown> {
+  if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > 60_000) {
+    throw new Error('Flow wait TTL must be an integer from 1 to 60000 ms');
+  }
+  const { producer, job } = await loadJob(config, target, flowWaitTransportOptions(ttl));
+  try {
+    return { value: await job.waitUntilFinished(undefined, ttl) };
+  } finally {
+    await producer.close();
+  }
+}
+
+export function flowWaitTransportOptions(ttl: number) {
+  return { commandTimeout: ttl + 5_000, poolSize: 1 as const };
+}
+
+function producerFor(
+  config: ServerConfig,
+  overrides?: { commandTimeout: number; poolSize: 1 }
+): FlowProducer {
+  return new FlowProducer({ connection: { ...connectionFor(config), ...overrides } });
+}
+
+function connectionFor(config: ServerConfig) {
+  return { host: '127.0.0.1', port: config.tcpPort, token: managedAuthToken(config) };
+}
+
+async function loadJob(
+  config: ServerConfig,
+  target: FlowJobTarget,
+  connectionOverrides?: { commandTimeout: number; poolSize: 1 }
+) {
+  validateFlowTarget(target);
+  const producer = producerFor(config, connectionOverrides);
+  try {
+    const node = await producer.getFlow({ ...target, depth: 0, maxChildren: 0 });
+    if (!node) throw new Error(`Flow job ${target.id} was not found in queue ${target.queueName}`);
+    return { producer, job: node.job };
+  } catch (error) {
+    await producer.close();
+    throw error;
+  }
+}
+
+function createRequest(input: unknown): CreateOperation {
+  const request = asFlowRecord(input);
+  switch (request.operation) {
+    case 'add':
+      assertExactFlowKeys(request, ['operation', 'flow', 'options'], 'create');
+      break;
+    case 'addBulk':
+      assertExactFlowKeys(request, ['operation', 'flows'], 'create');
+      break;
+    case 'addChain':
+      assertExactFlowKeys(request, ['operation', 'steps'], 'create');
+      break;
+    case 'addBulkThen':
+      assertExactFlowKeys(request, ['operation', 'parallel', 'final'], 'create');
+      break;
+    case 'addTree':
+      assertExactFlowKeys(request, ['operation', 'root'], 'create');
+      break;
+    default:
+      throw new Error('Unknown FlowProducer create operation');
+  }
+  return request as unknown as CreateOperation;
+}
+
+function parentResultRequest(input: unknown): ParentResultRequest {
+  const request = asFlowRecord(input);
+  if (request.operation === 'getParentResult') {
+    assertExactFlowKeys(request, ['operation', 'parentId'], 'parent result');
+    validateParentIds([request.parentId]);
+  } else if (request.operation === 'getParentResults') {
+    assertExactFlowKeys(request, ['operation', 'parentIds'], 'parent result');
+    validateParentIds(request.parentIds);
+  } else {
+    throw new Error('Unknown FlowProducer parent result operation');
+  }
+  return request as unknown as ParentResultRequest;
+}
+
+async function updateProgress(
+  config: ServerConfig,
+  target: FlowJobTarget,
+  payload: Record<string, unknown>
+): Promise<void> {
+  const wire = normalizeFlowProgressPayload(payload);
+  const tcp = new TcpConnectionPool({ ...connectionFor(config), poolSize: 1 });
+  try {
+    const response = await tcp.send({
+      cmd: 'Progress',
+      id: target.id,
+      progress: wire.progress,
+      message: wire.message,
+    });
+    if (response.ok !== true) {
+      throw new Error(
+        typeof response.error === 'string' ? response.error : 'Flow updateProgress failed'
+      );
+    }
+  } finally {
+    tcp.close();
+  }
+}
+
+async function serializeNode(node: JobNode): Promise<unknown> {
+  return {
+    id: String(node.job.id),
+    name: node.job.name,
+    queueName: node.job.queueName,
+    state: await node.job.getState(),
+    children: node.children ? await Promise.all(node.children.map(serializeNode)) : [],
+  };
+}

package/agent/flow/types.ts

@@ -0,0 +1,34 @@
+export type FlowInspectOperation =
+  | 'getState'
+  | 'isWaiting'
+  | 'isActive'
+  | 'isDelayed'
+  | 'isCompleted'
+  | 'isFailed'
+  | 'isWaitingChildren'
+  | 'toJSON'
+  | 'asJSON'
+  | 'getChildrenValues'
+  | 'getDependencies'
+  | 'getDependenciesCount'
+  | 'getFailedChildrenValues'
+  | 'getIgnoredChildrenFailures';
+
+export type FlowMutationOperation =
+  | 'removeChildDependency'
+  | 'removeUnprocessedChildren'
+  | 'updateData'
+  | 'updateProgress'
+  | 'log'
+  | 'changeDelay'
+  | 'changePriority'
+  | 'clearLogs'
+  | 'removeDeduplicationKey'
+  | 'retry'
+  | 'promote'
+  | 'remove';
+
+export interface FlowJobTarget {
+  id: string;
+  queueName: string;
+}