bunqueue 2.8.60 → 2.9.2

package/dist/infrastructure/server/storageAdapter.js

@@ -0,0 +1,61 @@
+/** Immutable adapter registry: adding an engine does not change server bootstrap. */
+export class StorageAdapterRegistry {
+    adapters = new Map();
+    constructor(adapters) {
+        for (const adapter of adapters) {
+            if (this.adapters.has(adapter.driver)) {
+                throw new Error(`Duplicate storage adapter: ${adapter.driver}`);
+            }
+            this.adapters.set(adapter.driver, adapter);
+        }
+    }
+    resolve(driver) {
+        const adapter = this.adapters.get(driver);
+        if (!adapter)
+            throw new Error(`Unsupported storage driver: ${driver}`);
+        return adapter;
+    }
+    drivers() {
+        return [...this.adapters.keys()];
+    }
+}
+/** Lifecycle facade that remembers which strategy owns each created manager. */
+export class ServerStorageManager {
+    registry;
+    owners = new WeakMap();
+    shutdowns = new WeakMap();
+    constructor(registry) {
+        this.registry = registry;
+    }
+    startupError(config) {
+        return this.registry.resolve(config.storageDriver).startupError(config);
+    }
+    async create(config) {
+        const adapter = this.registry.resolve(config.storageDriver);
+        const manager = await adapter.create(config);
+        this.owners.set(manager, adapter);
+        return manager;
+    }
+    async shutdown(manager) {
+        const pending = this.shutdowns.get(manager);
+        if (pending) {
+            await pending;
+            return true;
+        }
+        const adapter = this.owners.get(manager);
+        if (!adapter)
+            return false;
+        const shutdown = adapter
+            .shutdown(manager)
+            .then(() => {
+            this.owners.delete(manager);
+        })
+            .finally(() => this.shutdowns.delete(manager));
+        this.shutdowns.set(manager, shutdown);
+        await shutdown;
+        return true;
+    }
+    display(config) {
+        return this.registry.resolve(config.storageDriver).display(config);
+    }
+}

package/dist/infrastructure/server/storageManager.d.ts

@@ -0,0 +1,12 @@
+import { QueueManager } from '../../application/queueManager';
+import type { ResolvedConfig } from '../../config';
+import { ServerStorageManager, StorageAdapterRegistry } from './storageAdapter';
+export declare const serverStorageAdapters: StorageAdapterRegistry;
+export declare const serverStorageManager: ServerStorageManager;
+export declare function storageStartupError(config: ResolvedConfig): string | null;
+export declare function backupStartupError(config: Pick<ResolvedConfig, 's3BackupEnabled' | 'dataPath'> & {
+    storageDriver?: ResolvedConfig['storageDriver'];
+}): string | null;
+export declare function createServerQueueManager(config: ResolvedConfig): Promise<QueueManager>;
+export declare function shutdownServerQueueManager(manager: QueueManager): Promise<void>;
+export declare function storageDisplay(config: ResolvedConfig): string;

package/dist/infrastructure/server/storageManager.js

@@ -0,0 +1,102 @@
+import { PostgresQueueManager } from '../../application/postgresQueueManager';
+import { QueueManager } from '../../application/queueManager';
+import { ServerStorageManager, StorageAdapterRegistry, } from './storageAdapter';
+function localAdapter(driver) {
+    return {
+        driver,
+        startupError: (config) => driver === 'sqlite' && !config.dataPath
+            ? 'SQLite storage requires storage.dataPath or BUNQUEUE_DATA_PATH.'
+            : null,
+        create: (config) => Promise.resolve(new QueueManager({
+            ...(driver === 'sqlite' && { dataPath: config.dataPath }),
+            maxPrometheusQueues: config.maxPrometheusQueues,
+        })),
+        shutdown: (manager) => {
+            manager.shutdown();
+            return Promise.resolve();
+        },
+        display: (config) => driver === 'sqlite' && config.dataPath
+            ? `SQLite · ${config.dataPath}`
+            : 'in-memory · ephemeral',
+    };
+}
+const postgresAdapter = {
+    driver: 'postgres',
+    startupError(config) {
+        if (!config.postgresUrl) {
+            return 'PostgreSQL storage requires storage.url or BUNQUEUE_POSTGRES_URL.';
+        }
+        if (config.dataPath) {
+            return 'PostgreSQL storage cannot be combined with SQLite dataPath configuration.';
+        }
+        return null;
+    },
+    async create(config) {
+        if (!config.postgresUrl)
+            throw new Error('PostgreSQL storage URL is missing');
+        const manager = new PostgresQueueManager({
+            maxPrometheusQueues: config.maxPrometheusQueues,
+            postgres: {
+                url: config.postgresUrl,
+                namespace: config.postgresNamespace,
+                poolSize: config.postgresPoolSize,
+                leaseDurationMs: config.postgresLeaseDurationMs,
+                pollIntervalMs: config.postgresPollIntervalMs,
+                statementTimeoutMs: config.postgresStatementTimeoutMs,
+                lockTimeoutMs: config.postgresLockTimeoutMs,
+                idleTransactionTimeoutMs: config.postgresIdleTransactionTimeoutMs,
+                maxConcurrentOperations: config.postgresMaxConcurrentOperations,
+                maxQueuedOperations: config.postgresMaxQueuedOperations,
+                maxSnapshotJobs: config.postgresMaxSnapshotJobs,
+                maxSnapshotPayloadBytes: config.postgresMaxSnapshotPayloadBytes,
+                ...(config.postgresBrokerId && { brokerId: config.postgresBrokerId }),
+            },
+        });
+        try {
+            await manager.waitUntilReady();
+            return manager;
+        }
+        catch (error) {
+            await manager.shutdownPostgres().catch(() => undefined);
+            throw error;
+        }
+    },
+    async shutdown(manager) {
+        if (!(manager instanceof PostgresQueueManager)) {
+            throw new Error('PostgreSQL adapter received an incompatible queue manager');
+        }
+        await manager.shutdownPostgres();
+    },
+    display: (config) => `PostgreSQL · namespace ${config.postgresNamespace}`,
+};
+export const serverStorageAdapters = new StorageAdapterRegistry([
+    localAdapter('memory'),
+    localAdapter('sqlite'),
+    postgresAdapter,
+]);
+export const serverStorageManager = new ServerStorageManager(serverStorageAdapters);
+export function storageStartupError(config) {
+    return serverStorageManager.startupError(config);
+}
+export function backupStartupError(config) {
+    const driver = config.storageDriver ?? (config.dataPath ? 'sqlite' : 'memory');
+    if (config.s3BackupEnabled && (driver !== 'sqlite' || !config.dataPath)) {
+        return ('S3 backup requires persistent SQLite storage. Set BUNQUEUE_DATA_PATH ' +
+            'or storage.dataPath before enabling S3_BACKUP_ENABLED.');
+    }
+    return null;
+}
+export async function createServerQueueManager(config) {
+    return await serverStorageManager.create(config);
+}
+export async function shutdownServerQueueManager(manager) {
+    if (await serverStorageManager.shutdown(manager))
+        return;
+    if (manager instanceof PostgresQueueManager)
+        await manager.shutdownPostgres();
+    else
+        manager.shutdown();
+}
+export function storageDisplay(config) {
+    return serverStorageManager.display(config);
+}

package/dist/infrastructure/server/tcp.js

@@ -2,6 +2,7 @@ import { tcpLog } from '../../shared/logger';
 import { decodeMessagePack } from '../../shared/msgpack';
 import { withSemaphore } from '../../shared/semaphore';
 import { handleCommand } from './handler';
+import { sanitizeServerError } from './errors';
 import { FrameSizeError } from './protocol';
 import { getRateLimiter } from './rateLimiter';
 import { TcpConnectionRegistry } from './tcp/connections';
@@ -69,9 +70,7 @@ export function createTcpServer(queueManager, config) {
                         registry.dropForWriteOverflow(socket);
                     }
                     catch (error) {
-                        const raw = error instanceof Error ? error.message : 'Unknown error';
-                        const message = raw.includes('SQLITE') || raw.includes('database') ? 'Internal server error' : raw;
-                        writeQueue.write(socket, tcpErrorResponse(message, command.reqId));
+                        writeQueue.write(socket, tcpErrorResponse(sanitizeServerError(error), command.reqId));
                         registry.dropForWriteOverflow(socket);
                     }
                 });

package/dist/infrastructure/server/ws/snapshots.d.ts

@@ -1,4 +1,4 @@
 import type { QueueManager } from '../../../application/queueManager';
-export declare function buildStatsSnapshot(queueManager: QueueManager): Record<string, unknown>;
+export declare function buildStatsSnapshot(queueManager: QueueManager): Record<string, unknown> | Promise<Record<string, unknown>>;
 export declare function buildHealthSnapshot(queueManager: QueueManager, connectionCount: number, connectionType?: 'ws' | 'sse'): Record<string, unknown>;
 export declare function buildStorageSnapshot(queueManager: QueueManager): Record<string, unknown>;

package/dist/infrastructure/server/ws/snapshots.js

@@ -1,9 +1,24 @@
 import { throughputTracker } from '../../../application/throughputTracker';
+import { isStorageDegraded } from '../../../shared/storageHealth';
+const WORKER_TIMEOUT_MS = parseInt(Bun.env.WORKER_TIMEOUT_MS ?? '30000', 10);
 export function buildStatsSnapshot(queueManager) {
+    const manager = queueManager;
+    if (manager.listWorkersDurable || manager.listCronsDurable) {
+        return Promise.all([
+            manager.listWorkersDurable
+                ? manager.listWorkersDurable()
+                : Promise.resolve(manager.workerManager.list()),
+            manager.listCronsDurable ? manager.listCronsDurable() : Promise.resolve(manager.listCrons()),
+        ]).then(([workers, crons]) => statsSnapshot(manager, workers, crons.length));
+    }
+    return statsSnapshot(manager, manager.workerManager.list(), manager.listCrons().length);
+}
+function statsSnapshot(queueManager, workers, cronJobs) {
     const stats = queueManager.getStats();
     const rates = throughputTracker.getRates();
     const perQueue = queueManager.getPerQueueStats();
-    const workerStats = queueManager.workerManager.getStats();
+    const now = Date.now();
+    const activeWorkers = workers.filter((worker) => now - worker.lastSeen < WORKER_TIMEOUT_MS);
     const queues = {};
     for (const [name, value] of perQueue) {
         queues[name] = {
@@ -27,15 +42,15 @@ export function buildStatsSnapshot(queueManager) {
         pullPerSec: rates.pullPerSec,
         uptime: stats.uptime,
         queues,
-        workers: { total: workerStats.total, active: workerStats.active },
-        cronJobs: queueManager.listCrons().length,
+        workers: { total: workers.length, active: activeWorkers.length },
+        cronJobs,
     };
 }
 export function buildHealthSnapshot(queueManager, connectionCount, connectionType = 'ws') {
     const memory = process.memoryUsage();
     const storage = queueManager.getStorageStatus();
     return {
-        ok: !storage.diskFull,
+        ok: !isStorageDegraded(storage),
         uptime: Math.floor(process.uptime()),
         memory: {
             rss: Math.round(memory.rss / 1024 / 1024),

package/dist/infrastructure/server/wsHandler.js

@@ -12,6 +12,7 @@
  * Legacy:      clients that never Subscribe get all events in old format
  */
 import { handleCommand } from './handler';
+import { sanitizeServerError } from './errors';
 import { parseCommand, serializeResponse, errorResponse } from './protocol';
 import { QueueCountsScheduler } from './queueCountsScheduler';
 import { matchesWsSubscription, MAX_WS_CLIENTS, textDecoder, WS_BACKPRESSURE_BYTES, WS_EVENT_MAP, } from './ws/constants';
@@ -61,7 +62,7 @@ export class WsHandler {
         });
         this.statsInterval ??= setInterval(() => {
             if (this.clients.size > 0)
-                this.broadcastStats(qm);
+                void this.broadcastStats(qm);
         }, 5000);
         this.healthInterval ??= setInterval(() => {
             if (this.clients.size > 0)
@@ -90,8 +91,13 @@ export class WsHandler {
         }
     }
     // ── Periodic broadcasts ──────────────────────────────────
-    broadcastStats(qm) {
-        this.emit('stats:snapshot', buildStatsSnapshot(qm));
+    async broadcastStats(qm) {
+        try {
+            this.emit('stats:snapshot', await buildStatsSnapshot(qm));
+        }
+        catch {
+            // A failed durable read must not be replaced by a stale local snapshot.
+        }
     }
     broadcastHealth(qm) {
         this.emit('health:status', buildHealthSnapshot(qm, this.clients.size));
@@ -199,8 +205,7 @@ export class WsHandler {
             ws.send(serializeResponse(response));
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : 'Unknown error';
-            ws.send(errorResponse(msg, cmd.reqId));
+            ws.send(errorResponse(sanitizeServerError(err), cmd.reqId));
         }
     }
     getClients() {

package/dist/main.js

@@ -30,7 +30,7 @@ async function startServer() {
     // Load config file (bunqueue.config.ts) if present, then merge with env vars
     const fileConfig = await loadConfigFile();
     const config = resolveServerConfig(fileConfig);
-    bootServer(fileConfig, config);
+    await bootServer(fileConfig, config);
 }
 // Logger env-var bootstrap only applies when this file is the entry point.
 // Imported consumers (e.g. user config files using `defineConfig`) must not

package/dist/mcp/backend/embedded/services.js

@@ -1,6 +1,7 @@
 import { jobId as toJobId } from '../../../domain/types/job';
 import { serializeMcpCron } from '../serializers';
 import { EmbeddedQueueBackend } from './queues';
+import { clientStorageStatus } from '../../../shared/storageHealth';
 export class EmbeddedServiceBackend extends EmbeddedQueueBackend {
     addCron(input) {
         return Promise.resolve(serializeMcpCron(this.manager.addCron(input)));
@@ -93,7 +94,7 @@ export class EmbeddedServiceBackend extends EmbeddedQueueBackend {
         return Promise.resolve(this.manager.getPrometheusMetrics());
     }
     getStorageStatus() {
-        const status = this.manager.getStorageStatus();
+        const status = clientStorageStatus(this.manager.getStorageStatus());
         return Promise.resolve({ diskFull: status.diskFull, error: status.error });
     }
     clearJobLogs(id, keepLogs) {

package/dist/mcp/index.d.ts

@@ -6,8 +6,8 @@
  * Uses the official @modelcontextprotocol/sdk for protocol compliance.
  *
  * Supports two connection modes:
- * - embedded (default): Direct SQLite access via QueueManager
- * - tcp: Connect to a remote bunqueue server
+ * - embedded (default): In-memory or direct SQLite access via QueueManager
+ * - tcp: Connect to a remote memory/SQLite or PostgreSQL-backed server
  *
  * @example Embedded mode (Claude Desktop):
  * ```json

package/dist/mcp/index.js

@@ -7,8 +7,8 @@
  * Uses the official @modelcontextprotocol/sdk for protocol compliance.
  *
  * Supports two connection modes:
- * - embedded (default): Direct SQLite access via QueueManager
- * - tcp: Connect to a remote bunqueue server
+ * - embedded (default): In-memory or direct SQLite access via QueueManager
+ * - tcp: Connect to a remote memory/SQLite or PostgreSQL-backed server
  *
  * @example Embedded mode (Claude Desktop):
  * ```json

package/dist/shared/storageHealth.d.ts

@@ -0,0 +1,9 @@
+export interface StorageHealthStatus {
+    readonly diskFull: boolean;
+    readonly error: string | null;
+    readonly since: number | null;
+}
+/** A storage error is degraded even when the underlying failure is not a full disk. */
+export declare function isStorageDegraded(status: StorageHealthStatus): boolean;
+/** Project internal health into a client-safe copy without mutating runtime diagnostics. */
+export declare function clientStorageStatus(status: StorageHealthStatus): StorageHealthStatus;

package/dist/shared/storageHealth.js

@@ -0,0 +1,12 @@
+/** A storage error is degraded even when the underlying failure is not a full disk. */
+export function isStorageDegraded(status) {
+    return status.diskFull || status.error !== null;
+}
+/** Project internal health into a client-safe copy without mutating runtime diagnostics. */
+export function clientStorageStatus(status) {
+    return {
+        diskFull: status.diskFull,
+        error: status.error === null || status.diskFull ? status.error : 'Internal server error',
+        since: status.since,
+    };
+}

package/package.json

@@ -1,14 +1,74 @@
 {
   "name": "bunqueue",
-  "version": "2.8.60",
-  "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
-  "type": "module",
-  "main": "dist/main.js",
-  "types": "dist/main.d.ts",
+  "version": "2.9.2",
+  "description": "High-performance job queue for Bun and AI agents. Memory or one-file SQLite, optional PostgreSQL 15–18 multi-broker persistence, cron, retries, DLQ, and MCP.",
+  "keywords": [
+    "agentic",
+    "ai",
+    "ai-agent",
+    "ai-native",
+    "automation",
+    "background-jobs",
+    "bullmq-alternative",
+    "bun",
+    "compensation",
+    "cron",
+    "dead-letter-queue",
+    "delayed-jobs",
+    "dlq",
+    "human-in-the-loop",
+    "inngest-alternative",
+    "job-queue",
+    "mcp",
+    "message-queue",
+    "model-context-protocol",
+    "multi-broker",
+    "multi-step",
+    "orchestration",
+    "postgresql",
+    "priority-queue",
+    "prometheus",
+    "queue",
+    "redis-alternative",
+    "retries",
+    "saga",
+    "saga-pattern",
+    "scheduler",
+    "sqlite",
+    "step-functions",
+    "task-queue",
+    "temporal-alternative",
+    "typescript",
+    "webhooks",
+    "worker",
+    "workflow",
+    "workflow-engine"
+  ],
+  "homepage": "https://bunqueue.dev",
+  "bugs": {
+    "url": "https://github.com/egeominotti/bunqueue/issues"
+  },
+  "license": "MIT",
+  "author": "egeominotti",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egeominotti/bunqueue.git"
+  },
   "bin": {
     "bunqueue": "./dist/cli/index.js",
     "bunqueue-mcp": "./dist/mcp/index.js"
   },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/bunqueue",
+    "!dist/benchmark",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
   "exports": {
     ".": {
       "types": "./dist/main.d.ts",
@@ -42,14 +102,6 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "!dist/bunqueue",
-    "!dist/benchmark",
-    "README.md",
-    "LICENSE"
-  ],
   "scripts": {
     "prepare": "git config core.hooksPath .husky",
     "dev": "bun run --watch src/main.ts",
@@ -58,15 +110,24 @@
     "build:lib": "tsc -p tsconfig.build.json",
     "docs:api": "bun run scripts/build-api-reference.ts",
     "check:docs-data": "bun run scripts/check-docs-data.ts",
-    "test": "BUNQUEUE_EMBEDDED=1 bun test",
+    "test": "BUNQUEUE_EMBEDDED=1 bun test --parallel=4",
     "test:core-e2e": "bun test test/core-e2e/core-public-api.e2e.test.ts",
     "test:model": "BUNQUEUE_EMBEDDED=1 bun test test/model-based/queue-model.test.ts test/model-based/workflow-model.test.ts test/model-based/flow-producer-model.test.ts test/model-based/backup-model.test.ts test/model-based/monitoring-model.test.ts test/model-based/enterprise-telemetry-model.test.ts",
+    "test:postgres": "bun scripts/test-postgres.ts",
+    "test:postgres:smoke": "bun scripts/test-postgres.ts --profile=smoke",
+    "test:postgres:destruction": "bun scripts/test-postgres.ts --profile=destruction",
+    "test:postgres:pressure": "BUNQUEUE_POSTGRES_TEN_BROKER_SOAK=1 bun scripts/test-postgres.ts --profile=pressure",
+    "test:postgres:battle": "BUNQUEUE_POSTGRES_TEN_BROKER_SOAK=1 BUNQUEUE_POSTGRES_FC_RUNS=100 bun scripts/test-postgres.ts --profile=battle",
+    "test:postgres:fast-check": "bun scripts/test-postgres.ts test/postgres-fast-check-*.test.ts",
+    "test:postgres:ten-broker": "BUNQUEUE_POSTGRES_TEN_BROKER_SOAK=1 bun scripts/test-postgres.ts test/postgres-ten-processes.test.ts",
     "test:sandbox": "bun run scripts/test-sandbox.ts",
     "test:sandbox:sdk": "bun run scripts/test-sdk-sandbox.ts",
     "bench": "bun run bench/comprehensive.ts",
     "bench:tcp": "bun run bench/tcp-bench.ts",
     "bench:autobatch": "bun run bench/local-autobatch.ts",
+    "bench:postgres:versions": "bun run bench/postgres-versions.ts",
     "bench:pushbulk": "bun run bench/pushbulk-delta.ts",
+    "bench:sqlite-lifecycle": "bun run bench/sqlite-lifecycle-batching.ts",
     "bench:workflow": "bun run bench/workflow-engine.ts",
     "bench:workflow:scale": "bun run bench/workflow-engine/scale.ts",
     "bench:joblist": "bun run bench/job-list-perf.ts",
@@ -81,7 +142,6 @@
     "prepublishOnly": "bun run build:lib"
   },
   "dependencies": {
-    "croner": "10.0.1",
     "msgpackr": "^1.11.8"
   },
   "devDependencies": {
@@ -113,56 +173,6 @@
       "optional": true
     }
   },
-  "keywords": [
-    "bun",
-    "job-queue",
-    "message-queue",
-    "task-queue",
-    "background-jobs",
-    "queue",
-    "worker",
-    "cron",
-    "scheduler",
-    "sqlite",
-    "redis-alternative",
-    "bullmq-alternative",
-    "priority-queue",
-    "delayed-jobs",
-    "retries",
-    "dead-letter-queue",
-    "dlq",
-    "webhooks",
-    "prometheus",
-    "typescript",
-    "ai",
-    "ai-agent",
-    "ai-native",
-    "mcp",
-    "model-context-protocol",
-    "agentic",
-    "automation",
-    "workflow",
-    "workflow-engine",
-    "orchestration",
-    "saga",
-    "saga-pattern",
-    "temporal-alternative",
-    "inngest-alternative",
-    "step-functions",
-    "multi-step",
-    "compensation",
-    "human-in-the-loop"
-  ],
-  "author": "egeominotti",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/egeominotti/bunqueue.git"
-  },
-  "bugs": {
-    "url": "https://github.com/egeominotti/bunqueue/issues"
-  },
-  "homepage": "https://bunqueue.dev",
   "engines": {
     "bun": ">=1.4.0"
   }