@warlock.js/queue 5.33.0 → 5.34.0

package/cjs/index.cjs

@@ -1,6 +1,10 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let _warlock_js_logger = require("@warlock.js/logger");
 let bullmq = require("bullmq");
+let node_crypto = require("node:crypto");
+let node_fs = require("node:fs");
+let node_module = require("node:module");
+let node_path = require("node:path");
 
 //#region ../../packages/queue/src/errors.ts
 /**
@@ -278,111 +282,640 @@ async function processJob(job) {
 }
 
 //#endregion
-//#region ../../packages/queue/src/queue-manager.ts
-const DEFAULT_SHUTDOWN_TIMEOUT = 3e4;
-const queues = /* @__PURE__ */ new Map();
-const workers = /* @__PURE__ */ new Map();
-let stopListening;
-/**
-* The BullMQ queue for `name`, created on first use with the configured
-* connection and prefix.
-*/
-function getQueue(name) {
-	let queue = queues.get(name);
-	if (!queue) {
-		const config = getQueueConfig();
-		queue = new bullmq.Queue(name, {
-			connection: config.connection,
-			prefix: config.prefix ?? "warlock"
+//#region ../../packages/queue/src/drivers/bullmq.ts
+var BullMQDriver = class {
+	constructor(config) {
+		this.config = config;
+		this.queues = /* @__PURE__ */ new Map();
+		this.workers = /* @__PURE__ */ new Map();
+		if (!config.connection) throw new Error("The bullmq queue driver requires `connection`.");
+	}
+	getQueue(name) {
+		let queue = this.queues.get(name);
+		if (!queue) {
+			const connection = this.config.connection;
+			if (!connection) throw new Error("The bullmq queue driver requires `connection`.");
+			queue = new bullmq.Queue(name, {
+				connection,
+				prefix: this.config.prefix ?? "warlock"
+			});
+			queue.on("error", (error) => _warlock_js_logger.log.error("queue", "connection", error));
+			this.queues.set(name, queue);
+		}
+		return queue;
+	}
+	async dispatch(request) {
+		const { backoff, ...rest } = request.options;
+		const options = {
+			...rest,
+			backoff: typeof backoff === "number" ? {
+				type: "fixed",
+				delay: backoff
+			} : backoff
+		};
+		const job = await this.getQueue(request.queue).add(request.name, request.data, options);
+		return {
+			id: String(job.id),
+			name: request.name,
+			queue: request.queue
+		};
+	}
+	async find(queue, id) {
+		const source = this.getQueue(queue);
+		const initial = await source.getJob(id);
+		if (!initial) return void 0;
+		const state = await initial.getState();
+		return toSnapshot(await source.getJob(id) ?? initial, state);
+	}
+	async failed(queue, start, end) {
+		return (await this.getQueue(queue).getFailed(start, end)).map((job) => ({
+			id: String(job.id),
+			name: job.name,
+			queue,
+			payload: unwrapPayload(job.data).payload,
+			attemptsMade: job.attemptsMade,
+			failedReason: job.failedReason,
+			stacktrace: job.stacktrace ?? [],
+			failedAt: job.finishedOn ? new Date(job.finishedOn) : void 0,
+			retry: () => job.retry("failed")
+		}));
+	}
+	async retry(queue, id) {
+		const job = await this.getQueue(queue).getJob(id);
+		if (!job || !await job.isFailed()) throw new FailedJobNotFoundError(id, queue);
+		await job.retry("failed");
+	}
+	async start(queue) {
+		let worker = this.workers.get(queue);
+		if (!worker) {
+			const connection = this.config.connection;
+			if (!connection) throw new Error("The bullmq queue driver requires `connection`.");
+			worker = new bullmq.Worker(queue, processJob, {
+				connection,
+				prefix: this.config.prefix ?? "warlock",
+				concurrency: this.config.workers?.concurrency ?? 1
+			});
+			worker.on("error", (error) => _warlock_js_logger.log.error("queue", "worker", error));
+			worker.on("failed", (job, error) => _warlock_js_logger.log.error("queue", "job.failed", `${job?.name ?? "unknown"} (${job?.id ?? "?"}): ${error.message}`));
+			this.workers.set(queue, worker);
+		}
+		await worker.waitUntilReady();
+	}
+	running() {
+		return [...this.workers.keys()];
+	}
+	async close(timeout) {
+		const workers = [...this.workers.values()];
+		this.workers.clear();
+		await Promise.all(workers.map((worker) => closeWorker(worker, timeout)));
+		const queues = [...this.queues.values()];
+		this.queues.clear();
+		await Promise.all(queues.map((queue) => queue.close()));
+	}
+};
+function toSnapshot(job, state) {
+	return {
+		id: String(job.id),
+		name: job.name,
+		queue: job.queueName,
+		state,
+		payload: unwrapPayload(job.data).payload,
+		progress: job.progress,
+		attemptsMade: job.attemptsMade,
+		result: job.returnvalue,
+		failedReason: job.failedReason || void 0,
+		createdAt: new Date(job.timestamp),
+		finishedAt: job.finishedOn ? new Date(job.finishedOn) : void 0
+	};
+}
+async function closeWorker(worker, timeout) {
+	let timer;
+	const timedOut = new Promise((resolve) => {
+		timer = setTimeout(() => resolve("timeout"), timeout);
+	});
+	const closing = worker.close().then(() => "closed");
+	closing.catch(() => void 0);
+	try {
+		if (await Promise.race([closing, timedOut]) === "timeout") {
+			_warlock_js_logger.log.warn("queue", "shutdown", `Worker for "${worker.name}" still had active jobs after ${timeout}ms; disconnecting. Those jobs are retried once their lock expires.`);
+			await worker.disconnect();
+		}
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+//#endregion
+//#region ../../packages/queue/src/drivers/local-store.ts
+/** Match JSON transport on every backend, without sharing mutable objects. */
+function jsonCopy(value) {
+	return JSON.parse(JSON.stringify({ value })).value;
+}
+
+//#endregion
+//#region ../../packages/queue/src/drivers/local.ts
+/** Shared scheduling and lease semantics for the SQLite and memory stores. */
+var LocalDriver = class {
+	constructor(store, config) {
+		this.store = store;
+		this.workers = /* @__PURE__ */ new Map();
+		this.active = /* @__PURE__ */ new Set();
+		this.closed = false;
+		this.stopping = false;
+		try {
+			this.leaseDuration = positiveInteger(config.local?.leaseDuration ?? 3e4, "local.leaseDuration", 30);
+			this.pollInterval = positiveInteger(config.local?.pollInterval ?? 100, "local.pollInterval");
+			this.concurrency = positiveInteger(config.workers?.concurrency ?? 1, "workers.concurrency");
+		} catch (error) {
+			store.close();
+			throw error;
+		}
+	}
+	async dispatch(request) {
+		this.assertOpen();
+		validateOptions(request);
+		const id = request.options.jobId ?? (0, node_crypto.randomUUID)();
+		const now = Date.now();
+		return {
+			id: this.store.transaction(() => {
+				const previous = this.store.get(request.queue, id);
+				if (previous) return previous;
+				const entry = {
+					id,
+					name: request.name,
+					queue: request.queue,
+					data: jsonCopy(request.data),
+					options: jsonCopy(request.options),
+					state: request.options.delay ? "delayed" : request.options.priority ? "prioritized" : "waiting",
+					createdAt: now,
+					readyAt: now + (request.options.delay ?? 0),
+					attemptsMade: 0,
+					priority: request.options.priority ?? 0,
+					progress: 0,
+					logs: [],
+					stacktrace: [],
+					leaseUntil: 0
+				};
+				this.store.put(entry);
+				return entry;
+			}).id,
+			name: request.name,
+			queue: request.queue
+		};
+	}
+	async find(queue, id) {
+		this.assertOpen();
+		const job = this.store.get(queue, id);
+		return job ? snapshot(job) : void 0;
+	}
+	async failed(queue, start, end) {
+		this.assertOpen();
+		const jobs = newestFirst(this.store.list(queue, "failed"));
+		const last = end < 0 ? jobs.length + end : end;
+		return jobs.slice(start, last + 1).map((job) => ({
+			id: job.id,
+			name: job.name,
+			queue,
+			payload: unwrapPayload(job.data).payload,
+			attemptsMade: job.attemptsMade,
+			failedReason: job.failedReason ?? "",
+			stacktrace: job.stacktrace,
+			failedAt: job.finishedAt === void 0 ? void 0 : new Date(job.finishedAt),
+			retry: () => this.retry(queue, job.id)
+		}));
+	}
+	async retry(queue, id) {
+		this.assertOpen();
+		this.store.transaction(() => {
+			const job = this.store.get(queue, id);
+			if (!job || job.state !== "failed") throw new FailedJobNotFoundError(id, queue);
+			job.state = job.priority ? "prioritized" : "waiting";
+			job.attemptsMade = 0;
+			job.readyAt = Date.now();
+			delete job.finishedAt;
+			delete job.failedReason;
+			delete job.result;
+			job.stacktrace = [];
+			this.store.put(job);
+		});
+	}
+	async start(queue) {
+		this.assertOpen();
+		if (this.stopping) throw new Error("Queue workers are shutting down.");
+		if (this.workers.has(queue)) return;
+		const worker = { active: /* @__PURE__ */ new Set() };
+		this.workers.set(queue, worker);
+		this.schedule(queue, worker, 0);
+	}
+	running() {
+		return [...this.workers.keys()];
+	}
+	async close(timeout) {
+		if (this.closed) return;
+		this.stopping = true;
+		for (const worker of this.workers.values()) clearTimeout(worker.timer);
+		this.workers.clear();
+		let timer;
+		const timedOut = new Promise((resolve) => {
+			timer = setTimeout(resolve, timeout);
+		});
+		try {
+			await Promise.race([Promise.allSettled([...this.active].map((entry) => entry.done)), timedOut]);
+		} finally {
+			clearTimeout(timer);
+			try {
+				for (const entry of this.active) {
+					clearInterval(entry.heartbeat);
+					entry.controller.abort(/* @__PURE__ */ new Error("Queue shutdown timeout elapsed."));
+					this.mutate(entry.job, entry.token, (job) => {
+						job.state = job.priority ? "prioritized" : "waiting";
+						job.readyAt = Date.now();
+						job.leaseUntil = 0;
+						delete job.token;
+					});
+				}
+			} finally {
+				this.closed = true;
+				for (const entry of this.active) clearInterval(entry.heartbeat);
+				this.store.close();
+			}
+		}
+	}
+	schedule(queue, worker, delay) {
+		if (this.stopping) return;
+		worker.timer = setTimeout(() => {
+			try {
+				while (!this.stopping && worker.active.size < this.concurrency) {
+					const token = (0, node_crypto.randomUUID)();
+					const job = this.store.transaction(() => {
+						const now = Date.now();
+						const candidate = this.store.ready(queue, now);
+						if (!candidate) return void 0;
+						candidate.state = "active";
+						candidate.token = token;
+						candidate.leaseUntil = now + this.leaseDuration;
+						this.store.put(candidate);
+						return candidate;
+					});
+					if (!job) break;
+					this.run(job, token, worker);
+				}
+			} catch (error) {
+				_warlock_js_logger.log.error("queue", "worker", error);
+			}
+			this.schedule(queue, worker, this.pollInterval);
+		}, delay);
+	}
+	run(job, token, worker) {
+		const controller = new AbortController();
+		const heartbeat = setInterval(() => {
+			try {
+				if (!this.mutate(job, token, (current) => {
+					current.leaseUntil = Date.now() + this.leaseDuration;
+				})) {
+					controller.abort(/* @__PURE__ */ new Error("Queue job lease expired or changed owner."));
+					clearInterval(heartbeat);
+				}
+			} catch (error) {
+				controller.abort(error);
+				clearInterval(heartbeat);
+				_warlock_js_logger.log.error("queue", "lease", error);
+			}
+		}, Math.floor(this.leaseDuration / 3));
+		const entry = {
+			job,
+			token,
+			controller,
+			heartbeat,
+			done: Promise.resolve()
+		};
+		this.active.add(entry);
+		worker.active.add(entry);
+		entry.done = this.execute(entry).catch((error) => {
+			_warlock_js_logger.log.error("queue", "job", error);
+		}).finally(() => {
+			clearInterval(heartbeat);
+			this.active.delete(entry);
+			worker.active.delete(entry);
 		});
-		queue.on("error", (error) => {
-			_warlock_js_logger.log.error("queue", "connection", error);
+	}
+	async execute(entry) {
+		const { job, token, controller } = entry;
+		try {
+			const definition = findRegisteredJob(job.name);
+			if (!definition) throw new UnrecoverableJobError(`No job named "${job.name}" is defined in this process. Import its definition in the worker.`);
+			const { payload, context: captured } = unwrapPayload(job.data);
+			const context = {
+				id: job.id,
+				name: job.name,
+				queue: job.queue,
+				attempt: job.attemptsMade + 1,
+				maxAttempts: job.options.attempts ?? 1,
+				context: captured,
+				signal: controller.signal,
+				progress: async (value) => {
+					if (!this.mutate(job, token, (current) => {
+						current.progress = jsonCopy(value);
+					})) throw new Error("Queue job lease lost.");
+				},
+				log: async (line) => {
+					if (!this.mutate(job, token, (current) => {
+						current.logs.push(line);
+					})) throw new Error("Queue job lease lost.");
+				}
+			};
+			const run = async () => definition.handle(payload, context);
+			const queueContext = getQueueContext();
+			const result = jsonCopy(captured !== void 0 && queueContext ? await queueContext.restore(captured, run) : await run());
+			this.mutate(job, token, (current) => {
+				current.attemptsMade++;
+				current.result = result;
+				current.state = "completed";
+				current.finishedAt = Date.now();
+				current.leaseUntil = 0;
+				delete current.token;
+			}, true);
+		} catch (error) {
+			this.mutate(job, token, (current) => {
+				current.attemptsMade++;
+				current.failedReason = error instanceof Error ? error.message : String(error);
+				current.stacktrace.push(error instanceof Error ? error.stack ?? error.message : String(error));
+				current.leaseUntil = 0;
+				delete current.token;
+				if (error instanceof UnrecoverableJobError || current.attemptsMade >= (current.options.attempts ?? 1)) {
+					current.state = "failed";
+					current.finishedAt = Date.now();
+				} else {
+					const backoff = current.options.backoff;
+					const base = typeof backoff === "number" ? backoff : backoff?.delay ?? 0;
+					const delay = typeof backoff === "object" && backoff.type === "exponential" ? base * 2 ** (current.attemptsMade - 1) : base;
+					current.readyAt = Math.min(Number.MAX_SAFE_INTEGER, Date.now() + delay);
+					current.state = delay > 0 ? "delayed" : current.priority ? "prioritized" : "waiting";
+				}
+			}, true);
+		}
+	}
+	/** Fencing: expired owners cannot renew, finish, or overwrite a new owner's job. */
+	mutate(job, token, update, retain = false) {
+		if (this.closed) return false;
+		return this.store.transaction(() => {
+			const current = this.store.get(job.queue, job.id);
+			if (!current || !ownsLease(current, token)) return false;
+			update(current);
+			this.store.put(current);
+			if (retain && (current.state === "completed" || current.state === "failed")) {
+				const retention = current.state === "completed" ? current.options.removeOnComplete : current.options.removeOnFail;
+				if (retention === true) this.store.remove(current.queue, current.id);
+				if (typeof retention === "number") for (const old of newestFirst(this.store.list(current.queue, current.state)).slice(retention)) this.store.remove(old.queue, old.id);
+			}
+			return true;
 		});
-		queues.set(name, queue);
 	}
-	return queue;
+	assertOpen() {
+		if (this.closed) throw new Error("Queue driver is closed.");
+	}
+};
+function snapshot(job) {
+	return {
+		id: job.id,
+		name: job.name,
+		queue: job.queue,
+		state: job.state,
+		payload: unwrapPayload(job.data).payload,
+		progress: job.progress,
+		attemptsMade: job.attemptsMade,
+		result: job.result,
+		failedReason: job.failedReason,
+		createdAt: new Date(job.createdAt),
+		finishedAt: job.finishedAt === void 0 ? void 0 : new Date(job.finishedAt)
+	};
 }
-/**
-* Start one worker per queue that has a registered job, and keep starting
-* workers for queues whose first job is defined later.
-*
-* A no-op returning `[]` when `workers.enabled` is `false`, or when this
-* process does not serve the `worker` role (`Application.hasRole`) — a
-* process started with `--role=web`, for example, produces jobs but never
-* runs them in-process. Calling it again while workers run starts only the
-* missing ones.
-*
-* @returns the queue names that now have a worker in this process.
-*/
+function newestFirst(jobs) {
+	return jobs.reverse().sort((a, b) => (b.finishedAt ?? 0) - (a.finishedAt ?? 0));
+}
+function positiveInteger(value, name, minimum = 1) {
+	if (!Number.isSafeInteger(value) || value < minimum || value > 2147483647) throw new Error(`${name} must be an integer between ${minimum} and 2147483647.`);
+	return value;
+}
+function validateOptions({ options }) {
+	positiveInteger(options.attempts ?? 1, "attempts");
+	if (options.priority !== void 0 && (!Number.isInteger(options.priority) || options.priority < 0 || options.priority > 2097152)) throw new Error("priority must be an integer between 0 and 2097152.");
+	const backoff = options.backoff;
+	const delay = typeof backoff === "number" ? backoff : backoff?.delay ?? 0;
+	if (!Number.isFinite(delay) || delay < 0 || typeof backoff === "object" && !["fixed", "exponential"].includes(backoff.type)) throw new Error("backoff must have a non-negative finite delay and fixed or exponential type.");
+	if (options.delay !== void 0 && (!Number.isFinite(options.delay) || options.delay < 0)) throw new Error("delay must be non-negative and finite.");
+	for (const retention of [options.removeOnComplete, options.removeOnFail]) if (typeof retention === "number" && (!Number.isInteger(retention) || retention < 0)) throw new Error("Job retention must be a non-negative integer or boolean.");
+}
+function ownsLease(job, token) {
+	return job.state === "active" && job.token === token && job.leaseUntil > Date.now();
+}
+
+//#endregion
+//#region ../../packages/queue/src/drivers/memory-store.ts
+var MemoryStore = class {
+	constructor() {
+		this.jobs = /* @__PURE__ */ new Map();
+	}
+	transaction(run) {
+		const before = new Map(this.jobs);
+		try {
+			return run();
+		} catch (error) {
+			this.jobs = before;
+			throw error;
+		}
+	}
+	key(queue, id) {
+		return JSON.stringify([queue, id]);
+	}
+	get(queue, id) {
+		return jsonCopy(this.jobs.get(this.key(queue, id)));
+	}
+	list(queue, state) {
+		return [...this.jobs.values()].filter((job) => job.queue === queue && (!state || job.state === state)).map(jsonCopy);
+	}
+	ready(queue, now) {
+		let candidate;
+		for (const job of this.list(queue)) if ((job.state === "active" && job.leaseUntil <= now || [
+			"waiting",
+			"delayed",
+			"prioritized"
+		].includes(job.state) && job.readyAt <= now) && (!candidate || job.priority < candidate.priority)) candidate = job;
+		return candidate;
+	}
+	put(job) {
+		this.jobs.set(this.key(job.queue, job.id), jsonCopy(job));
+	}
+	remove(queue, id) {
+		this.jobs.delete(this.key(queue, id));
+	}
+	close() {
+		this.jobs.clear();
+	}
+};
+
+//#endregion
+//#region ../../packages/queue/src/drivers/sqlite-store.ts
+/** node:sqlite is loaded only when the local backend is selected. */
+var SqliteStore = class {
+	constructor(config) {
+		const path = (0, node_path.resolve)(config.local?.path ?? ".warlock/queue.sqlite");
+		if (config.local?.path === ":memory:") throw new Error("Use driver: 'memory' for non-durable queues.");
+		let sqlite;
+		try {
+			sqlite = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("node:sqlite");
+		} catch (cause) {
+			throw new Error("The local queue driver requires Node >= 22.15 with node:sqlite available without flags.", { cause });
+		}
+		if (typeof sqlite.DatabaseSync !== "function") throw new Error("node:sqlite.DatabaseSync is unavailable.");
+		(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+		this.db = new sqlite.DatabaseSync(path);
+		this.namespace = config.prefix ?? "warlock";
+		try {
+			this.db.exec(`
+        PRAGMA busy_timeout = 5000;
+        PRAGMA journal_mode = WAL;
+        PRAGMA synchronous = FULL;
+        CREATE TABLE IF NOT EXISTS warlock_queue_jobs (
+          seq INTEGER PRIMARY KEY AUTOINCREMENT,
+          namespace TEXT NOT NULL, queue TEXT NOT NULL, id TEXT NOT NULL,
+          state TEXT NOT NULL, ready_at REAL NOT NULL, lease_until REAL NOT NULL,
+          priority INTEGER NOT NULL, body TEXT NOT NULL,
+          UNIQUE(namespace, queue, id)
+        );
+        CREATE INDEX IF NOT EXISTS warlock_queue_ready
+          ON warlock_queue_jobs(namespace, queue, state, ready_at, lease_until);
+      `);
+		} catch (error) {
+			this.db.close();
+			throw error;
+		}
+	}
+	transaction(run) {
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = run();
+			this.db.exec("COMMIT");
+			return result;
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+	}
+	get(queue, id) {
+		return decode(this.db.prepare("SELECT body FROM warlock_queue_jobs WHERE namespace = ? AND queue = ? AND id = ?").get(this.namespace, queue, id));
+	}
+	list(queue, state) {
+		return (state ? this.db.prepare("SELECT body FROM warlock_queue_jobs WHERE namespace = ? AND queue = ? AND state = ? ORDER BY seq").all(this.namespace, queue, state) : this.db.prepare("SELECT body FROM warlock_queue_jobs WHERE namespace = ? AND queue = ? ORDER BY seq").all(this.namespace, queue)).flatMap((row) => {
+			const job = decode(row);
+			return job ? [job] : [];
+		});
+	}
+	ready(queue, now) {
+		return decode(this.db.prepare(`SELECT body FROM warlock_queue_jobs
+      WHERE namespace = ? AND queue = ? AND (
+        (state IN ('waiting', 'delayed', 'prioritized') AND ready_at <= ?) OR
+        (state = 'active' AND lease_until <= ?)
+      ) ORDER BY priority, seq LIMIT 1`).get(this.namespace, queue, now, now));
+	}
+	put(job) {
+		this.db.prepare(`INSERT INTO warlock_queue_jobs
+      (namespace, queue, id, state, ready_at, lease_until, priority, body)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(namespace, queue, id) DO UPDATE SET
+        state = excluded.state, ready_at = excluded.ready_at,
+        lease_until = excluded.lease_until, priority = excluded.priority, body = excluded.body`).run(this.namespace, job.queue, job.id, job.state, job.readyAt, job.leaseUntil, job.priority, JSON.stringify(job));
+	}
+	remove(queue, id) {
+		this.db.prepare("DELETE FROM warlock_queue_jobs WHERE namespace = ? AND queue = ? AND id = ?").run(this.namespace, queue, id);
+	}
+	close() {
+		this.db.close();
+	}
+};
+function decode(row) {
+	return typeof row?.body === "string" ? JSON.parse(row.body) : void 0;
+}
+
+//#endregion
+//#region ../../packages/queue/src/queue-driver.ts
+let activeDriver;
+/** The configured backend, created on first use. Close it before changing config. */
+function getQueueDriver() {
+	if (!activeDriver) {
+		const config = getQueueConfig();
+		switch (config.driver ?? "bullmq") {
+			case "bullmq":
+				activeDriver = new BullMQDriver(config);
+				break;
+			case "local":
+				activeDriver = new LocalDriver(new SqliteStore(config), config);
+				break;
+			case "memory":
+				activeDriver = new LocalDriver(new MemoryStore(), config);
+				break;
+			default: throw new Error(`Unknown queue driver: ${String(config.driver)}`);
+		}
+	}
+	return activeDriver;
+}
+function currentQueueDriver() {
+	return activeDriver;
+}
+function forgetQueueDriver() {
+	activeDriver = void 0;
+}
+
+//#endregion
+//#region ../../packages/queue/src/queue-manager.ts
+let stopListening;
+let closing;
+/** Low-level BullMQ access. For portable operations use defineJob / failedJobs. */
+function getQueue(name) {
+	const driver = getQueueDriver();
+	if (!(driver instanceof BullMQDriver)) throw new Error("getQueue() requires the bullmq queue driver.");
+	return driver.getQueue(name);
+}
+/** Start workers for registered queues, honouring process roles and workers.enabled. */
 async function startWorkers() {
+	if (closing) await closing;
 	const { Application } = await import("@warlock.js/core");
 	if (!Application.hasRole("worker")) {
 		_warlock_js_logger.log.info("queue", "workers", `queue: workers not started (role: ${[...Application.roles].join(",")})`);
 		return [];
 	}
 	if (getQueueConfig().workers?.enabled === false) return [];
-	for (const job of registeredJobs()) ensureWorker(queueOf(job));
+	const driver = getQueueDriver();
 	stopListening ??= onJobRegistered((job) => {
-		ensureWorker(queueOf(job));
+		driver.start(queueOf(job)).catch((error) => _warlock_js_logger.log.error("queue", "worker", error));
 	});
-	await Promise.all([...workers.values()].map((worker) => worker.waitUntilReady()));
-	return [...workers.keys()];
+	await Promise.all([...new Set(registeredJobs().map(queueOf))].map((queue) => driver.start(queue)));
+	return driver.running();
 }
-/** The queue names with a running worker in this process. */
+/** Names of queues with workers in this process. */
 function runningWorkers() {
-	return [...workers.keys()];
-}
-function ensureWorker(queueName) {
-	if (workers.has(queueName)) return;
-	const config = getQueueConfig();
-	const worker = new bullmq.Worker(queueName, processJob, {
-		connection: config.connection,
-		prefix: config.prefix ?? "warlock",
-		concurrency: config.workers?.concurrency ?? 1
-	});
-	worker.on("error", (error) => {
-		_warlock_js_logger.log.error("queue", "worker", error);
-	});
-	worker.on("failed", (job, error) => {
-		_warlock_js_logger.log.error("queue", "job.failed", `${job?.name ?? "unknown"} (${job?.id ?? "?"}): ${error.message}`);
-	});
-	workers.set(queueName, worker);
+	return currentQueueDriver()?.running() ?? [];
 }
-/**
-* Graceful shutdown: stop workers taking new jobs and wait for active ones
-* (bounded by `timeout`, then force-close), then close every queue
-* connection. Safe to call when nothing was started, and more than once.
-*/
-async function closeQueue(options = {}) {
+/** Stop taking jobs, drain active handlers, then release leases and close storage. */
+function closeQueue(options = {}) {
+	if (closing) return closing;
 	stopListening?.();
 	stopListening = void 0;
+	const driver = currentQueueDriver();
+	if (!driver) return Promise.resolve();
 	const timeout = options.timeout ?? configuredShutdownTimeout();
-	const closingWorkers = [...workers.values()];
-	workers.clear();
-	await Promise.all(closingWorkers.map((worker) => closeWorker(worker, timeout)));
-	const closingQueues = [...queues.values()];
-	queues.clear();
-	await Promise.all(closingQueues.map((queue) => queue.close()));
+	if (!Number.isFinite(timeout) || timeout < 0) return Promise.reject(/* @__PURE__ */ new Error("Queue shutdown timeout must be non-negative and finite."));
+	closing = driver.close(timeout).finally(() => {
+		forgetQueueDriver();
+		closing = void 0;
+	});
+	return closing;
 }
 function configuredShutdownTimeout() {
 	try {
-		return getQueueConfig().workers?.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT;
+		return getQueueConfig().workers?.shutdownTimeout ?? 3e4;
 	} catch {
-		return DEFAULT_SHUTDOWN_TIMEOUT;
-	}
-}
-async function closeWorker(worker, timeout) {
-	let timer;
-	const timedOut = new Promise((resolve) => {
-		timer = setTimeout(() => resolve("timeout"), timeout);
-	});
-	const closing = worker.close().then(() => "closed");
-	closing.catch(() => void 0);
-	const outcome = await Promise.race([closing, timedOut]);
-	clearTimeout(timer);
-	if (outcome === "timeout") {
-		_warlock_js_logger.log.warn("queue", "shutdown", `Worker for "${worker.name}" still had active jobs after ${timeout}ms; disconnecting. Those jobs are retried once their lock expires.`);
-		await worker.disconnect();
+		return 3e4;
 	}
 }
 
@@ -402,6 +935,7 @@ async function closeWorker(worker, timeout) {
 * await queueDashboard(getHttpServer(), { basePath: "/admin/queues" });
 */
 async function queueDashboard(server, options = {}) {
+	if ((getQueueConfig().driver ?? "bullmq") !== "bullmq") throw new Error("The bull-board dashboard requires the bullmq queue driver. Use job.find() and failedJobs() with local or memory queues.");
 	const basePath = options.basePath ?? "/admin/queues";
 	const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();
 	const queueNames = options.queues ?? [.../* @__PURE__ */ new Set([defaultQueueName(), ...registeredJobs().map((job) => queueOf(job))])];
@@ -473,6 +1007,7 @@ const DEFAULT_DASHBOARD_PATH = "/admin/queues";
 async function mountQueueDashboard(server, config) {
 	const dashboard = config.dashboard;
 	if (!dashboard?.enabled) return;
+	if ((config.driver ?? "bullmq") !== "bullmq") throw new Error("The bull-board dashboard requires the bullmq queue driver.");
 	const middlewareList = dashboard.middleware ?? [];
 	if (middlewareList.length === 0) {
 		if (process.env.NODE_ENV === "production") throw new QueueDashboardUnguardedError();
@@ -524,6 +1059,21 @@ function toMilliseconds(value) {
 	return Math.round(Number(match[1]) * UNIT_MILLISECONDS[match[2]]);
 }
 
+//#endregion
+//#region ../../packages/queue/src/job-options.ts
+function resolveJobOptions(definition, options) {
+	const defaults = getQueueConfig().defaultJobOptions ?? {};
+	return {
+		attempts: options.attempts ?? definition.attempts ?? defaults.attempts,
+		backoff: options.backoff ?? definition.backoff ?? defaults.backoff,
+		removeOnComplete: definition.removeOnComplete ?? defaults.removeOnComplete,
+		removeOnFail: definition.removeOnFail ?? defaults.removeOnFail,
+		delay: options.delay === void 0 ? void 0 : toMilliseconds(options.delay),
+		priority: options.priority,
+		jobId: options.jobId
+	};
+}
+
 //#endregion
 //#region ../../packages/queue/src/define-job.ts
 /**
@@ -562,12 +1112,12 @@ function defineJob(definition) {
 				options
 			});
 			const captured = definition.context === false ? void 0 : getQueueContext()?.capture();
-			const job = await getQueue(queueName).add(definition.name, wrapPayload(payload, captured), toBullJobOptions(definition, options));
-			return {
-				id: String(job.id),
+			return getQueueDriver().dispatch({
 				name: definition.name,
-				queue: queueName
-			};
+				queue: queueName,
+				data: wrapPayload(payload, captured),
+				options: resolveJobOptions(definition, options)
+			});
 		},
 		async find(id) {
 			const interceptor = getDispatchInterceptor();
@@ -576,11 +1126,8 @@ function defineJob(definition) {
 				queue: queueOf(definition),
 				id
 			});
-			const queue = getQueue(queueOf(definition));
-			const initialJob = await queue.getJob(id);
-			if (!initialJob || initialJob.name !== definition.name) return;
-			const state = await initialJob.getState();
-			return toSnapshot(await queue.getJob(id) ?? initialJob, state);
+			const snapshot = await getQueueDriver().find(queueOf(definition), id);
+			return snapshot?.name === definition.name ? snapshot : void 0;
 		}
 	};
 }
@@ -589,88 +1136,16 @@ function assertValidDefinition(definition) {
 	if (typeof definition.handle !== "function") throw new InvalidJobDefinitionError(`defineJob("${definition.name}") requires a \`handle(payload, ctx)\` function.`);
 	if (definition.attempts !== void 0 && !(Number.isInteger(definition.attempts) && definition.attempts >= 1)) throw new InvalidJobDefinitionError(`defineJob("${definition.name}"): \`attempts\` must be an integer >= 1, got ${definition.attempts}.`);
 }
-/**
-* Merge app defaults < job definition < dispatch options into BullMQ's shape.
-*/
-function toBullJobOptions(definition, options) {
-	const defaults = getQueueConfig().defaultJobOptions ?? {};
-	const attempts = options.attempts ?? definition.attempts ?? defaults.attempts;
-	const backoff = options.backoff ?? definition.backoff ?? defaults.backoff;
-	const removeOnComplete = definition.removeOnComplete ?? defaults.removeOnComplete;
-	const removeOnFail = definition.removeOnFail ?? defaults.removeOnFail;
-	const bullOptions = {};
-	if (attempts !== void 0) bullOptions.attempts = attempts;
-	if (backoff !== void 0) bullOptions.backoff = toBullBackoff(backoff);
-	if (removeOnComplete !== void 0) bullOptions.removeOnComplete = removeOnComplete;
-	if (removeOnFail !== void 0) bullOptions.removeOnFail = removeOnFail;
-	if (options.delay !== void 0) bullOptions.delay = toMilliseconds(options.delay);
-	if (options.priority !== void 0) bullOptions.priority = options.priority;
-	if (options.jobId !== void 0) bullOptions.jobId = options.jobId;
-	return bullOptions;
-}
-function toBullBackoff(backoff) {
-	return typeof backoff === "number" ? {
-		type: "fixed",
-		delay: backoff
-	} : backoff;
-}
-/**
-* A plain view of a BullMQ job.
-*
-* @param job The job to read fields from.
-* @param state The job's state; pass a state read *before* `job` was
-* fetched (or re-fetched) so the returned snapshot's fields are consistent
-* with it. If omitted, the state is read from `job` directly.
-*/
-async function toSnapshot(job, state) {
-	const resolvedState = state ?? await job.getState();
-	return {
-		id: String(job.id),
-		name: job.name,
-		queue: job.queueName,
-		state: resolvedState,
-		payload: unwrapPayload(job.data).payload,
-		progress: job.progress,
-		attemptsMade: job.attemptsMade,
-		result: job.returnvalue,
-		failedReason: job.failedReason || void 0,
-		createdAt: new Date(job.timestamp),
-		finishedAt: job.finishedOn ? new Date(job.finishedOn) : void 0
-	};
-}
 
 //#endregion
 //#region ../../packages/queue/src/failed-jobs.ts
-/**
-* List failed jobs, newest first — jobs that used up every attempt, or
-* failed unrecoverably. Each entry can be retried.
-*/
+/** List failed jobs, newest first, using the selected driver. */
 async function failedJobs(options = {}) {
-	const queueName = options.queue ?? defaultQueueName();
-	return (await getQueue(queueName).getFailed(options.start ?? 0, options.end ?? 99)).map((job) => toFailedJob(job));
+	return getQueueDriver().failed(options.queue ?? defaultQueueName(), options.start ?? 0, options.end ?? 99);
 }
-/**
-* Retry one failed job by id: it goes back to waiting with its attempts reset.
-* Throws {@link FailedJobNotFoundError} when no FAILED job has that id.
-*/
+/** Move a failed job back to waiting, resetting its attempts. */
 async function retryFailedJob(id, options = {}) {
-	const queueName = options.queue ?? defaultQueueName();
-	const job = await getQueue(queueName).getJob(id);
-	if (!job || !await job.isFailed()) throw new FailedJobNotFoundError(id, queueName);
-	await job.retry("failed");
-}
-function toFailedJob(job) {
-	return {
-		id: String(job.id),
-		name: job.name,
-		queue: job.queueName,
-		payload: unwrapPayload(job.data).payload,
-		attemptsMade: job.attemptsMade,
-		failedReason: job.failedReason,
-		stacktrace: job.stacktrace ?? [],
-		failedAt: job.finishedOn ? new Date(job.finishedOn) : void 0,
-		retry: () => job.retry("failed")
-	};
+	await getQueueDriver().retry(options.queue ?? defaultQueueName(), id);
 }
 
 //#endregion
@@ -774,6 +1249,7 @@ exports.getDispatchInterceptor = getDispatchInterceptor;
 exports.getQueue = getQueue;
 exports.getQueueConfig = getQueueConfig;
 exports.getQueueContext = getQueueContext;
+exports.getQueueDriver = getQueueDriver;
 exports.loadBullBoard = loadBullBoard;
 exports.mountQueueDashboard = mountQueueDashboard;
 exports.queueConnector = queueConnector;