@warlock.js/queue 5.14.0 → 5.16.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@warlock.js/queue` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.16.0 - 2026-09-18
+
+### Fixed
+
+- The failed-jobs dashboard skill sample now includes the connection config and the `authMiddleware` import.
+
+## 5.15.0 - 2026-09-18
+
+### BREAKING
+
+- Removed `@warlock.js/queue/notifications` (`queueNotificationDispatcher`), deprecated in 5.14. Use `bullmqQueue()` from `@warlock.js/notifications` instead. The `@warlock.js/notifications` peer dependency is also dropped, since this was the only thing in the package that needed it.
+
+### Fixed
+
+- The dashboard guard now ends the request explicitly when a middleware short-circuits, instead of leaving it to Fastify noticing the reply was already sent. The adapter has always returned a "handled" boolean for this; the hook discarded it, so whether an unauthenticated caller reached the dashboard depended on write ordering — a guard answering asynchronously could lose that race.
+
 ## 5.14.0 - 2026-09-17
 
 ### Added

package/README.md

@@ -106,9 +106,6 @@ const config: NotificationConfig = {
 `@warlock.js/queue` is dynamically imported the first time `.queue()` runs —
 notifications never pays for it unless `bullmqQueue()` is configured.
 
-> **Deprecated:** `queueNotificationDispatcher` from `@warlock.js/queue/notifications`
-> still works for this release (it logs a one-time deprecation warning) and is
-> removed in the next one. Switch to `bullmqQueue` above.
 
 ## Dashboard (optional)
 

package/cjs/index.cjs

@@ -1,7 +1,88 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_define_job = require('./define-job-33RNLEqL.cjs');
 let _warlock_js_logger = require("@warlock.js/logger");
+let bullmq = require("bullmq");
 
+//#region ../queue/src/errors.ts
+/**
+* Thrown when the queue is used before `setQueueConfig` (or the queue
+* connector) supplied a configuration.
+*/
+var QueueNotConfiguredError = class extends Error {
+	constructor() {
+		super("@warlock.js/queue is not configured. Add src/config/queue.ts exporting a QueueConfig and register queueConnector() in warlock.config.ts > connectors, or call setQueueConfig() yourself.");
+		this.name = "QueueNotConfiguredError";
+	}
+};
+/**
+* Thrown for a malformed duration such as `"10 minutes"`.
+*/
+var InvalidDurationError = class extends Error {
+	constructor(value) {
+		super(`Invalid duration ${JSON.stringify(value)}: expected milliseconds as a non-negative number or a string like "500ms", "30s", "10m", "2h", "1d".`);
+		this.name = "InvalidDurationError";
+	}
+};
+/**
+* Thrown by `defineJob` for an invalid definition.
+*/
+var InvalidJobDefinitionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "InvalidJobDefinitionError";
+	}
+};
+/**
+* Thrown by `retryFailedJob` when no failed job has the given id.
+*/
+var FailedJobNotFoundError = class extends Error {
+	constructor(id, queue) {
+		super(`No failed job with id "${id}" on queue "${queue}".`);
+		this.name = "FailedJobNotFoundError";
+	}
+};
+/**
+* Thrown by `queueDashboard` when an optional bull-board package is not
+* installed.
+*/
+var QueueDashboardDependencyError = class extends Error {
+	constructor(missing) {
+		super(`The queue dashboard needs the optional package "${missing}", which is not installed.\nInstall both bull-board packages:
+
+  npm install @bull-board/api @bull-board/fastify
+`);
+		this.name = "QueueDashboardDependencyError";
+	}
+};
+
+//#endregion
+//#region ../queue/src/config.ts
+let activeConfig;
+/**
+* Set the active queue configuration. In a Warlock app the queue connector
+* calls this at boot with `src/config/queue.ts`; scripts and tests may call
+* it directly. Replaces (does not merge) any previous configuration.
+*/
+function setQueueConfig(config) {
+	activeConfig = config;
+}
+/**
+* The active queue configuration. Throws {@link QueueNotConfiguredError}
+* when none was set.
+*/
+function getQueueConfig() {
+	if (!activeConfig) throw new QueueNotConfiguredError();
+	return activeConfig;
+}
+/** Forget the active configuration. */
+function resetQueueConfig() {
+	activeConfig = void 0;
+}
+/** The queue a job runs on when it names none. */
+function defaultQueueName() {
+	return activeConfig?.defaultQueue ?? "default";
+}
+
+//#endregion
 //#region ../queue/src/dashboard-middleware-adapter.ts
 /**
 * Run a Warlock middleware list against a raw Fastify request/reply pair.
@@ -55,13 +136,176 @@ async function runDashboardMiddleware(middlewareList, fastifyRequest, fastifyRep
 function buildDashboardGuardPlugin(middlewareList, bullBoardPlugin) {
 	return function dashboardGuardPlugin(instance, _options, done) {
 		if (middlewareList.length > 0) instance.addHook("onRequest", async (request, reply) => {
-			await runDashboardMiddleware(middlewareList, request, reply);
+			if (await runDashboardMiddleware(middlewareList, request, reply)) return reply;
 		});
 		instance.register(bullBoardPlugin);
 		done();
 	};
 }
 
+//#endregion
+//#region ../queue/src/job-registry.ts
+const jobs = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Set();
+/**
+* Register a definition under its name.
+*
+* Re-registering a name REPLACES the previous definition: in development a
+* job module is re-evaluated on every reload, and refusing the second
+* evaluation would break the reload. Job names must therefore be unique
+* across the app — two different modules using one name leave only the
+* later handler active.
+*/
+function registerJob(job) {
+	jobs.set(job.name, job);
+	for (const listener of listeners) listener(job);
+}
+/** The definition registered under `name`, if any. */
+function findRegisteredJob(name) {
+	return jobs.get(name);
+}
+/** Every registered definition. */
+function registeredJobs() {
+	return [...jobs.values()];
+}
+/** The queue a definition runs on, resolved against the active config. */
+function queueOf(job) {
+	return job.queue ?? defaultQueueName();
+}
+/** Be told whenever a job is registered. Returns an unsubscribe function. */
+function onJobRegistered(listener) {
+	listeners.add(listener);
+	return () => listeners.delete(listener);
+}
+
+//#endregion
+//#region ../queue/src/process-job.ts
+/**
+* The single BullMQ processor every worker runs: route the job to the
+* handler registered under its name.
+*
+* A name with no handler in this process fails with `UnrecoverableError` —
+* retrying cannot make a missing definition appear, so it must not burn
+* through its attempts.
+*/
+async function processJob(job) {
+	const definition = findRegisteredJob(job.name);
+	if (!definition) throw new bullmq.UnrecoverableError(`No job named "${job.name}" is defined in this process. Make sure the module that calls defineJob() is imported by the worker process.`);
+	const context = {
+		id: String(job.id),
+		name: job.name,
+		queue: job.queueName,
+		attempt: job.attemptsMade + 1,
+		maxAttempts: job.opts.attempts ?? 1,
+		progress: (value) => job.updateProgress(value),
+		log: async (line) => {
+			await job.log(line);
+		}
+	};
+	return definition.handle(job.data, context);
+}
+
+//#endregion
+//#region ../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"
+		});
+		queue.on("error", (error) => {
+			_warlock_js_logger.log.error("queue", "connection", error);
+		});
+		queues.set(name, queue);
+	}
+	return queue;
+}
+/**
+* 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`. Calling it again
+* while workers run starts only the missing ones.
+*
+* @returns the queue names that now have a worker in this process.
+*/
+async function startWorkers() {
+	if (getQueueConfig().workers?.enabled === false) return [];
+	for (const job of registeredJobs()) ensureWorker(queueOf(job));
+	stopListening ??= onJobRegistered((job) => {
+		ensureWorker(queueOf(job));
+	});
+	await Promise.all([...workers.values()].map((worker) => worker.waitUntilReady()));
+	return [...workers.keys()];
+}
+/** The queue names with a running worker 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);
+}
+/**
+* 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 = {}) {
+	stopListening?.();
+	stopListening = void 0;
+	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()));
+}
+function configuredShutdownTimeout() {
+	try {
+		return getQueueConfig().workers?.shutdownTimeout ?? DEFAULT_SHUTDOWN_TIMEOUT;
+	} 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();
+	}
+}
+
 //#endregion
 //#region ../queue/src/dashboard.ts
 /**
@@ -80,11 +324,11 @@ function buildDashboardGuardPlugin(middlewareList, bullBoardPlugin) {
 async function queueDashboard(server, options = {}) {
 	const basePath = options.basePath ?? "/admin/queues";
 	const { createBullBoard, BullMQAdapter, FastifyAdapter } = await loadBullBoard();
-	const queueNames = options.queues ?? [...new Set([require_define_job.defaultQueueName(), ...require_define_job.registeredJobs().map((job) => require_define_job.queueOf(job))])];
+	const queueNames = options.queues ?? [...new Set([defaultQueueName(), ...registeredJobs().map((job) => queueOf(job))])];
 	const serverAdapter = new FastifyAdapter();
 	serverAdapter.setBasePath(basePath);
 	createBullBoard({
-		queues: queueNames.map((name) => new BullMQAdapter(require_define_job.getQueue(name))),
+		queues: queueNames.map((name) => new BullMQAdapter(getQueue(name))),
 		serverAdapter
 	});
 	const guardedPlugin = buildDashboardGuardPlugin(options.middleware ?? [], serverAdapter.registerPlugin());
@@ -108,7 +352,7 @@ async function importOptional(importer, specifier) {
 	try {
 		return await importer(specifier);
 	} catch (error) {
-		if (isModuleNotFound(error)) throw new require_define_job.QueueDashboardDependencyError(specifier.split("/").slice(0, 2).join("/"));
+		if (isModuleNotFound(error)) throw new QueueDashboardDependencyError(specifier.split("/").slice(0, 2).join("/"));
 		throw error;
 	}
 }
@@ -164,6 +408,131 @@ async function mountQueueDashboard(server, config) {
 	});
 }
 
+//#endregion
+//#region ../queue/src/duration.ts
+const UNIT_MILLISECONDS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+const DURATION_PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/;
+/**
+* Convert a {@link Duration} to milliseconds. Numbers are already
+* milliseconds. Anything else is rejected loudly rather than guessed at.
+*/
+function toMilliseconds(value) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value < 0) throw new InvalidDurationError(value);
+		return Math.round(value);
+	}
+	const match = typeof value === "string" ? DURATION_PATTERN.exec(value.trim()) : null;
+	if (!match) throw new InvalidDurationError(value);
+	return Math.round(Number(match[1]) * UNIT_MILLISECONDS[match[2]]);
+}
+
+//#endregion
+//#region ../queue/src/define-job.ts
+/**
+* Define a background job.
+*
+* The definition is registered by name so any worker in the process can run
+* it; the returned object dispatches it with a typed payload.
+*
+* @example
+* export const sendInvoice = defineJob({
+*   name: "invoices.send",
+*   attempts: 5,
+*   backoff: { type: "exponential", delay: 2000 },
+*   async handle(payload: { invoiceId: string }, ctx) {
+*     await ctx.progress(50);
+*   },
+* });
+*
+* await sendInvoice.dispatch({ invoiceId: "42" }, { delay: "10m", priority: 1 });
+*/
+function defineJob(definition) {
+	assertValidDefinition(definition);
+	registerJob(definition);
+	return {
+		name: definition.name,
+		get queue() {
+			return queueOf(definition);
+		},
+		async dispatch(payload, options = {}) {
+			const queueName = queueOf(definition);
+			const job = await getQueue(queueName).add(definition.name, payload, toBullJobOptions(definition, options));
+			return {
+				id: String(job.id),
+				name: definition.name,
+				queue: queueName
+			};
+		},
+		async find(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);
+		}
+	};
+}
+function assertValidDefinition(definition) {
+	if (typeof definition.name !== "string" || definition.name.trim() === "") throw new InvalidJobDefinitionError("defineJob() requires a non-empty `name`.");
+	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: job.data,
+		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 ../queue/src/failed-jobs.ts
 /**
@@ -171,16 +540,16 @@ async function mountQueueDashboard(server, config) {
 * failed unrecoverably. Each entry can be retried.
 */
 async function failedJobs(options = {}) {
-	return (await require_define_job.getQueue(options.queue ?? require_define_job.defaultQueueName()).getFailed(options.start ?? 0, options.end ?? 99)).map((job) => toFailedJob(job));
+	return (await getQueue(options.queue ?? defaultQueueName()).getFailed(options.start ?? 0, options.end ?? 99)).map((job) => toFailedJob(job));
 }
 /**
 * 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.
 */
 async function retryFailedJob(id, options = {}) {
-	const queueName = options.queue ?? require_define_job.defaultQueueName();
-	const job = await require_define_job.getQueue(queueName).getJob(id);
-	if (!job || !await job.isFailed()) throw new require_define_job.FailedJobNotFoundError(id, queueName);
+	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) {
@@ -240,7 +609,7 @@ function queueConnector(options = {}) {
 		async boot() {
 			const queueConfig = options.config ?? await readQueueConfig();
 			if (!queueConfig?.dashboard?.enabled) return;
-			require_define_job.setQueueConfig(queueConfig);
+			setQueueConfig(queueConfig);
 			const { getHttpServer } = await import("@warlock.js/core");
 			await mountQueueDashboard(getHttpServer(), queueConfig);
 		},
@@ -250,8 +619,8 @@ function queueConnector(options = {}) {
 				_warlock_js_logger.log.warn("queue", "configured", "queueConnector() is registered but no `queue` config was found (src/config/queue.ts); queue not started");
 				return;
 			}
-			require_define_job.setQueueConfig(queueConfig);
-			const started = await require_define_job.startWorkers();
+			setQueueConfig(queueConfig);
+			const started = await startWorkers();
 			active = true;
 			_warlock_js_logger.log.info("queue", "configured", started.length > 0 ? `Queue workers running for: ${started.join(", ")}` : "Queue configured (no in-process workers)");
 		},
@@ -261,8 +630,8 @@ function queueConnector(options = {}) {
 		},
 		async shutdown() {
 			if (!active) return;
-			await require_define_job.closeQueue();
-			require_define_job.resetQueueConfig();
+			await closeQueue();
+			resetQueueConfig();
 			active = false;
 		},
 		shouldRestart(changedFiles) {
@@ -281,27 +650,27 @@ async function readQueueConfig() {
 
 //#endregion
 exports.DEFAULT_DASHBOARD_PATH = DEFAULT_DASHBOARD_PATH;
-exports.FailedJobNotFoundError = require_define_job.FailedJobNotFoundError;
-exports.InvalidDurationError = require_define_job.InvalidDurationError;
-exports.InvalidJobDefinitionError = require_define_job.InvalidJobDefinitionError;
+exports.FailedJobNotFoundError = FailedJobNotFoundError;
+exports.InvalidDurationError = InvalidDurationError;
+exports.InvalidJobDefinitionError = InvalidJobDefinitionError;
 exports.QUEUE_CONNECTOR_PRIORITY = QUEUE_CONNECTOR_PRIORITY;
-exports.QueueDashboardDependencyError = require_define_job.QueueDashboardDependencyError;
+exports.QueueDashboardDependencyError = QueueDashboardDependencyError;
 exports.QueueDashboardUnguardedError = QueueDashboardUnguardedError;
-exports.QueueNotConfiguredError = require_define_job.QueueNotConfiguredError;
-exports.closeQueue = require_define_job.closeQueue;
-exports.defaultQueueName = require_define_job.defaultQueueName;
-exports.defineJob = require_define_job.defineJob;
+exports.QueueNotConfiguredError = QueueNotConfiguredError;
+exports.closeQueue = closeQueue;
+exports.defaultQueueName = defaultQueueName;
+exports.defineJob = defineJob;
 exports.failedJobs = failedJobs;
-exports.getQueue = require_define_job.getQueue;
-exports.getQueueConfig = require_define_job.getQueueConfig;
+exports.getQueue = getQueue;
+exports.getQueueConfig = getQueueConfig;
 exports.loadBullBoard = loadBullBoard;
 exports.mountQueueDashboard = mountQueueDashboard;
 exports.queueConnector = queueConnector;
 exports.queueDashboard = queueDashboard;
-exports.resetQueueConfig = require_define_job.resetQueueConfig;
+exports.resetQueueConfig = resetQueueConfig;
 exports.retryFailedJob = retryFailedJob;
-exports.runningWorkers = require_define_job.runningWorkers;
-exports.setQueueConfig = require_define_job.setQueueConfig;
-exports.startWorkers = require_define_job.startWorkers;
-exports.toMilliseconds = require_define_job.toMilliseconds;
+exports.runningWorkers = runningWorkers;
+exports.setQueueConfig = setQueueConfig;
+exports.startWorkers = startWorkers;
+exports.toMilliseconds = toMilliseconds;
 //# sourceMappingURL=index.cjs.map