bunqueue 2.8.60 → 2.9.0

package/dist/application/postgres-queue-manager/state.js

@@ -0,0 +1,273 @@
+import { PostgresQueueStore, } from '../../infrastructure/persistence/postgres';
+import { QueueManager } from '../queueManager';
+import { stopBackgroundTasks } from '../backgroundTasks';
+import { PostgresDeferredWriteQueue, throwDeferredWriteErrors } from './deferredWrites';
+import { applyPostgresEventMetrics, hydratePostgresLifetimeMetrics, postgresEventType, } from './lifetimeMetrics';
+import { PostgresQueueSnapshot } from './snapshot';
+import { PostgresStartupEventBuffer } from './startupEventBuffer';
+import { PostgresOperationGate } from './operationGate';
+import { applyPostgresJobProjection, PostgresProjectionRefreshes } from './projectionRefreshes';
+export class PostgresQueueManagerState extends QueueManager {
+    postgresStore;
+    postgresSnapshot;
+    activeTokens = new Map();
+    postgresReady;
+    refreshes = new Map();
+    dirtyQueues = new Set();
+    queueEventVersions = new Map();
+    snapshotEventBuffer = new PostgresStartupEventBuffer();
+    terminalMetricBaselineCommitSeq = 0;
+    unsubscribeEvent;
+    unsubscribeInvalidation;
+    writes = new PostgresDeferredWriteQueue();
+    operations;
+    projectionRefreshes;
+    shutdownPromise = null;
+    shutdownComplete = false;
+    baseStopped = false;
+    stopQueueRefreshes = false;
+    constructor(config) {
+        const { postgres, ...baseConfig } = config;
+        super(baseConfig);
+        if (this.backgroundTaskHandles)
+            stopBackgroundTasks(this.backgroundTaskHandles);
+        this.postgresSnapshot = new PostgresQueueSnapshot(this.config.maxCompletedJobs, this.config.maxJobResults);
+        this.postgresStore = new PostgresQueueStore({
+            ...postgres,
+            maxQueueEvents: this.config.maxQueueEvents,
+            maxMetricDataPoints: this.config.maxMetricDataPoints,
+            maxCompletedJobs: this.config.maxCompletedJobs,
+            maxJobResults: this.config.maxJobResults,
+        });
+        this.operations = new PostgresOperationGate(this.postgresStore.config.maxConcurrentOperations, this.postgresStore.config.maxQueuedOperations);
+        this.projectionRefreshes = new PostgresProjectionRefreshes((requests) => this.postgresStore.loadJobProjections(requests), (id, projection) => applyPostgresJobProjection(this.postgresSnapshot, this.activeTokens, id, projection), (queue, id, error) => this.postgresStore.reportProjectionRefresh(queue, id, error), this.postgresStore.config.pollIntervalMs);
+        this.unsubscribeEvent = this.postgresStore.onEvent((event) => this.onStoreEvent(event));
+        this.unsubscribeInvalidation = this.postgresStore.onInvalidation((queue) => {
+            this.scheduleQueueRefresh(queue);
+        });
+        this.postgresReady = this.initializePostgres();
+    }
+    async waitUntilReady() {
+        await this.postgresReady;
+    }
+    async flushPostgresWrites() {
+        await this.postgresReady;
+        await this.writes.flush();
+    }
+    async shutdownPostgres() {
+        if (this.shutdownComplete)
+            return;
+        if (!this.shutdownPromise) {
+            const attempt = this.performPostgresShutdown()
+                .then(() => {
+                this.shutdownComplete = true;
+            })
+                .finally(() => {
+                if (this.shutdownPromise === attempt && !this.shutdownComplete) {
+                    this.shutdownPromise = null;
+                }
+            });
+            this.shutdownPromise = attempt;
+        }
+        await this.shutdownPromise;
+    }
+    shutdown() {
+        void this.shutdownPostgres().catch(() => undefined);
+    }
+    async performPostgresShutdown() {
+        this.stopQueueRefreshes = true;
+        this.dirtyQueues.clear();
+        this.projectionRefreshes.close();
+        const operationDrain = this.operations.closeAndDrain();
+        await operationDrain;
+        this.stopBaseRuntime();
+        this.unsubscribeEvent();
+        this.unsubscribeInvalidation();
+        const errors = await this.writes.closeAndDrain();
+        try {
+            await this.postgresReady;
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        await Promise.allSettled([...this.refreshes.values(), this.projectionRefreshes.drain()]);
+        try {
+            await this.postgresStore.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        throwDeferredWriteErrors(errors, 'PostgreSQL shutdown failed');
+    }
+    tokenFor(id, token) {
+        return token ?? this.activeTokens.get(id) ?? this.postgresSnapshot.get(id)?.token ?? null;
+    }
+    forgetToken(id) {
+        this.activeTokens.delete(id);
+    }
+    runPostgresOperation(operation) {
+        return this.operations.run(operation);
+    }
+    async refreshJob(id, queue) {
+        const targetQueue = queue ?? this.postgresSnapshot.get(id)?.job.queue ?? '';
+        try {
+            await this.projectionRefreshes.refreshNow(id, targetQueue);
+        }
+        catch {
+            this.projectionRefreshes.request(id, targetQueue);
+        }
+    }
+    async fetchPostgresJob(id) {
+        const queue = this.postgresSnapshot.get(id)?.job.queue ?? '';
+        return (await this.projectionRefreshes.refreshNow(id, queue)).row;
+    }
+    async refreshJobs(ids, queue) {
+        const requests = [...new Set(ids)].map((id) => ({
+            id,
+            queue: queue ?? this.postgresSnapshot.get(id)?.job.queue ?? '',
+        }));
+        try {
+            await this.projectionRefreshes.refreshManyNow(requests);
+        }
+        catch {
+            for (const request of requests)
+                this.projectionRefreshes.request(request.id, request.queue);
+        }
+    }
+    async refreshQueue(queue) {
+        const eventVersion = this.queueEventVersions.get(queue) ?? 0;
+        const { rows, state, exists, results } = await this.postgresStore.loadQueueReadModel(queue);
+        if (eventVersion !== (this.queueEventVersions.get(queue) ?? 0)) {
+            this.dirtyQueues.add(queue);
+            return false;
+        }
+        this.projectionRefreshes.supersedeQueue(queue);
+        if (!exists) {
+            for (const id of this.postgresSnapshot.removeQueue(queue))
+                this.activeTokens.delete(id);
+            return true;
+        }
+        this.postgresSnapshot.replaceQueue(queue, rows, state, results);
+        return true;
+    }
+    async refreshQueueAfterCommit(queue) {
+        try {
+            if (!(await this.refreshQueue(queue)))
+                this.scheduleQueueRefresh(queue);
+            else
+                this.postgresStore.reportQueueRefresh(queue, null);
+        }
+        catch (error) {
+            this.postgresStore.reportQueueRefresh(queue, error);
+            this.scheduleQueueRefresh(queue);
+        }
+    }
+    enqueueWrite(operation) {
+        this.writes.enqueue(operation);
+    }
+    async initializePostgres() {
+        await this.postgresStore.initialize();
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const buffer = this.snapshotEventBuffer;
+            if (!buffer)
+                return;
+            buffer.reset();
+            const { rows, results, crons, states } = await this.postgresStore.loadManagerSnapshot();
+            const events = buffer.take();
+            if (!events && attempt === 0)
+                continue;
+            this.postgresSnapshot.hydrate(rows);
+            this.postgresSnapshot.hydrateResults(results);
+            this.cronScheduler.load([...crons]);
+            for (const state of states)
+                this.postgresSnapshot.setQueueState(state);
+            for (const event of events ?? []) {
+                this.postgresSnapshot.apply(event);
+                applyPostgresEventMetrics(this.metrics, this.perQueueMetrics, event, false);
+            }
+            await this.postgresStore.finalizeLifetimeMetrics((lifetimeMetrics) => {
+                hydratePostgresLifetimeMetrics(this.metrics, this.perQueueMetrics, lifetimeMetrics);
+                this.terminalMetricBaselineCommitSeq = lifetimeMetrics.baselineCommitSeq;
+                this.snapshotEventBuffer = null;
+                this.projectionRefreshes.start();
+            });
+            return;
+        }
+    }
+    scheduleQueueRefresh(queue) {
+        if (this.stopQueueRefreshes)
+            return;
+        this.dirtyQueues.add(queue);
+        if (this.refreshes.has(queue))
+            return;
+        const refresh = this.postgresReady
+            .then(() => this.refreshDirtyQueue(queue))
+            .catch(() => {
+            this.dirtyQueues.delete(queue);
+        })
+            .finally(() => {
+            this.refreshes.delete(queue);
+            if (this.dirtyQueues.has(queue))
+                this.scheduleQueueRefresh(queue);
+        });
+        this.refreshes.set(queue, refresh);
+    }
+    async refreshDirtyQueue(queue) {
+        let retryDelay = this.postgresStore.config.pollIntervalMs;
+        while (!this.stopQueueRefreshes && this.dirtyQueues.delete(queue)) {
+            try {
+                const applied = await this.refreshQueue(queue);
+                if (!applied && !this.stopQueueRefreshes) {
+                    await Bun.sleep(this.postgresStore.config.pollIntervalMs);
+                }
+                this.postgresStore.reportQueueRefresh(queue, null);
+                retryDelay = this.postgresStore.config.pollIntervalMs;
+            }
+            catch (error) {
+                this.postgresStore.reportQueueRefresh(queue, error);
+                if (this.stopQueueRefreshes)
+                    return;
+                this.dirtyQueues.add(queue);
+                await Bun.sleep(retryDelay);
+                retryDelay = Math.min(retryDelay * 2, 1_000);
+            }
+        }
+    }
+    onStoreEvent(event) {
+        this.queueEventVersions.set(event.queue, (this.queueEventVersions.get(event.queue) ?? 0) + 1);
+        const startupBuffer = this.snapshotEventBuffer;
+        startupBuffer?.capture(event);
+        if (startupBuffer)
+            this.postgresSnapshot.apply(event);
+        if (startupBuffer?.overflowed)
+            this.scheduleQueueRefresh(event.queue);
+        else
+            this.projectionRefreshes.request(event.jobId, event.queue);
+        const mapped = postgresEventType(event.type);
+        if (!mapped)
+            return;
+        if (!startupBuffer) {
+            applyPostgresEventMetrics(this.metrics, this.perQueueMetrics, event, event.commitSeq > this.terminalMetricBaselineCommitSeq);
+        }
+        this.eventsManager.broadcast({
+            eventType: mapped,
+            queue: event.queue,
+            jobId: event.jobId,
+            timestamp: event.occurredAt,
+            ...(Object.hasOwn(event, 'result') && { data: event.result }),
+            ...(event.error !== undefined && { error: event.error }),
+            ...(mapped === 'failed' && { terminal: event.state === 'failed' }),
+        });
+    }
+    applyPostgresClaim(claim) {
+        this.projectionRefreshes.supersede(claim.job.id);
+        this.activeTokens.set(claim.job.id, claim.token);
+        this.postgresSnapshot.claim(claim);
+    }
+    stopBaseRuntime() {
+        if (this.baseStopped)
+            return;
+        this.baseStopped = true;
+        super.shutdown();
+    }
+}

package/dist/application/postgres-queue-manager/terminalDelivery.d.ts

@@ -0,0 +1,20 @@
+import { FailureReason } from '../../domain/types/dlq';
+import type { JobId } from '../../domain/types/job';
+import type { AckBatchOutcome, AckOutcome, CompletionOptions } from '../types/ack';
+import { PostgresQueueManagerQueries } from './queries';
+/** Terminal delivery transitions drained before the PostgreSQL pool closes. */
+export declare class PostgresQueueManagerTerminalDelivery extends PostgresQueueManagerQueries {
+    ack(id: JobId, result?: unknown, token?: string, options?: CompletionOptions): Promise<AckOutcome>;
+    ackBatch(ids: JobId[], tokens?: string[]): Promise<AckBatchOutcome>;
+    ackBatchWithResults(items: Array<{
+        id: JobId;
+        result: unknown;
+        token?: string;
+    } & CompletionOptions>): Promise<AckBatchOutcome>;
+    fail(id: JobId, error?: string, token?: string, unrecoverable?: boolean, stack?: string[], removeOnFail?: boolean): Promise<AckOutcome>;
+    failWithReason(id: JobId, error: string | undefined, reason: FailureReason): Promise<AckOutcome>;
+    private requireToken;
+    private ackPostgres;
+    private completeBatch;
+    private failPostgres;
+}

package/dist/application/postgres-queue-manager/terminalDelivery.js

@@ -0,0 +1,100 @@
+import { applyPostgresBatchCompletion } from './batchSnapshot';
+import { PostgresQueueManagerQueries } from './queries';
+/** Terminal delivery transitions drained before the PostgreSQL pool closes. */
+export class PostgresQueueManagerTerminalDelivery extends PostgresQueueManagerQueries {
+    async ack(id, result, token, options = {}) {
+        return await this.runPostgresOperation(() => this.ackPostgres(id, result, token, options));
+    }
+    async ackBatch(ids, tokens) {
+        return await this.runPostgresOperation(() => this.completeBatch(ids.map((id, index) => ({ id, token: tokens?.[index] }))));
+    }
+    async ackBatchWithResults(items) {
+        return await this.runPostgresOperation(() => this.completeBatch(items));
+    }
+    // oxlint-disable-next-line max-params -- public compatibility signature carries failure policy
+    async fail(id, error, token, unrecoverable = false, stack, removeOnFail) {
+        return await this.runPostgresOperation(() => this.failPostgres(id, error, token, { unrecoverable, stack, removeOnFail }));
+    }
+    async failWithReason(id, error, reason) {
+        return await this.runPostgresOperation(() => this.failPostgres(id, error, undefined, {
+            unrecoverable: reason === "timeout" /* FailureReason.Timeout */,
+            failureReason: reason,
+        }));
+    }
+    requireToken(id, supplied) {
+        const token = this.tokenFor(id, supplied);
+        if (!token)
+            throw new Error(`Lock token required for job ${String(id)}`);
+        return token;
+    }
+    async ackPostgres(id, result, token, options) {
+        await this.postgresReady;
+        const transition = await this.postgresStore.complete(id, this.requireToken(id, token), result, options.removeOnComplete);
+        this.forgetToken(id);
+        await this.refreshJob(id);
+        if (transition.applied)
+            return;
+        if (transition.alreadyFinalized)
+            return { applied: false, reason: 'already-finalized' };
+        throw new Error(`Invalid or expired lock token for job ${String(id)}`);
+    }
+    async completeBatch(items) {
+        if (items.length === 0)
+            return;
+        if (new Set(items.map((item) => String(item.id))).size === items.length) {
+            await this.postgresReady;
+            const transitions = await this.postgresStore.completeMany(items.map((item) => ({
+                id: item.id,
+                token: this.requireToken(item.id, item.token),
+                result: item.result,
+                removeOnComplete: item.removeOnComplete,
+            })));
+            const repeatQueues = new Set();
+            const ignoredIds = [];
+            const ignoredIndices = [];
+            for (let index = 0; index < transitions.length; index++) {
+                const transition = transitions[index];
+                this.forgetToken(items[index].id);
+                const repeatQueue = applyPostgresBatchCompletion(this.postgresSnapshot, items[index], transition);
+                if (repeatQueue)
+                    repeatQueues.add(repeatQueue);
+                if (!transition.applied) {
+                    ignoredIndices.push(index);
+                    ignoredIds.push(items[index].id);
+                }
+            }
+            await Promise.all([
+                ...ignoredIds.map((id) => this.refreshJob(id)),
+                ...[...repeatQueues].map((queue) => this.refreshQueueAfterCommit(queue)),
+            ]);
+            return ignoredIndices.length === 0
+                ? undefined
+                : { ignoredIndices, ignoredIds: ignoredIndices.map((index) => items[index].id) };
+        }
+        const ignoredIndices = [];
+        for (let index = 0; index < items.length; index++) {
+            const outcome = await this.ackPostgres(items[index].id, items[index].result, items[index].token, items[index]);
+            if (outcome)
+                ignoredIndices.push(index);
+        }
+        return ignoredIndices.length === 0
+            ? undefined
+            : { ignoredIndices, ignoredIds: ignoredIndices.map((index) => items[index].id) };
+    }
+    async failPostgres(id, error, token, options) {
+        await this.postgresReady;
+        const transition = await this.postgresStore.fail({
+            id,
+            token: this.requireToken(id, token),
+            error,
+            ...options,
+        });
+        this.forgetToken(id);
+        await this.refreshJob(id);
+        if (transition.applied)
+            return;
+        if (transition.alreadyFinalized)
+            return { applied: false, reason: 'already-finalized' };
+        throw new Error(`Invalid or expired lock token for job ${String(id)}`);
+    }
+}

package/dist/application/postgresQueueManager.d.ts

@@ -0,0 +1,2 @@
+export { PostgresQueueManagerOperations as PostgresQueueManager } from './postgres-queue-manager/operations';
+export type { PostgresQueueManagerConfig } from './postgres-queue-manager/config';

package/dist/application/postgresQueueManager.js

@@ -0,0 +1 @@
+export { PostgresQueueManagerOperations as PostgresQueueManager } from './postgres-queue-manager/operations';

package/dist/application/queue-manager/flow-failures.js

@@ -9,6 +9,10 @@ export class QueueManagerFlowFailures extends QueueManagerDependencyRuntime {
             this.jobIndex.delete(entry.job.id);
             this.jobResults.delete(entry.job.id);
             this.jobLogs.delete(entry.job.id);
+            this.dependencyResults.releaseConsumer(entry.job.id);
+            if (entry.job.customId && this.customIdMap.get(entry.job.customId) === entry.job.id) {
+                this.customIdMap.delete(entry.job.customId);
+            }
         }
         this.storage?.purgeDlqEntries(entry.job.queue, [entry.job.id], ownsTerminal ? [entry.job.id] : [], false);
     }

package/dist/application/queue-manager/limits.d.ts

@@ -16,6 +16,8 @@ export declare class QueueManagerLimits extends QueueManagerControl {
     retryDlq(queue: string, jobId?: JobId, limit?: number): number;
     retryDlqByFilter(queue: string, filter: DlqFilter): number;
     purgeDlq(queue: string): number;
+    /** Remove one terminal DLQ job without re-enqueuing it. */
+    removeDlqJob(queue: string, jobId: JobId): boolean;
     retryCompleted(queue: string, jobId?: JobId, options?: {
         limit?: number;
         timestamp?: number;

package/dist/application/queue-manager/limits.js

@@ -37,6 +37,10 @@ export class QueueManagerLimits extends QueueManagerControl {
     purgeDlq(queue) {
         return dlqOps.purgeDlqJobs(queue, this.contextFactory.getDlqContext());
     }
+    /** Remove one terminal DLQ job without re-enqueuing it. */
+    removeDlqJob(queue, jobId) {
+        return dlqOps.removeDlqJob(queue, jobId, this.contextFactory.getDlqContext());
+    }
     retryCompleted(queue, jobId, options) {
         return dlqOps.retryCompletedJobs(queue, this.contextFactory.getRetryCompletedContext(), jobId, options);
     }

package/dist/application/queue-manager/observability.js

@@ -2,6 +2,7 @@ import * as logsOps from '../jobLogsManager';
 import { generatePrometheusMetrics } from '../metricsExporter';
 import { selectPrometheusQueues } from '../prometheusOperationalMetrics';
 import * as statsMgr from '../statsManager';
+import { isStorageDegraded } from '../../shared/storageHealth';
 import { QueueManagerStats } from './stats';
 export class QueueManagerObservability extends QueueManagerStats {
     getQueueMetrics(queue, type, start = 0, end = -1) {
@@ -25,9 +26,20 @@ export class QueueManagerObservability extends QueueManagerStats {
     getPrometheusMetrics() {
         const storageStatus = this.getStorageStatus();
         const memory = process.memoryUsage();
-        const queueSelection = selectPrometheusQueues(this.queueNamesCache, this.config.maxPrometheusQueues);
-        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, statsMgr.getPerQueueStats(this.contextFactory.getStatsContext(), queueSelection.selected), {
-            storageDegraded: storageStatus.diskFull,
+        const queueSelection = selectPrometheusQueues(this.listQueues(), this.config.maxPrometheusQueues);
+        const countsByQueue = this.getQueueJobCountsBatch(queueSelection.selected);
+        const perQueueStats = new Map([...countsByQueue].map(([queue, counts]) => [
+            queue,
+            {
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                delayed: counts.delayed,
+                active: counts.active,
+                dlq: counts.failed,
+            },
+        ]));
+        return generatePrometheusMetrics(this.getStats(), this.workerManager, this.webhookManager, perQueueStats, {
+            storageDegraded: isStorageDegraded(storageStatus),
             storageDiskFull: storageStatus.diskFull,
             ...(this.storage && { sqliteDatabaseSizeBytes: this.storage.getSize() }),
             processHeapUsedBytes: memory.heapUsed,

package/dist/application/queue-manager/queries.d.ts

@@ -4,6 +4,13 @@ export declare class QueueManagerQueries extends QueueManagerLocks {
     getJob(jobId: JobId): Promise<Job | null>;
     getJobState(jobId: JobId): Promise<string>;
     getResult(jobId: JobId): unknown;
+    /** Distinguish a completed generation from a valid undefined result. */
+    getCompletionAsync(jobId: JobId): Promise<{
+        found: boolean;
+        result: unknown;
+    }>;
+    /** Async result port used by transports; memory and SQLite remain synchronous internally. */
+    getResultAsync(jobId: JobId): Promise<unknown>;
     getChildrenValues(parentJobId: JobId): Promise<Record<string, unknown>>;
     updateJobParent(childJobId: JobId, parentJobId: JobId): Promise<void>;
     getJobByCustomId(customId: string): Job | null;

package/dist/application/queue-manager/queries.js

@@ -14,6 +14,15 @@ export class QueueManagerQueries extends QueueManagerLocks {
     getResult(jobId) {
         return queryOps.getJobResult(jobId, this.contextFactory.getQueryContext());
     }
+    /** Distinguish a completed generation from a valid undefined result. */
+    async getCompletionAsync(jobId) {
+        const found = this.completedJobs.has(jobId);
+        return { found, result: found ? this.getResult(jobId) : undefined };
+    }
+    /** Async result port used by transports; memory and SQLite remain synchronous internally. */
+    async getResultAsync(jobId) {
+        return (await this.getCompletionAsync(jobId)).result;
+    }
     async getChildrenValues(parentJobId) {
         const job = await this.getJob(parentJobId);
         if (!job?.childrenIds || job.childrenIds.length === 0)

package/dist/application/queue-manager/services.d.ts

@@ -12,7 +12,7 @@ export declare class QueueManagerServices extends QueueManagerObservability {
     setDashboardEmit(fn: (event: string, data: Record<string, unknown>) => void): void;
     emitDashboardEvent(event: string, data: Record<string, unknown>): void;
     subscribe(callback: (event: JobEvent) => void): () => void;
-    waitForJobCompletion(jobId: JobId, timeoutMs: number): Promise<boolean>;
+    waitForJobCompletion(jobId: JobId, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     registerWorker(name: string, queues: string[], concurrency?: number, options?: CreateWorkerOptions): import("../../domain/types/worker").Worker;
     unregisterWorker(workerId: string): boolean;
     unregisterWorkersByClientId(clientId: string): number;

package/dist/application/queue-manager/services.js

@@ -1,7 +1,9 @@
+import { assertValidCronInput } from '../../infrastructure/scheduler/cron/validation';
 import { shardIndex } from '../../shared/hash';
 import { QueueManagerObservability } from './observability';
 export class QueueManagerServices extends QueueManagerObservability {
     addCron(input) {
+        assertValidCronInput(input);
         if (input.preventOverlap) {
             this.removeOrphanedCronJob(input.queue, input.uniqueKey ?? `cron:${input.name}`);
         }
@@ -54,8 +56,8 @@ export class QueueManagerServices extends QueueManagerObservability {
     subscribe(callback) {
         return this.eventsManager.subscribe(callback);
     }
-    waitForJobCompletion(jobId, timeoutMs) {
-        return this.eventsManager.waitForJobCompletion(jobId, timeoutMs);
+    waitForJobCompletion(jobId, timeoutMs, signal) {
+        return this.eventsManager.waitForJobCompletion(jobId, timeoutMs, signal);
     }
     registerWorker(name, queues, concurrency, options) {
         const worker = this.workerManager.register(name, queues, concurrency, options);

package/dist/application/queue-manager/state.js

@@ -1,6 +1,7 @@
 import { Shard } from '../../domain/queue/shard';
 import { SqliteStorage } from '../../infrastructure/persistence/sqlite';
 import { CronScheduler } from '../../infrastructure/scheduler/cronScheduler';
+import { assertPersistedCronsSupported } from '../../infrastructure/scheduler/cron/persisted';
 import { RWLock } from '../../shared/lock';
 import { SHARD_COUNT } from '../../shared/hash';
 import { BoundedMap, BoundedSet, LRUMap } from '../../shared/lru';
@@ -83,6 +84,20 @@ export class QueueManagerState {
     constructor(config = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
         this.storage = config.dataPath ? new SqliteStorage({ path: config.dataPath }) : null;
+        let persistedCrons;
+        try {
+            persistedCrons = this.storage?.loadCronJobs() ?? [];
+            assertPersistedCronsSupported(persistedCrons);
+        }
+        catch (error) {
+            try {
+                this.storage?.close();
+            }
+            catch {
+                // Preserve the read/validation error that made construction fail.
+            }
+            throw error;
+        }
         this.telemetryJournal = new QueueTelemetryJournal(this.storage, this.config.maxQueueEvents, this.config.maxMetricDataPoints);
         this.completedJobsData = new BoundedMap(this.config.maxCompletedJobs);
         this.completedJobs = new BoundedSet(this.config.maxCompletedJobs, (id) => {
@@ -138,7 +153,7 @@ export class QueueManagerState {
         }
         this.recoveryStats = { queues: this.queueNamesCache.size, jobs: this.jobIndex.size };
         if (this.storage)
-            this.cronScheduler.load(this.storage.loadCronJobs());
+            this.cronScheduler.load(persistedCrons);
         this.backgroundTaskHandles = bgTasks.startBackgroundTasks(this.contextFactory.getBackgroundContext(), this.cronScheduler);
     }
 }

package/dist/cli/commands/server.js

@@ -106,5 +106,5 @@ export async function runServer(args, showHelp) {
     const mergedConfig = applyCliFlags(fileConfig, flags);
     const config = resolveServerConfig(mergedConfig);
     // Same full server as the bare `bunqueue` entry (shared bootstrap)
-    bootServer(mergedConfig, config);
+    await bootServer(mergedConfig, config);
 }

package/dist/client/forwarder.d.ts

@@ -5,11 +5,13 @@
  * The edge pattern: jobs buffer in the local queue (typically embedded
  * SQLite on a gateway); the Forwarder drains them to a central server over
  * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
- * local DLQ, so nothing is lost while the uplink is down.
+ * local DLQ. With a persistent local `dataPath`, queued work survives uplink
+ * outages and process restarts; memory-only sources provide no such guarantee.
  *
  * Idempotency: every forwarded job carries the deterministic remote jobId
- * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
- * re-forward after a crash or retry never duplicates the job remotely.
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds while
+ * their ownership is retained; after bounded retention or removal, downstream
+ * effects must still tolerate at-least-once delivery.
  */
 import { EventEmitter } from 'events';
 import type { ConnectionOptions, QueueOptions } from './types';
@@ -21,7 +23,7 @@ export interface ForwardOptions {
     queue?: string;
     /** Parallel forwards (default: 4) */
     concurrency?: number;
-    /** Push to the remote with durable: true (immediate fsync server-side) */
+    /** Push with durable: true (bypasses SQLite buffering; PostgreSQL is already transactional). */
     durable?: boolean;
 }
 /** Source queue identity + config, provided by Queue.forward() */

package/dist/client/forwarder.js

@@ -5,11 +5,13 @@
  * The edge pattern: jobs buffer in the local queue (typically embedded
  * SQLite on a gateway); the Forwarder drains them to a central server over
  * TCP/TLS. A remote failure makes the local job fail → local retry/backoff →
- * local DLQ, so nothing is lost while the uplink is down.
+ * local DLQ. With a persistent local `dataPath`, queued work survives uplink
+ * outages and process restarts; memory-only sources provide no such guarantee.
  *
  * Idempotency: every forwarded job carries the deterministic remote jobId
- * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds, so a
- * re-forward after a crash or retry never duplicates the job remotely.
+ * `fwd:<localQueueKey>:<localJobId>`. The server dedupes custom jobIds while
+ * their ownership is retained; after bounded retention or removal, downstream
+ * effects must still tolerate at-least-once delivery.
  */
 import { EventEmitter } from 'events';
 import { Worker } from './worker';

package/dist/client/queue/dlq.d.ts

@@ -52,6 +52,8 @@ export declare function purgeDlq(ctx: DlqContext): number;
  * purge-then-assert-empty patterns need this variant.
  */
 export declare function purgeDlqAsync(ctx: DlqContext): Promise<number>;
+/** Remove one DLQ entry without re-enqueuing it. */
+export declare function removeDlqJobAsync(ctx: DlqContext, id: string): Promise<boolean>;
 /** Retry completed job */
 export declare function retryCompleted(ctx: DlqContext, id?: string): number;
 /** Retry completed job (async) */

package/dist/client/queue/dlq.js

@@ -197,6 +197,20 @@ export async function purgeDlqAsync(ctx) {
         return 0;
     return (response.count ?? 0);
 }
+/** Remove one DLQ entry without re-enqueuing it. */
+export async function removeDlqJobAsync(ctx, id) {
+    if (ctx.embedded)
+        return dlqOps.removeDlqJobEmbedded(ctx.name, id);
+    if (!ctx.tcp)
+        return false;
+    const response = await ctx.tcp.send({ cmd: 'RemoveDlqJob', queue: ctx.name, jobId: id });
+    if (!response.ok) {
+        const error = typeof response.error === 'string' ? response.error : 'Failed to remove the DLQ job';
+        throw new Error(error);
+    }
+    const payload = response;
+    return payload.data?.removed === true;
+}
 /** Retry completed job */
 export function retryCompleted(ctx, id) {
     if (ctx.embedded) {