@c9up/bay 0.1.3

package/src/drivers/RedisDriver.ts

@@ -0,0 +1,202 @@
+/**
+ * Redis queue driver — FIFO job queue with visibility timeout.
+ *
+ * Uses LMOVE (Redis 6.2+) for at-least-once delivery:
+ * - pop() moves the job from pending → processing (atomic)
+ * - complete() removes from processing
+ * - If a worker crashes, the job stays in processing
+ * - recoverStale() moves expired processing jobs back to pending
+ *
+ * Compatible with ioredis and node-redis clients.
+ */
+
+import type { Job, QueueDriver } from "../QueueManager.js";
+
+export interface RedisClient {
+	rpush(key: string, ...values: string[]): Promise<number>;
+	lpop(key: string): Promise<string | null>;
+	lmove?(
+		source: string,
+		destination: string,
+		from: "LEFT" | "RIGHT",
+		to: "LEFT" | "RIGHT",
+	): Promise<string | null>;
+	lrem(key: string, count: number, element: string): Promise<number>;
+	llen(key: string): Promise<number>;
+	lrange(key: string, start: number, stop: number): Promise<string[]>;
+	del(key: string): Promise<number>;
+	set(key: string, value: string, ...args: string[]): Promise<string | null>;
+	get(key: string): Promise<string | null>;
+}
+
+function isValidJob(obj: unknown): obj is Job {
+	if (typeof obj !== "object" || obj === null) return false;
+	const j = obj as Record<string, unknown>;
+	return (
+		typeof j.id === "string" &&
+		typeof j.name === "string" &&
+		typeof j.attempts === "number" &&
+		typeof j.maxAttempts === "number" &&
+		typeof j.status === "string"
+	);
+}
+
+export class RedisDriver implements QueueDriver {
+	#client: RedisClient;
+	#prefix: string;
+	#visibilityTimeout: number;
+
+	constructor(
+		client: RedisClient,
+		options?: { prefix?: string; visibilityTimeoutMs?: number },
+	) {
+		this.#client = client;
+		this.#prefix = options?.prefix ?? "queue:";
+		this.#visibilityTimeout = options?.visibilityTimeoutMs ?? 30_000;
+	}
+
+	#pendingKey = () => `${this.#prefix}pending`;
+	#processingKey = () => `${this.#prefix}processing`;
+	#failedKey = () => `${this.#prefix}failed`;
+	#leaseKey = (jobId: string) => `${this.#prefix}lease:${jobId}`;
+
+	async push(job: Job): Promise<void> {
+		await this.#client.rpush(this.#pendingKey(), JSON.stringify(job));
+	}
+
+	async pop(): Promise<Job | null> {
+		let raw: string | null = null;
+
+		if (this.#client.lmove) {
+			raw = await this.#client.lmove(
+				this.#pendingKey(),
+				this.#processingKey(),
+				"LEFT",
+				"RIGHT",
+			);
+		} else {
+			raw = await this.#client.lpop(this.#pendingKey());
+			if (raw) await this.#client.rpush(this.#processingKey(), raw);
+		}
+
+		if (!raw) return null;
+		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 this.#client.lrem(this.#processingKey(), 1, raw);
+				return null;
+			}
+			await this.#client.set(
+				this.#leaseKey(parsed.id),
+				raw,
+				"PX",
+				String(this.#visibilityTimeout),
+			);
+			return parsed;
+		} catch {
+			await this.#client.lrem(this.#processingKey(), 1, raw);
+			return null;
+		}
+	}
+
+	async complete(job: Job): Promise<void> {
+		await this.#removeFromProcessing(job);
+		await this.#client.del(this.#leaseKey(job.id));
+	}
+
+	async fail(job: Job, error: string): Promise<void> {
+		await this.#removeFromProcessing(job);
+		await this.#client.del(this.#leaseKey(job.id));
+		job.error = error;
+		job.status = "failed";
+		await this.#client.rpush(this.#failedKey(), JSON.stringify(job));
+	}
+
+	async retry(job: Job): Promise<void> {
+		await this.#removeFromProcessing(job);
+		await this.#client.del(this.#leaseKey(job.id));
+		job.status = "pending";
+		await this.#client.rpush(this.#pendingKey(), JSON.stringify(job));
+	}
+
+	async recoverStale(): Promise<number> {
+		const processing = await this.#client.lrange(this.#processingKey(), 0, -1);
+		let recovered = 0;
+		for (const raw of processing) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(raw);
+			} catch {
+				// Malformed JSON would otherwise sit in processing forever —
+				// LREM purges it so the queue makes progress.
+				await this.#client.lrem(this.#processingKey(), 1, raw);
+				continue;
+			}
+			if (!isValidJob(parsed)) {
+				await this.#client.lrem(this.#processingKey(), 1, raw);
+				continue;
+			}
+			const lease = await this.#client.get(this.#leaseKey(parsed.id));
+			if (lease === null) {
+				await this.#client.lrem(this.#processingKey(), 1, raw);
+				parsed.status = "pending";
+				await this.#client.rpush(this.#pendingKey(), JSON.stringify(parsed));
+				recovered++;
+			}
+		}
+		return recovered;
+	}
+
+	/**
+	 * Remove the entry for `job` from the processing list. The string in
+	 * Redis is whatever pop() pushed, but QueueManager mutates `job` after
+	 * pop returns (attempts++, status="processing", processedAt, then
+	 * completed/failed/pending). LREM-ing on `JSON.stringify(job)` would
+	 * therefore miss every real-world entry. Use the lease — set to the
+	 * exact raw string at pop() time — and fall back to a list scan when
+	 * the lease has expired (e.g. recoverStale already handled it).
+	 */
+	async #removeFromProcessing(job: Job): Promise<void> {
+		const stored = await this.#client.get(this.#leaseKey(job.id));
+		if (stored !== null) {
+			const removed = await this.#client.lrem(this.#processingKey(), 1, stored);
+			if (removed > 0) return;
+		}
+		// Lease missing or already-LREM'd entry not found — best-effort scan
+		// matches by job id and removes the actual stored representation.
+		const items = await this.#client.lrange(this.#processingKey(), 0, -1);
+		for (const item of items) {
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(item);
+			} catch {
+				continue;
+			}
+			if (isValidJob(parsed) && (parsed as { id: string }).id === job.id) {
+				await this.#client.lrem(this.#processingKey(), 1, item);
+				return;
+			}
+		}
+	}
+
+	async failed(): Promise<Job[]> {
+		const raws = await this.#client.lrange(this.#failedKey(), 0, -1);
+		return raws
+			.map((r) => {
+				try {
+					const parsed: unknown = JSON.parse(r);
+					return isValidJob(parsed) ? parsed : null;
+				} catch {
+					return null;
+				}
+			})
+			.filter((j): j is Job => j !== null);
+	}
+
+	async size(): Promise<number> {
+		return this.#client.llen(this.#pendingKey());
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @c9up/bay — Background job queue for the Ream framework.
+ *
+ * Dispatch/process/retry/fail pattern with pluggable drivers (Memory, Redis).
+ *
+ * @implements MISS-11
+ */
+
+export { MemoryDriver } from "./drivers/MemoryDriver.js";
+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";

package/src/services/main.ts

@@ -0,0 +1,43 @@
+/**
+ * Default `QueueManager` singleton — mirror of Adonis's
+ * `import queue from '@adonisjs/queue/services/main'` shape.
+ *
+ * Populated by either:
+ *   - `BayProvider.boot()`, when the app uses `() => import('@c9up/bay/provider')`
+ *   - The app itself, via `setQueue(myQueue)`, when it wires a
+ *     custom-driver `QueueManager` outside the provider flow.
+ *
+ *   import queue from '@c9up/bay/services/main'
+ *
+ *   queue.register('send-email', new SendEmailJob())
+ *   await queue.dispatch('send-email', { to: 'user@example.com' })
+ */
+
+import type { QueueManager } from "../QueueManager.js";
+
+let instance: QueueManager | undefined;
+
+/** @internal Bind the singleton (called by BayProvider or by the app). */
+export function setQueue(value: QueueManager): void {
+	instance = value;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getQueue(): QueueManager | undefined {
+	return instance;
+}
+
+const queue: QueueManager = new Proxy({} as QueueManager, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[bay] QueueManager singleton accessed before BayProvider.boot() ran " +
+					"or `setQueue(myQueue)` was called. Wire one of them first.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default queue;

package/src/testing/FakeQueue.ts

@@ -0,0 +1,172 @@
+/**
+ * In-memory `QueueDriver` for tests — captures every dispatched
+ * job and exposes Adonis/Laravel-style `assertPushed` /
+ * `assertNotPushed` helpers in the same shape as Rover's
+ * `FakeMail`.
+ *
+ * Not re-exported from the main barrel; reach via
+ * `@c9up/bay/testing` so production code never accidentally pulls
+ * the fake into a runtime build.
+ */
+
+import type { Job, QueueDriver } from "../QueueManager.js";
+
+export interface FakeQueuePredicate {
+	/** Custom payload predicate — receives the job's `payload` and
+	 *  returns `true` to match. The job name is always taken from the
+	 *  positional `name` argument of `assertPushed` / `assertNotPushed`
+	 *  — there is no `name` field on the predicate (would create a
+	 *  silent override footgun where `assertPushed('a', { name: 'b' })`
+	 *  matches 'b' but the error message says 'a'). */
+	payloadMatches?: (payload: unknown) => boolean;
+}
+
+export type FakeQueuePredicateArg =
+	| FakeQueuePredicate
+	| ((job: Job) => boolean);
+
+export class FakeQueue implements QueueDriver {
+	#pushed: Job[] = [];
+
+	async push(job: Job): Promise<void> {
+		// Reject duplicate ids to surface the most common test-fixture
+		// mistake — two `makeJob({ id: 'x' })` reused across pushes
+		// silently corrupts later `fail`/`complete`/`retry` lookups.
+		if (this.#pushed.some((j) => j.id === job.id)) {
+			throw new Error(
+				`FakeQueue: duplicate job id '${job.id}' — each push must use a unique id (the real drivers enforce this implicitly via crypto.randomUUID()).`,
+			);
+		}
+		this.#pushed.push(job);
+	}
+
+	/** Always returns `null` — fake queues never auto-dispatch.
+	 *  Tests that need handler execution should use the memory
+	 *  driver directly. */
+	async pop(): Promise<Job | null> {
+		return null;
+	}
+
+	async fail(job: Job, error: string): Promise<void> {
+		const found = this.#requireJob(job, "fail");
+		found.status = "failed";
+		found.error = error;
+	}
+
+	async complete(job: Job): Promise<void> {
+		const found = this.#requireJob(job, "complete");
+		found.status = "completed";
+		found.processedAt = Date.now();
+	}
+
+	async retry(job: Job): Promise<void> {
+		const found = this.#requireJob(job, "retry");
+		found.attempts += 1;
+		found.status = "pending";
+		// Reset transient state from the prior failure so a retried
+		// job's invariants match a fresh push (a real driver would
+		// either drop these on requeue or rely on the worker to clear
+		// them — we mirror "drop").
+		found.error = undefined;
+		found.processedAt = undefined;
+	}
+
+	/** Look up the captured copy of a job by id. Throws when the id
+	 *  isn't present — silent no-op on a missing job is the most
+	 *  insidious test bug (caller's local Job ref shows the new
+	 *  status while the FakeQueue's internal capture is unchanged). */
+	#requireJob(job: Job, verb: string): Job {
+		const found = this.#pushed.find((j) => j.id === job.id);
+		if (!found) {
+			throw new Error(
+				`FakeQueue.${verb}: job id '${job.id}' is not in the queue. Did you forget to push it, or is it from a different FakeQueue instance?`,
+			);
+		}
+		return found;
+	}
+
+	async failed(): Promise<Job[]> {
+		return this.#pushed
+			.filter((j) => j.status === "failed")
+			.map((j) => ({ ...j }));
+	}
+
+	async size(): Promise<number> {
+		return this.#pushed.filter((j) => j.status === "pending").length;
+	}
+
+	/**
+	 * Defensive snapshot of every captured job. Each entry is a
+	 * shallow clone so test-side mutations can't bleed back into the
+	 * internal capture store — avoids cross-test contamination.
+	 */
+	getPushed(): Job[] {
+		return this.#pushed.map((j) => ({ ...j }));
+	}
+
+	reset(): void {
+		this.#pushed = [];
+	}
+
+	assertPushed(name: string, predicate?: FakeQueuePredicateArg): void {
+		const match = makeMatcher(name, predicate);
+		if (this.#pushed.some(match)) return;
+		throw new Error(
+			`queue.assertPushed('${name}'${describePredicate(predicate)}) failed — no captured job matches.\n${describeCaptured(this.#pushed)}`,
+		);
+	}
+
+	assertNotPushed(name: string, predicate?: FakeQueuePredicateArg): void {
+		const match = makeMatcher(name, predicate);
+		const found = this.#pushed.find(match);
+		if (!found) return;
+		throw new Error(
+			`queue.assertNotPushed('${name}'${describePredicate(predicate)}) failed — at least one captured job matches.\n${describeCaptured(this.#pushed)}`,
+		);
+	}
+}
+
+function makeMatcher(
+	name: string,
+	predicate: FakeQueuePredicateArg | undefined,
+): (j: Job) => boolean {
+	// Function-form predicate — caller does ALL the matching, the
+	// `name` arg is still a hard prerequisite.
+	if (typeof predicate === "function") {
+		return (j) => j.name === name && predicate(j);
+	}
+	if (predicate === undefined) {
+		return (j) => j.name === name;
+	}
+	// Object-form: positional `name` is the contract; the predicate
+	// narrows further via `payloadMatches`.
+	return (j) => {
+		if (j.name !== name) return false;
+		if (predicate.payloadMatches && !predicate.payloadMatches(j.payload)) {
+			return false;
+		}
+		return true;
+	};
+}
+
+function describePredicate(
+	predicate: FakeQueuePredicateArg | undefined,
+): string {
+	if (predicate === undefined) return "";
+	if (typeof predicate === "function") return ", <function predicate>";
+	// Empty object collapses to a name-only match — say so explicitly
+	// so a mistaken `assertPushed('x', {})` is not mistaken for "I'm
+	// narrowing by some predicate I forgot to fill in".
+	if (Object.keys(predicate).length === 0)
+		return ", <empty predicate (name-only)>";
+	return `, ${JSON.stringify(predicate)}`;
+}
+
+function describeCaptured(captured: Job[]): string {
+	if (captured.length === 0) return "Captured: (none)";
+	const lines = captured.map(
+		(j, i) =>
+			`  [${i}] name="${j.name}" status=${j.status} attempts=${j.attempts}/${j.maxAttempts}`,
+	);
+	return `Captured (${captured.length}):\n${lines.join("\n")}`;
+}