bunqueue-dashboard 0.0.35 → 0.0.37

package/agent/queue/runtime.ts

@@ -0,0 +1,119 @@
+import { Queue, type QueueMetricType, type QueueMetrics } from 'bunqueue/client';
+import { managedAuthToken } from '../managedTarget';
+import type { ServerConfig } from '../manager';
+import type { QueueLimitSnapshot, QueueOperationsPort } from './types';
+import { QueueOperationsUnavailableError } from './types';
+
+export type QueueOperationsClient = Pick<
+  Queue,
+  | 'waitUntilReady'
+  | 'getGlobalRateLimit'
+  | 'getGlobalConcurrency'
+  | 'getRateLimitTtl'
+  | 'isMaxed'
+  | 'getDeduplicationJobId'
+  | 'removeDeduplicationKey'
+  | 'getMetrics'
+  | 'trimEvents'
+  | 'close'
+>;
+export type QueueOperationsClientFactory = (
+  config: ServerConfig,
+  queue: string
+) => QueueOperationsClient;
+
+/** Serializes operator reads and mutations and owns each dedicated TCP session. */
+export class QueueOperationsRuntime implements QueueOperationsPort {
+  private gate: Promise<void> = Promise.resolve();
+  private closed = false;
+
+  constructor(private readonly createClient: QueueOperationsClientFactory = defaultClient) {}
+
+  limits(config: ServerConfig, queue: string, maxJobs?: number): Promise<QueueLimitSnapshot> {
+    return this.withQueue(config, queue, async (client) => {
+      const [rateLimit, concurrency, rateLimitTtl, maxed] = await Promise.all([
+        client.getGlobalRateLimit(),
+        client.getGlobalConcurrency(),
+        client.getRateLimitTtl(maxJobs),
+        client.isMaxed(),
+      ]);
+      return { rateLimit, concurrency, rateLimitTtl, maxed };
+    });
+  }
+
+  deduplicationJobId(
+    config: ServerConfig,
+    queue: string,
+    deduplicationId: string
+  ): Promise<string | null> {
+    return this.withQueue(config, queue, (client) =>
+      client.getDeduplicationJobId(deduplicationId)
+    );
+  }
+
+  removeDeduplicationKey(
+    config: ServerConfig,
+    queue: string,
+    deduplicationId: string
+  ): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.removeDeduplicationKey(deduplicationId));
+  }
+
+  metrics(
+    config: ServerConfig,
+    queue: string,
+    type: QueueMetricType,
+    start: number,
+    end: number
+  ): Promise<QueueMetrics> {
+    return this.withQueue(config, queue, (client) => client.getMetrics(type, start, end));
+  }
+
+  trimEvents(config: ServerConfig, queue: string, maxLength: number): Promise<number> {
+    return this.withQueue(config, queue, (client) => client.trimEvents(maxLength));
+  }
+
+  async close(): Promise<void> {
+    this.closed = true;
+    await this.gate;
+  }
+
+  private withQueue<T>(
+    config: ServerConfig,
+    queue: string,
+    operation: (client: QueueOperationsClient) => Promise<T>
+  ): Promise<T> {
+    return this.serial(async () => {
+      const client = this.createClient(config, queue);
+      try {
+        await client.waitUntilReady();
+        return await operation(client);
+      } finally {
+        client.close();
+      }
+    });
+  }
+
+  private serial<T>(operation: () => Promise<T>): Promise<T> {
+    if (this.closed) {
+      return Promise.reject(new QueueOperationsUnavailableError('Queue operations runtime is closed'));
+    }
+    const result = this.gate.then(operation, operation);
+    this.gate = result.then(
+      () => undefined,
+      () => undefined
+    );
+    return result;
+  }
+}
+
+function connectionFor(config: ServerConfig) {
+  return { host: '127.0.0.1', port: config.tcpPort, token: managedAuthToken(config) };
+}
+
+function defaultClient(config: ServerConfig, queue: string): QueueOperationsClient {
+  return new Queue(queue, {
+    autoBatch: { enabled: false },
+    connection: { ...connectionFor(config), poolSize: 1 },
+  });
+}

package/agent/queue/types.ts

@@ -0,0 +1,34 @@
+import type { QueueMetricType, QueueMetrics } from 'bunqueue/client';
+import type { ServerConfig } from '../manager';
+
+export interface QueueLimitSnapshot {
+  rateLimit: { max: number; duration: number } | null;
+  concurrency: number | null;
+  rateLimitTtl: number;
+  maxed: boolean;
+}
+
+export interface QueueOperationsPort {
+  limits(config: ServerConfig, queue: string, maxJobs?: number): Promise<QueueLimitSnapshot>;
+  deduplicationJobId(
+    config: ServerConfig,
+    queue: string,
+    deduplicationId: string
+  ): Promise<string | null>;
+  removeDeduplicationKey(
+    config: ServerConfig,
+    queue: string,
+    deduplicationId: string
+  ): Promise<number>;
+  metrics(
+    config: ServerConfig,
+    queue: string,
+    type: QueueMetricType,
+    start: number,
+    end: number
+  ): Promise<QueueMetrics>;
+  trimEvents(config: ServerConfig, queue: string, maxLength: number): Promise<number>;
+  close(): Promise<void>;
+}
+
+export class QueueOperationsUnavailableError extends Error {}

package/agent/queue/validation.ts

@@ -0,0 +1,100 @@
+import { readLimitedJsonBody } from '../server/jsonBody';
+
+const MAX_BODY_BYTES = 8 * 1024;
+const MAX_PAGE_INDEX = 10_000;
+const MAX_EVENT_RETENTION = 1_000_000;
+
+export function exactQuery(url: string, allowed: readonly string[]): URLSearchParams {
+  const query = new URL(url).searchParams;
+  for (const key of query.keys()) {
+    if (!allowed.includes(key)) throw new Error(`Unknown Queue operation option: ${key}`);
+    if (query.getAll(key).length !== 1) {
+      throw new Error(`Duplicate Queue operation option: ${key}`);
+    }
+  }
+  return query;
+}
+
+export function validateQueueName(queue: string): string {
+  if (
+    !queue ||
+    queue === '.' ||
+    queue === '..' ||
+    queue.length > 256 ||
+    !/^[a-zA-Z0-9_\-.:]+$/.test(queue)
+  ) {
+    throw new Error('Queue name must contain 1-256 letters, numbers, underscores, dashes, dots or colons');
+  }
+  return queue;
+}
+
+export function requiredDeduplicationId(value: string | null): string {
+  if (!value || value.length > 1024) {
+    throw new Error('Deduplication ID must contain 1-1024 characters');
+  }
+  return value;
+}
+
+export function optionalMaxJobs(query: URLSearchParams): number | undefined {
+  const raw = query.get('maxJobs');
+  return raw === null ? undefined : boundedInteger(raw, 'maxJobs', 0, 1_000_000);
+}
+
+export function metricsRange(query: URLSearchParams): { start: number; end: number } {
+  const start = optionalInteger(query.get('start'), 'start', 0, MAX_PAGE_INDEX, 0);
+  const rawEnd = query.get('end');
+  const end = rawEnd === null ? -1 : boundedInteger(rawEnd, 'end', -1, MAX_PAGE_INDEX);
+  if (end !== -1 && end < start) throw new Error('Metrics end must be -1 or at least start');
+  return { start, end };
+}
+
+export function eventRetention(value: unknown): number {
+  return bodyInteger(value, 'maxLength', 0, MAX_EVENT_RETENTION);
+}
+
+export async function exactJsonBody(
+  request: Request,
+  allowed: readonly string[]
+): Promise<Record<string, unknown>> {
+  const value = await readLimitedJsonBody(request, {
+    scope: 'Queue operation',
+    maxBytes: MAX_BODY_BYTES,
+    limitLabel: '8 KiB',
+    missingMessage: 'Queue operation request must be valid JSON',
+    invalidJsonMessage: 'Queue operation request must be valid JSON',
+  });
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Queue operation request 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 Queue operation body field: ${unknown}`);
+  return body;
+}
+
+function optionalInteger(
+  value: string | null,
+  label: string,
+  minimum: number,
+  maximum: number,
+  fallback: number
+): number {
+  return value === null ? fallback : boundedInteger(value, label, minimum, maximum);
+}
+
+function boundedInteger(
+  raw: string,
+  label: string,
+  minimum: number,
+  maximum: number
+): number {
+  if (!/^-?\d+$/.test(raw)) throw new Error(`${label} must be an integer`);
+  return bodyInteger(Number(raw), label, minimum, maximum);
+}
+
+function bodyInteger(value: unknown, label: string, minimum: number, maximum: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new Error(`${label} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return value as number;
+}

package/agent/server/controlRoutes.ts

@@ -0,0 +1,185 @@
+import { type ProcessManager, validateConfigPatch } from '../manager';
+import { safeErrorMessage } from '../errorMessage';
+import {
+  WorkflowRuntimeUnavailableError,
+  type WorkflowRuntimePort,
+} from '../workflow/runtime';
+import { readLimitedJsonBody } from './jsonBody';
+import {
+  MANAGED_CONTROL_TARGET,
+  probeExternalHealth,
+  type ServerControlTarget,
+} from './controlTarget';
+import type { AgentLifecyclePort } from './lifecycle';
+import type { RouteResponse } from './types';
+
+const MAX_CONFIG_BODY_BYTES = 64 * 1024;
+
+async function statusWithHealth(manager: ProcessManager, controlTarget: ServerControlTarget) {
+  const snapshot = manager.getStatus();
+  if (controlTarget.mode === 'external') {
+    const health = await probeExternalHealth(controlTarget);
+    return {
+      ...snapshot,
+      managementMode: 'external' as const,
+      healthy: health.healthy,
+      version: health.version,
+      reachable: health.reachable,
+      externalUrl: controlTarget.url,
+      healthStatus: health.statusCode,
+      healthError: health.error,
+      db: null,
+    };
+  }
+  let healthy = false;
+  let version: string | undefined;
+  if (snapshot.status === 'running') {
+    const port = snapshot.runningConfig?.httpPort ?? snapshot.config.httpPort;
+    try {
+      const response = await fetch(`http://127.0.0.1:${port}/health`, {
+        signal: AbortSignal.timeout(1500),
+      });
+      if (response.ok) {
+        const body: unknown = await response.json();
+        if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+          const health = body as Record<string, unknown>;
+          healthy = health.ok === true;
+          if (typeof health.version === 'string') version = health.version;
+        }
+      }
+    } catch {
+      // The managed process is not healthy yet.
+    }
+  }
+  const database = await manager.dbStats().catch(() => null);
+  return { ...snapshot, managementMode: 'managed' as const, healthy, version, db: database };
+}
+
+export async function routeControlRequest(
+  request: Request,
+  pathname: string,
+  method: string,
+  manager: ProcessManager,
+  runtime: WorkflowRuntimePort,
+  lifecycle?: AgentLifecyclePort,
+  controlTarget: ServerControlTarget = MANAGED_CONTROL_TARGET
+): Promise<RouteResponse | null> {
+  if (pathname === '/control/status') {
+    return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+  }
+  if (pathname === '/control/logs') {
+    return { status: 200, body: { lines: manager.getLogs() } };
+  }
+  if (pathname === '/control/start' && method === 'POST') {
+    assertManagedControl(controlTarget);
+    return coordinated(lifecycle, async () => {
+      await manager.start();
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+    });
+  }
+  if (pathname === '/control/stop' && method === 'POST') {
+    assertManagedControl(controlTarget);
+    return coordinated(lifecycle, async () => {
+      await stopWithRuntimeCleanup(manager, runtime);
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+    });
+  }
+  if (pathname === '/control/restart' && method === 'POST') {
+    assertManagedControl(controlTarget);
+    return coordinated(lifecycle, async () => {
+      const closeResult = await settle(() => runtime.close());
+      if (!closeResult.ok) {
+        await stopAfterCloseFailure(manager, workflowCloseError(closeResult.error));
+      }
+      await manager.restart();
+      return { status: 200, body: await statusWithHealth(manager, controlTarget) };
+    });
+  }
+  if (pathname === '/control/config' && method === 'GET') {
+    return { status: 200, body: manager.getConfig() };
+  }
+  if (pathname === '/control/config' && method === 'PUT') {
+    assertManagedControl(controlTarget);
+    const patch = validateConfigPatch(
+      await readLimitedJsonBody(request, {
+        scope: 'Agent configuration',
+        maxBytes: MAX_CONFIG_BODY_BYTES,
+        limitLabel: '64 KiB',
+      })
+    );
+    return { status: 200, body: manager.setConfig(patch) };
+  }
+  return null;
+}
+
+export function assertManagedControl(controlTarget: ServerControlTarget): void {
+  if (controlTarget.mode === 'external') {
+    throw new Error(
+      'Server lifecycle is disabled in external mode (BUNQUEUE_MANAGED=0); manage this broker with its external supervisor'
+    );
+  }
+}
+
+async function stopWithRuntimeCleanup(
+  manager: ProcessManager,
+  runtime: WorkflowRuntimePort
+): Promise<void> {
+  const closeResult = await settle(() => runtime.close());
+  try {
+    await manager.stop();
+  } catch (stopFailure) {
+    if (!closeResult.ok) throw combinedShutdownError(closeResult.error, stopFailure);
+    throw stopFailure;
+  }
+  if (!closeResult.ok) throw workflowCloseError(closeResult.error);
+}
+
+async function stopAfterCloseFailure(
+  manager: ProcessManager,
+  closeFailure: unknown
+): Promise<never> {
+  try {
+    await manager.stop();
+  } catch (stopFailure) {
+    throw combinedShutdownError(closeFailure, stopFailure);
+  }
+  throw closeFailure;
+}
+
+function combinedShutdownError(closeFailure: unknown, stopFailure: unknown): Error {
+  return new WorkflowRuntimeUnavailableError(
+    `Workflow Engine shutdown failed (${message(closeFailure)}); ` +
+      `managed server stop also failed: ${message(stopFailure)}`
+  );
+}
+
+function workflowCloseError(error: unknown): WorkflowRuntimeUnavailableError {
+  try {
+    if (error instanceof WorkflowRuntimeUnavailableError) return error;
+  } catch {
+    // A hostile thrown Proxy must still become an unavailable-runtime error.
+  }
+  return new WorkflowRuntimeUnavailableError(`Workflow Engine shutdown failed: ${message(error)}`);
+}
+
+function message(error: unknown): string {
+  return safeErrorMessage(error);
+}
+
+function coordinated<T>(
+  lifecycle: AgentLifecyclePort | undefined,
+  operation: () => Promise<T>
+): Promise<T> {
+  return lifecycle ? lifecycle.run(operation) : operation();
+}
+
+type SettledOperation = { ok: true } | { ok: false; error: unknown };
+
+async function settle(operation: () => Promise<unknown>): Promise<SettledOperation> {
+  try {
+    await operation();
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}

package/agent/server/controlTarget.ts

@@ -0,0 +1,116 @@
+import { safeErrorMessage } from '../errorMessage';
+
+export type ServerManagementMode = 'managed' | 'external';
+
+export interface ServerControlTarget {
+  mode: ServerManagementMode;
+  /** Canonical external HTTP base; present only in attach-only mode. */
+  url?: string;
+  /** Server bearer used only by the agent-side health probe. */
+  token?: string;
+}
+
+export interface ExternalHealthProbe {
+  reachable: boolean;
+  healthy: boolean;
+  statusCode: number | null;
+  version?: string;
+  error?: string;
+}
+
+export const MANAGED_CONTROL_TARGET: ServerControlTarget = Object.freeze({ mode: 'managed' });
+
+/** Resolve the immutable lifecycle mode once, before the agent starts listening. */
+export function resolveServerControlTarget(
+  env: Record<string, string | undefined> = process.env
+): ServerControlTarget {
+  const configured = env.BUNQUEUE_MANAGED?.trim().toLowerCase();
+  if (!configured || ['1', 'true', 'yes', 'on'].includes(configured)) {
+    return MANAGED_CONTROL_TARGET;
+  }
+  if (!['0', 'false', 'no', 'off'].includes(configured)) {
+    throw new Error('BUNQUEUE_MANAGED must be 1/0, true/false, yes/no, or on/off');
+  }
+  return Object.freeze({
+    mode: 'external',
+    url: normalizeExternalUrl(env.BUNQUEUE_URL),
+    token: env.BUNQUEUE_TOKEN?.trim() || undefined,
+  });
+}
+
+function normalizeExternalUrl(value: string | undefined): string {
+  const candidate = value?.trim() || 'http://localhost:6790';
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new Error('BUNQUEUE_URL must be an absolute HTTP(S) URL in external mode');
+  }
+  if (
+    (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') ||
+    !parsed.hostname ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new Error(
+      'BUNQUEUE_URL must be a credential-free HTTP(S) URL without query or fragment in external mode'
+    );
+  }
+  const path = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.origin}${path}`;
+}
+
+/** Probe an externally supervised broker without following credential-bearing redirects. */
+export async function probeExternalHealth(target: ServerControlTarget): Promise<ExternalHealthProbe> {
+  if (target.mode !== 'external' || !target.url) {
+    throw new Error('External health probe requires an external server target');
+  }
+  let response: Response;
+  try {
+    response = await fetch(`${target.url}/health`, {
+      headers: target.token ? { Authorization: `Bearer ${target.token}` } : undefined,
+      redirect: 'error',
+      signal: AbortSignal.timeout(1500),
+    });
+  } catch (error) {
+    return {
+      reachable: false,
+      healthy: false,
+      statusCode: null,
+      error: safeErrorMessage(error),
+    };
+  }
+
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    return {
+      reachable: true,
+      healthy: false,
+      statusCode: response.status,
+      error: `Health endpoint returned non-JSON HTTP ${response.status}`,
+    };
+  }
+  const health = isRecord(body) ? body : {};
+  const healthy = response.ok && health.ok === true;
+  const version = typeof health.version === 'string' ? health.version : undefined;
+  const reportedStatus = typeof health.status === 'string' ? health.status : undefined;
+  return {
+    reachable: true,
+    healthy,
+    statusCode: response.status,
+    version,
+    error: healthy
+      ? undefined
+      : reportedStatus
+        ? `Health reported ${reportedStatus} (HTTP ${response.status})`
+        : `Health endpoint returned HTTP ${response.status}`,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}