@c9up/bay 0.1.11 → 0.1.13

package/src/QueueManager.ts

@@ -40,19 +40,22 @@ export interface QueueDriver {
 }
 
 export class QueueManager {
-	private driver: QueueDriver;
-	private handlers: Map<string, JobHandler | (new () => JobHandler)> =
-		new Map();
-	private running = false;
-	private inflightPromise: Promise<boolean> | null = null;
+	#driver: QueueDriver;
+	#handlers: Map<string, JobHandler | (new () => JobHandler)> = new Map();
+	#running = false;
+	/** The running loop, so `stop()` can wait for it to finish. */
+	#loopPromise: Promise<void> | undefined;
+	/** Cuts the sleep between polls short. */
+	#wake: (() => void) | undefined;
+	#inflightPromise: Promise<boolean> | null = null;
 
 	constructor(driver: QueueDriver) {
-		this.driver = driver;
+		this.#driver = driver;
 	}
 
 	/** Register a job handler. */
 	register(name: string, handler: JobHandler | (new () => JobHandler)): void {
-		this.handlers.set(name, handler);
+		this.#handlers.set(name, handler);
 	}
 
 	/** Dispatch a job to the queue. */
@@ -74,21 +77,24 @@ export class QueueManager {
 			status: "pending",
 			createdAt: Date.now(),
 		};
-		await this.driver.push(job);
+		await this.#driver.push(job);
 		return id;
 	}
 
 	/** Process the next job in the queue. */
 	async processOne(): Promise<boolean> {
-		const job = await this.driver.pop();
+		const job = await this.#driver.pop();
 		if (!job) return false;
 
-		const handlerOrClass = this.handlers.get(job.name);
+		const handlerOrClass = this.#handlers.get(job.name);
 		if (!handlerOrClass) {
 			process.stderr.write(
 				`QueueManager: no handler registered for job '${job.name}'\n`,
 			);
-			await this.driver.fail(job, `No handler registered for job: ${job.name}`);
+			await this.#driver.fail(
+				job,
+				`No handler registered for job: ${job.name}`,
+			);
 			return true;
 		}
 
@@ -103,16 +109,16 @@ export class QueueManager {
 		try {
 			await handler.handle(job.payload);
 			job.status = "completed";
-			await this.driver.complete(job);
+			await this.#driver.complete(job);
 		} catch (err) {
 			const errorMsg = err instanceof Error ? err.message : String(err);
 			if (job.attempts < job.maxAttempts) {
 				job.status = "pending";
-				await this.driver.retry(job);
+				await this.#driver.retry(job);
 			} else {
 				job.status = "failed";
 				job.error = errorMsg;
-				await this.driver.fail(job, errorMsg);
+				await this.#driver.fail(job, errorMsg);
 			}
 		}
 
@@ -132,34 +138,65 @@ export class QueueManager {
 		if (recoverStaleMs <= 0) {
 			throw new Error("recoverStaleMs must be positive");
 		}
-		if (this.running) {
+		if (this.#running) {
 			throw new Error("QueueManager is already running");
 		}
-		this.running = true;
+		this.#running = true;
+		const loop = this.#loop(pollIntervalMs, recoverStaleMs);
+		this.#loopPromise = loop;
+		try {
+			await loop;
+		} finally {
+			this.#loopPromise = undefined;
+		}
+	}
+
+	/**
+	 * The polling loop itself.
+	 *
+	 * Between jobs it sleeps, and that sleep is CANCELLABLE: `stop()` wakes it
+	 * rather than waiting out the interval. Without that, stopping returned
+	 * while the loop was still pending — up to a full poll interval of a worker
+	 * that was supposed to be gone, and a timer holding the process open.
+	 */
+	async #loop(pollIntervalMs: number, recoverStaleMs: number): Promise<void> {
 		await this.#tryRecoverStale();
 		let lastRecover = Date.now();
-		while (this.running) {
+		while (this.#running) {
 			try {
-				this.inflightPromise = this.processOne();
-				const processed = await this.inflightPromise;
-				if (!processed) {
-					await new Promise((r) => setTimeout(r, pollIntervalMs));
-				}
+				this.#inflightPromise = this.processOne();
+				const processed = await this.#inflightPromise;
+				if (!processed) await this.#sleep(pollIntervalMs);
 			} catch (err) {
 				process.stderr.write(
 					`QueueManager processOne error: ${err instanceof Error ? err.message : String(err)}\n`,
 				);
-				await new Promise((r) => setTimeout(r, pollIntervalMs));
+				await this.#sleep(pollIntervalMs);
 			} finally {
-				this.inflightPromise = null;
+				this.#inflightPromise = null;
 			}
-			if (this.running && Date.now() - lastRecover >= recoverStaleMs) {
+			if (this.#running && Date.now() - lastRecover >= recoverStaleMs) {
 				await this.#tryRecoverStale();
 				lastRecover = Date.now();
 			}
 		}
 	}
 
+	/** Wait, unless `stop()` says otherwise first. */
+	#sleep(ms: number): Promise<void> {
+		return new Promise((resolve) => {
+			const timer = setTimeout(() => {
+				this.#wake = undefined;
+				resolve();
+			}, ms);
+			this.#wake = () => {
+				clearTimeout(timer);
+				this.#wake = undefined;
+				resolve();
+			};
+		});
+	}
+
 	/** recoverStale() wrapper that swallows driver errors — used by the work loop. */
 	async #tryRecoverStale(): Promise<void> {
 		try {
@@ -178,29 +215,37 @@ export class QueueManager {
 	 * Called automatically by work(); also safe to schedule manually.
 	 */
 	async recoverStale(): Promise<number> {
-		return (await this.driver.recoverStale?.()) ?? 0;
+		return (await this.#driver.recoverStale?.()) ?? 0;
 	}
 
 	/** Await the currently in-flight processOne, if any. */
 	async drain(): Promise<void> {
-		if (this.inflightPromise) {
-			await this.inflightPromise.catch(() => {});
+		if (this.#inflightPromise) {
+			await this.#inflightPromise.catch(() => {});
 		}
 	}
 
-	/** Stop the worker. */
+	/**
+	 * Stop the worker and wait for it to actually be gone.
+	 *
+	 * Awaits the LOOP, not just the job in flight: a stop that returns while
+	 * the loop is still sleeping leaves a worker running past the teardown that
+	 * asked it to stop.
+	 */
 	async stop(): Promise<void> {
-		this.running = false;
+		this.#running = false;
+		this.#wake?.();
 		await this.drain();
+		if (this.#loopPromise) await this.#loopPromise.catch(() => {});
 	}
 
 	/** Get failed jobs. */
 	async failedJobs(): Promise<Job[]> {
-		return this.driver.failed();
+		return this.#driver.failed();
 	}
 
 	/** Get queue size. */
 	async size(): Promise<number> {
-		return this.driver.size();
+		return this.#driver.size();
 	}
 }

package/src/configure.ts

@@ -0,0 +1,45 @@
+/**
+ * `ream configure @c9up/bay` — wire the job queue in one command.
+ *
+ * The provider alone is not enough: it reads `config/queue.ts`, and a package
+ * registered without one falls back to a default that is rarely the one an
+ * application wants. Writing both together is what makes `ream add` mean
+ * installed AND working.
+ */
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	// The config below reads these, so they are declared here. Writing the file
+	// without them leaves an application whose config asks the environment for
+	// something nothing ever put there.
+	await codemods.addEnvVars({
+		QUEUE_STORE: "memory",
+	});
+
+	await codemods.addProvider("@c9up/bay/provider");
+	await codemods.writeFile(
+		"config/queue.ts",
+		`import { defineConfig, stores } from '@c9up/bay'
+import env from '#start/env'
+
+export default defineConfig({
+  // Which store to run on. Memory forgets everything on restart, which is
+  // what a single process in development wants and nothing else does.
+  default: env.get('QUEUE_STORE', 'memory'),
+
+  stores: {
+    memory: stores.memory(),
+    redis: stores.redis({ connection: 'main' }),
+  },
+})`,
+	);
+}

package/src/drivers/RedisDriver.ts

@@ -18,6 +18,7 @@
  * needs a thin adapter.
  */
 
+import { inProduction } from "../nodeEnv.js";
 import type { Job, QueueDriver } from "../QueueManager.js";
 
 export interface RedisClient {
@@ -65,13 +66,35 @@ export type RedisClientSource =
  * has no client to inspect yet.
  */
 const warned = new WeakSet<object>();
-function warnWithoutLmove(client: RedisClient): void {
-	if (typeof client.lmove === "function" || warned.has(client)) return;
+function checkLmove(client: RedisClient, allowNonAtomicPop: boolean): void {
+	if (typeof client.lmove === "function") return;
+
+	// A queue's whole promise is that a job it accepted gets run. Without LMOVE
+	// the pop is `lpop` then `rpush`, and a crash between the two deletes the
+	// job from pending before it reaches processing: nothing recovers it,
+	// because nothing knows it existed. That is a different product, and in
+	// production it must be asked for rather than fallen into.
+	if (inProduction() && !allowNonAtomicPop) {
+		throw new Error(
+			"[bay] this Redis client has no LMOVE (Redis < 6.2), so pop() would be a non-atomic lpop+rpush — " +
+				"a crash between the two loses the in-flight job, turning at-least-once delivery into at-most-once.\n" +
+				"  Upgrade to Redis 6.2 or later, or pass `allowNonAtomicPop: true` to state that losing a job is acceptable here.",
+		);
+	}
+	if (warned.has(client)) return;
 	warned.add(client);
+
+	// Said even when the deployment opted in: agreeing to lose a job once, in a
+	// config file, is not the same as being reminded that this process is
+	// running that way. The line has to be in the logs of the incident.
+	const optedIn = inProduction() && allowNonAtomicPop;
 	console.warn(
 		"[bay] RedisDriver: client lacks LMOVE (Redis <6.2). pop() falls back to " +
 			"a non-atomic lpop+rpush, downgrading delivery from at-least-once to " +
-			"at-most-once — a crash between the two commands loses the in-flight job.",
+			"at-most-once — a crash between the two commands loses the in-flight job." +
+			(optedIn
+				? "\n  Running this way in PRODUCTION because allowNonAtomicPop was set."
+				: ""),
 	);
 }
 
@@ -101,7 +124,7 @@ export class RedisDriver implements QueueDriver {
 		if (this.#resolved) return this.#resolved;
 		if (typeof this.#source !== "function") {
 			this.#resolved = this.#source;
-			warnWithoutLmove(this.#resolved);
+			checkLmove(this.#resolved, this.#allowNonAtomicPop);
 			return this.#resolved;
 		}
 		if (!this.#pending) {
@@ -109,7 +132,7 @@ export class RedisDriver implements QueueDriver {
 			this.#pending = Promise.resolve(resolver())
 				.then((client) => {
 					this.#resolved = client;
-					warnWithoutLmove(client);
+					checkLmove(client, this.#allowNonAtomicPop);
 					return client;
 				})
 				// Cleared on failure too. Clearing only on success left the
@@ -125,18 +148,30 @@ export class RedisDriver implements QueueDriver {
 
 	constructor(
 		source: RedisClientSource,
-		options?: { prefix?: string; visibilityTimeoutMs?: number },
+		options?: {
+			prefix?: string;
+			visibilityTimeoutMs?: number;
+			/**
+			 * Accept the non-atomic pop on a Redis older than 6.2, in
+			 * production. Off by default: losing an accepted job is a choice a
+			 * deployment makes, not one a version check makes for it.
+			 */
+			allowNonAtomicPop?: boolean;
+		},
 	) {
 		this.#source = source;
 		// A client handed in directly can be checked now, so the warning keeps
 		// landing at construction as it always did. A named connection has no
 		// client yet — it is checked when the connection resolves.
-		if (typeof source !== "function") warnWithoutLmove(source);
+		if (typeof source !== "function") {
+			checkLmove(source, options?.allowNonAtomicPop ?? false);
+		}
 		// Normalised rather than documented: every key is built by concatenation
 		// (`${prefix}pending`), so a prefix without a trailing separator yields
 		// "myapppending" — unreadable, and able to collide with a neighbouring
 		// prefix. Nothing warned, because nothing failed.
 		this.#prefix = withSeparator(options?.prefix ?? "queue:");
+		this.#allowNonAtomicPop = options?.allowNonAtomicPop ?? false;
 		const visibilityTimeout = options?.visibilityTimeoutMs ?? 30_000;
 		// A non-positive / non-integer timeout makes pop()'s `SET … PX <ms>` fail
 		// on a real Redis; the catch then removes the job from `processing` and
@@ -152,6 +187,7 @@ export class RedisDriver implements QueueDriver {
 
 	#pendingKey = () => `${this.#prefix}pending`;
 	#processingKey = () => `${this.#prefix}processing`;
+	#allowNonAtomicPop = false;
 	#failedKey = () => `${this.#prefix}failed`;
 	#leaseKey = (jobId: string) => `${this.#prefix}lease:${jobId}`;
 
@@ -177,26 +213,37 @@ export class RedisDriver implements QueueDriver {
 		}
 
 		if (!raw) return null;
+
+		// Only a payload that can never be run is purged. Everything past this
+		// point is a REAL job that already sits in `processing`, and deleting
+		// it there is the one thing that loses it for good: it is gone from
+		// pending too, and recoverStale() scans processing, so nothing would
+		// ever find it again.
+		let parsed: unknown;
 		try {
-			const parsed: unknown = JSON.parse(raw);
-			if (!isValidJob(parsed)) {
-				// Malformed payload — purge from `processing` so it can't sit
-				// there indefinitely as a poison pill. recoverStale() also
-				// catches survivors but pop()'s own move is the primary path.
-				await client.lrem(this.#processingKey(), 1, raw);
-				return null;
-			}
-			await client.set(
-				this.#leaseKey(parsed.id),
-				raw,
-				"PX",
-				String(this.#visibilityTimeout),
-			);
-			return parsed;
+			parsed = JSON.parse(raw);
 		} catch {
+			// A poison pill: unparseable, and it would sit in processing
+			// forever blocking nothing but wasting every recovery pass.
+			await client.lrem(this.#processingKey(), 1, raw);
+			return null;
+		}
+		if (!isValidJob(parsed)) {
 			await client.lrem(this.#processingKey(), 1, raw);
 			return null;
 		}
+
+		// A lease that cannot be written is a transient Redis failure, not a
+		// bad job. The error propagates and the job STAYS in processing with
+		// no lease, which is precisely the state recoverStale() puts back in
+		// pending — so the delivery guarantee survives the blip.
+		await client.set(
+			this.#leaseKey(parsed.id),
+			raw,
+			"PX",
+			String(this.#visibilityTimeout),
+		);
+		return parsed;
 	}
 
 	async complete(job: Job): Promise<void> {

package/src/index.ts

@@ -12,6 +12,7 @@ export type { RedisClient } from "./drivers/RedisDriver.js";
 export { RedisDriver } from "./drivers/RedisDriver.js";
 export type { Job, JobHandler, QueueDriver } from "./QueueManager.js";
 export { QueueManager } from "./QueueManager.js";
+export { type QueueStoreFactory, stores } from "./stores.js";
 
 import type { BayProviderConfig } from "./BayProvider.js";
 

package/src/nodeEnv.ts

@@ -0,0 +1,30 @@
+/**
+ * Reading `NODE_ENV`, with the aliases people actually set.
+ *
+ * `NODE_ENV=prod` is ordinary in a Dockerfile or a platform dashboard. Read
+ * verbatim it answers "not production" — and here that decides whether a queue
+ * silently accepts a delivery guarantee weaker than the one it advertises.
+ *
+ * Duplicated rather than imported: bay depends on no other package in this
+ * workspace, and a safety decision that only holds when an optional peer is
+ * installed is not a decision.
+ */
+
+const DEV_ENVS = ["dev", "develop", "development"];
+const PROD_ENVS = ["prod", "production"];
+const TEST_ENVS = ["test", "testing"];
+
+/** The canonical name for whatever `NODE_ENV` holds. */
+export function normalizeNodeEnv(value: string | undefined): string {
+	if (!value || typeof value !== "string") return "unknown";
+	const env = value.toLowerCase();
+	if (DEV_ENVS.includes(env)) return "development";
+	if (PROD_ENVS.includes(env)) return "production";
+	if (TEST_ENVS.includes(env)) return "test";
+	return env;
+}
+
+/** Whether this process is running in production, under any spelling. */
+export function inProduction(): boolean {
+	return normalizeNodeEnv(process.env.NODE_ENV) === "production";
+}

package/src/services/main.ts

@@ -27,6 +27,14 @@ export function getQueue(): QueueManager | undefined {
 	return instance;
 }
 
+/**
+ * @internal Release the singleton, so a shut-down application does not leave a
+ * dead queue reachable through `services/main`.
+ */
+export function clearQueue(): void {
+	instance = undefined;
+}
+
 const queue: QueueManager = new Proxy({} as QueueManager, {
 	get(_target, prop) {
 		// A module loader inspects what it imports before anyone uses it: it reads

package/src/stores.ts

@@ -0,0 +1,59 @@
+/**
+ * The queue store factories a config file names — `{ default, stores }`.
+ *
+ * The shape AdonisJS gives a package with several backends and one selected:
+ * a `stores` namespace imported beside `defineConfig`, each entry that
+ * namespace's result, and the selection read from the environment. Bay had a
+ * single `driver: "memory"` and told everyone else to build the manager by
+ * hand, which meant Redis could not be reached from a config file at all.
+ *
+ *   import { defineConfig, stores } from '@c9up/bay'
+ *
+ *   export default defineConfig({
+ *     default: env.get('QUEUE_STORE'),
+ *     stores: {
+ *       memory: stores.memory(),
+ *       redis:  stores.redis({ connection: 'main' }),
+ *     },
+ *   })
+ *
+ * Factories are lazy: only the store an application actually uses is built, so
+ * naming a Redis queue in a config that runs in memory opens no connection.
+ */
+
+import { MemoryDriver } from "./drivers/MemoryDriver.js";
+import type { RedisClientSource } from "./drivers/RedisDriver.js";
+import { RedisDriver } from "./drivers/RedisDriver.js";
+import type { QueueDriver } from "./QueueManager.js";
+import { quasarConnection } from "./quasar.js";
+
+/** A driver, built on first use. */
+export type QueueStoreFactory = () => QueueDriver;
+
+export const stores = {
+	/** In memory. Jobs do not survive a restart — for tests and dev. */
+	memory(): QueueStoreFactory {
+		return () => new MemoryDriver();
+	},
+
+	/**
+	 * Redis. `connection` takes an ioredis-shaped client, a function answering
+	 * one, or the NAME of a `@c9up/quasar` connection — the last resolved at
+	 * first use, without bay importing quasar, which stays an optional peer.
+	 */
+	redis(options: {
+		connection: RedisClientSource | string;
+		prefix?: string;
+		visibilityTimeoutMs?: number;
+	}): QueueStoreFactory {
+		const source: RedisClientSource =
+			typeof options.connection === "string"
+				? quasarConnection(options.connection)
+				: options.connection;
+		return () =>
+			new RedisDriver(source, {
+				prefix: options.prefix,
+				visibilityTimeoutMs: options.visibilityTimeoutMs,
+			});
+	},
+};