@c9up/bay 0.1.13 → 0.2.0

package/src/augmentations.ts

@@ -0,0 +1,31 @@
+/**
+ * Teach ream's `ContainerBindings` what `container.make('queue')` returns.
+ *
+ * ream declares that interface open on purpose: it registers its own entries
+ * and expects each package to contribute the one it owns. Nothing filled this
+ * one in, so resolving by the string token answered `unknown` and every call
+ * site had to assert a type it could not prove.
+ *
+ * Loaded from the package barrel and from the provider, so registering bay is
+ * enough — an application writes no `declare module` of its own.
+ *
+ * Type-only, and ream stays an OPTIONAL peer: nothing here reaches a runtime
+ * import, and a `declare module` for a specifier that does not resolve is
+ * simply inert.
+ */
+
+// Referenced so the augmentation below resolves the module it augments.
+import type {} from "@c9up/ream/types";
+import type { QueueManager } from "./QueueManager.js";
+
+declare module "@c9up/ream/types" {
+	interface ContainerBindings {
+		/** The job queue, bound by `BayProvider`. */
+		"bay.queue": QueueManager;
+		/**
+		 * The same binding under the name it had before the token carried its
+		 * package. Kept bound so an existing `container.make(...)` resolves.
+		 */
+		queue: QueueManager;
+	}
+}

package/src/configure.ts

@@ -9,6 +9,7 @@
 
 interface Codemods {
 	addProvider(importPath: string): Promise<void>;
+	registerCommand(importPath: string): Promise<void>;
 	addEnvVars(vars: Record<string, string>): Promise<void>;
 	writeFile(
 		filePath: string,
@@ -22,24 +23,41 @@ export async function configure(codemods: Codemods): Promise<void> {
 	// without them leaves an application whose config asks the environment for
 	// something nothing ever put there.
 	await codemods.addEnvVars({
-		QUEUE_STORE: "memory",
+		QUEUE_DRIVER: "memory",
 	});
 
 	await codemods.addProvider("@c9up/bay/provider");
+	// `queue:work` and `make:job` are the package's, not the binary's: a
+	// project reaches them by listing the module, never by upgrading `ream`.
+	await codemods.registerCommand("@c9up/bay/commands");
 	await codemods.writeFile(
 		"config/queue.ts",
-		`import { defineConfig, stores } from '@c9up/bay'
+		`import { defineConfig, drivers } from '@c9up/bay'
 import env from '#start/env'
 
 export default defineConfig({
-  // Which store to run on. Memory forgets everything on restart, which is
+  // Which adapter 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'),
+  default: env.get('QUEUE_DRIVER', 'memory'),
 
-  stores: {
-    memory: stores.memory(),
-    redis: stores.redis({ connection: 'main' }),
+  adapters: {
+    memory: drivers.memory(),
+    redis: drivers.redis({ connection: 'main' }),
   },
+
+  // What the worker does between jobs: how long it waits after finding
+  // nothing, how often it reclaims jobs a crashed worker left behind, how many
+  // it runs at once, and which named queues it serves.
+  worker: {
+    idleDelay: 2_000,
+    stalledInterval: 30_000,
+    concurrency: 1,
+    // queues: ['critical', 'default'],
+  },
+
+  // Where the job classes live. Every module under here is imported at boot,
+  // so a worker resolves a queued record by the class's own name.
+  locations: ['app/jobs'],
 })`,
 	);
 }

package/src/console/contract.ts

@@ -0,0 +1,94 @@
+/**
+ * The console command contract, declared locally.
+ *
+ * Bay stays framework-agnostic: it must not import `@c9up/ream`, so it
+ * describes the shape Ream's console kernel dispatches against rather than
+ * importing it.
+ *
+ * Ream's decorators (`@args` / `@flags`) live in the framework, so the helpers
+ * below build the same metadata without them.
+ */
+
+export interface CommandOptions {
+	/** Boot the application before `run()`. Off by default. */
+	startApp?: boolean;
+	staysAlive?: boolean;
+	allowUnknownFlags?: boolean;
+}
+
+export interface ArgumentMetaData {
+	type: "string" | "spread";
+	propertyName: string;
+	argumentName: string;
+	description?: string;
+	required: boolean;
+	default?: string | string[];
+}
+
+export interface FlagMetaData {
+	type: "string" | "boolean" | "number" | "array";
+	propertyName: string;
+	flagName: string;
+	description?: string;
+	alias: string[];
+	default?: string | string[] | number | boolean;
+	required: boolean;
+}
+
+/** The static side the kernel reads. */
+export interface BayCommandClass {
+	new (): { run(): Promise<void> | void };
+	commandName: string;
+	description: string;
+	options?: CommandOptions;
+	args?: readonly ArgumentMetaData[];
+	flags?: readonly FlagMetaData[];
+	help?: string | string[];
+}
+
+/** `startServer` → `start-server`, matching the framework's decorators. */
+function dashCase(value: string): string {
+	return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+export function flag(
+	propertyName: string,
+	type: FlagMetaData["type"],
+	options: {
+		flagName?: string;
+		description?: string;
+		alias?: string[];
+		default?: FlagMetaData["default"];
+		required?: boolean;
+	} = {},
+): FlagMetaData {
+	return {
+		type,
+		propertyName,
+		flagName: options.flagName ?? dashCase(propertyName),
+		description: options.description,
+		alias: options.alias ?? [],
+		default: options.default,
+		required: options.required ?? false,
+	};
+}
+
+export function argument(
+	propertyName: string,
+	options: {
+		type?: ArgumentMetaData["type"];
+		argumentName?: string;
+		description?: string;
+		required?: boolean;
+		default?: ArgumentMetaData["default"];
+	} = {},
+): ArgumentMetaData {
+	return {
+		type: options.type ?? "string",
+		propertyName,
+		argumentName: options.argumentName ?? dashCase(propertyName),
+		description: options.description,
+		required: options.required ?? options.default === undefined,
+		default: options.default,
+	};
+}

package/src/console/index.ts

@@ -0,0 +1,68 @@
+/**
+ * `@c9up/bay/commands` — the commands bay ships.
+ *
+ *   // reamrc.ts, written by `configure()`
+ *   commands: [() => import('@c9up/bay/commands')]
+ *
+ * A module answering `getMetaData()` / `getCommand()`, which is how a package
+ * adds commands: by shipping them, never by a change to the `ream` binary.
+ *
+ * `jobsDir` is read through a getter, not captured: these classes are built
+ * when the module is imported — before the application boots — while `run()`
+ * happens after it, when the config exists.
+ */
+
+import { getJobsDir } from "../jobs.js";
+import type { BayCommandClass } from "./contract.js";
+import { makeJobCommand } from "./makeJob.js";
+import { queueWorkCommand } from "./queueWork.js";
+
+const COMMANDS: readonly BayCommandClass[] = [
+	queueWorkCommand(),
+	makeJobCommand({
+		get jobsDir() {
+			return getJobsDir();
+		},
+	}),
+];
+
+/** What the kernel reads to list a command without importing it. */
+interface CommandMetaData {
+	commandName: string;
+	namespace: string | null;
+	description: string;
+	help?: string | string[];
+	aliases: string[];
+	options: Record<string, unknown>;
+	args: readonly unknown[];
+	flags: readonly unknown[];
+}
+
+function serialize(command: BayCommandClass): CommandMetaData {
+	const colon = command.commandName.indexOf(":");
+	return {
+		commandName: command.commandName,
+		namespace: colon === -1 ? null : command.commandName.slice(0, colon),
+		description: command.description,
+		help: command.help,
+		aliases: [],
+		options: { ...command.options },
+		args: command.args ?? [],
+		flags: command.flags ?? [],
+	};
+}
+
+export async function getMetaData(): Promise<CommandMetaData[]> {
+	return COMMANDS.map(serialize);
+}
+
+export async function getCommand(
+	metadata: CommandMetaData,
+): Promise<BayCommandClass | null> {
+	return (
+		COMMANDS.find((command) => command.commandName === metadata.commandName) ??
+		null
+	);
+}
+
+export type { BayCommandClass } from "./contract.js";

package/src/console/makeJob.ts

@@ -0,0 +1,139 @@
+/**
+ * `make:job` — scaffold a job class.
+ *
+ *     ream make:job SendWelcomeEmail        → app/jobs/send_welcome_email.ts
+ *     ream make:job emails/SendWelcomeEmail → app/jobs/emails/send_welcome_email.ts
+ *
+ * A subdirectory is allowed and is the only reason the name is not a plain
+ * identifier: `..` and every other way out of the jobs directory is refused
+ * before anything is written.
+ */
+
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { argument, type BayCommandClass } from "./contract.js";
+
+export interface MakeJobOptions {
+	/** Directory the job files are scaffolded into. */
+	jobsDir: string;
+}
+
+/** `SendWelcomeEmail` → `send_welcome_email`, `HTTPPing` → `http_ping`. */
+export function toSnakeCase(name: string): string {
+	return name
+		.replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+		.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+		.replace(/[-\s]+/g, "_")
+		.toLowerCase();
+}
+
+/** `send_welcome_email` / `sendWelcomeEmail` → `SendWelcomeEmail`. */
+export function toPascalCase(name: string): string {
+	return name
+		.split(/[_\-\s]+/)
+		.filter((part) => part.length > 0)
+		.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+		.join("");
+}
+
+/**
+ * Split `emails/SendWelcomeEmail` into the directory it goes in and the class
+ * it declares, refusing anything that would leave the jobs directory.
+ */
+export function resolveJobName(input: string): {
+	dir: string;
+	className: string;
+	fileName: string;
+} {
+	const parts = input.split("/").filter((part) => part.length > 0);
+	const last = parts.pop();
+	if (last === undefined || last.length === 0) {
+		throw new Error(`Invalid job name: '${input}'`);
+	}
+	for (const part of [...parts, last]) {
+		// `..` is the traversal; the rest are characters a filename has no
+		// business carrying and a shell has opinions about.
+		if (part === ".." || /[\\'";`]/.test(part)) {
+			throw new Error(`Invalid job name: '${input}'`);
+		}
+	}
+	const className = toPascalCase(last);
+	if (!/^[A-Za-z][A-Za-z0-9]*$/.test(className)) {
+		throw new Error(
+			`Invalid job name: '${input}' — a job's name becomes a class name`,
+		);
+	}
+	return {
+		dir: parts.join("/"),
+		className,
+		fileName: `${toSnakeCase(last)}.ts`,
+	};
+}
+
+/** The file a fresh job starts as. */
+export function jobStub(className: string): string {
+	return `import { Job } from '@c9up/bay'
+import type { JobOptions } from '@c9up/bay'
+
+interface ${className}Payload {
+  // What \`dispatch(${className}, …)\` must be given.
+}
+
+export default class ${className} extends Job<${className}Payload> {
+  static options: JobOptions = {
+    // queue: 'default',
+    // maxRetries: 3,
+    // delay: '10s',
+    // timeout: '1m',
+  }
+
+  async execute(): Promise<void> {
+    // The work. Throwing is what makes the attempt fail.
+    void this.payload
+  }
+
+  async failed(error: Error): Promise<void> {
+    // Once the last attempt has failed — the alert or the cleanup.
+    void error
+  }
+}
+`;
+}
+
+export function makeJobCommand(options: MakeJobOptions): BayCommandClass {
+	return class MakeJob {
+		static commandName = "make:job";
+		static description = "Scaffold a background job class";
+		// Pure filesystem work: no reason to boot the app and open a connection.
+		static options = { startApp: false };
+		static args = [
+			argument("name", {
+				description: "Job class name, optionally under a subdirectory",
+			}),
+		];
+
+		declare name: string;
+
+		async run(): Promise<void> {
+			let resolved: ReturnType<typeof resolveJobName>;
+			try {
+				resolved = resolveJobName(this.name);
+			} catch (err) {
+				console.error(
+					`[bay] ${err instanceof Error ? err.message : String(err)}`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+
+			const dir = path.join(options.jobsDir, resolved.dir);
+			const filePath = path.join(dir, resolved.fileName);
+			await fsp.mkdir(dir, { recursive: true });
+			// `wx`: an existing job is never clobbered, and the error says so.
+			await fsp.writeFile(filePath, jobStub(resolved.className), {
+				flag: "wx",
+			});
+			console.log(`Created ${filePath}`);
+		}
+	};
+}

package/src/console/queueWork.ts

@@ -0,0 +1,70 @@
+/**
+ * `queue:work` — run the worker that takes jobs off the queue.
+ *
+ * The command a deployment runs as its own process, beside the HTTP one:
+ *
+ *     ream queue:work
+ *     ream queue:work --queue=emails,notifications
+ *     ream queue:work --concurrency=10
+ *
+ * It stays alive on purpose — `staysAlive` — and the loop it starts is the
+ * application's, so a SIGTERM reaches `BayProvider.shutdown()`, which stops the
+ * worker and lets the job in flight finish rather than dropping it.
+ */
+
+import { getQueue } from "../services/main.js";
+import { type BayCommandClass, flag } from "./contract.js";
+
+/** Split `--queue=a,b` into names, dropping the empties a trailing comma makes. */
+export function parseQueues(value: string | undefined): string[] | undefined {
+	if (value === undefined) return undefined;
+	const names = value
+		.split(",")
+		.map((name) => name.trim())
+		.filter((name) => name.length > 0);
+	return names.length > 0 ? names : undefined;
+}
+
+export function queueWorkCommand(): BayCommandClass {
+	return class QueueWork {
+		static commandName = "queue:work";
+		static description = "Process queued jobs until the process is stopped";
+		// The worker needs the container: the queue it drains is the one the
+		// provider booted, with the driver the config named.
+		static options = { startApp: true, staysAlive: true };
+		static flags = [
+			flag("queue", "string", {
+				description:
+					"Comma-separated queues to serve, in order (default: the default queue)",
+			}),
+			flag("concurrency", "number", {
+				description: "How many jobs to run at once (default: 1)",
+			}),
+		];
+
+		declare queue?: string;
+		declare concurrency?: number;
+
+		async run(): Promise<void> {
+			const manager = getQueue();
+			if (!manager) {
+				// Naming the wiring beats a stack trace out of the service proxy:
+				// the usual cause is a project that never added the provider.
+				throw new Error(
+					"[bay] queue:work found no queue. Add `() => import('@c9up/bay/provider')` " +
+						"to the providers in reamrc.ts, or call setQueue(myQueue) at boot.",
+				);
+			}
+
+			const queues = parseQueues(this.queue);
+			process.stdout.write(
+				`[bay] worker started — queues: ${(queues ?? ["default"]).join(", ")}, concurrency: ${this.concurrency ?? 1}\n`,
+			);
+
+			await manager.work({
+				queues,
+				concurrency: this.concurrency,
+			});
+		}
+	};
+}

package/src/drivers/MemoryDriver.ts

@@ -1,27 +1,71 @@
 /**
- * Memory queue driver — in-process queue for development.
+ * Memory queue driver — in-process queue for development and tests.
  */
 
-import type { Job, QueueDriver } from "../QueueManager.js";
+import { DEFAULT_QUEUE } from "../Job.js";
+import { type JobRecord, type QueueDriver, queueOf } from "../QueueManager.js";
 
 export class MemoryDriver implements QueueDriver {
-	#pending: Job[] = [];
-	#failedJobs: Job[] = [];
+	/** One list per named queue, created on first use. */
+	#pending: Map<string, JobRecord[]> = new Map();
+	/**
+	 * Jobs whose `runAt` has not arrived, oldest deadline first.
+	 *
+	 * Kept apart from the queues rather than filtered on the way out: a delayed
+	 * job at the head of a list would otherwise be skipped over on every poll,
+	 * and a queue whose head is not due would look empty while it is not.
+	 */
+	#delayed: JobRecord[] = [];
+	#failedJobs: JobRecord[] = [];
 	#maxFailedJobs: number;
 
 	constructor(options?: { maxFailedJobs?: number }) {
 		this.#maxFailedJobs = options?.maxFailedJobs ?? 1000;
 	}
 
-	async push(job: Job): Promise<void> {
-		this.#pending.push(job);
+	#queue(name: string): JobRecord[] {
+		const existing = this.#pending.get(name);
+		if (existing !== undefined) return existing;
+		const created: JobRecord[] = [];
+		this.#pending.set(name, created);
+		return created;
 	}
 
-	async pop(): Promise<Job | null> {
-		return this.#pending.shift() ?? null;
+	/** Move everything whose delay has elapsed into its queue. */
+	#promoteDue(now = Date.now()): void {
+		if (this.#delayed.length === 0) return;
+		const due = this.#delayed.filter((job) => (job.runAt ?? 0) <= now);
+		if (due.length === 0) return;
+		this.#delayed = this.#delayed.filter((job) => (job.runAt ?? 0) > now);
+		for (const job of due) {
+			job.runAt = undefined;
+			this.#queue(queueOf(job)).push(job);
+		}
+	}
+
+	async push(job: JobRecord): Promise<void> {
+		if (job.runAt !== undefined && job.runAt > Date.now()) {
+			this.#delayed.push(job);
+			this.#delayed.sort((a, b) => (a.runAt ?? 0) - (b.runAt ?? 0));
+			return;
+		}
+		this.#queue(queueOf(job)).push(job);
+	}
+
+	async pop(
+		queues: readonly string[] = [DEFAULT_QUEUE],
+	): Promise<JobRecord | null> {
+		this.#promoteDue();
+		// In the order given: naming `['critical', 'default']` is how a worker
+		// says which queue it would rather drain first.
+		for (const name of queues) {
+			const next = this.#pending.get(name)?.shift();
+			if (next !== undefined) return next;
+		}
+		return null;
 	}
 
-	async fail(job: Job, error: string): Promise<void> {
+	async fail(job: JobRecord, error: string): Promise<void> {
 		job.error = error;
 		job.status = "failed";
 		this.#failedJobs.push(job);
@@ -30,20 +74,28 @@ export class MemoryDriver implements QueueDriver {
 		}
 	}
 
-	async complete(_job: Job): Promise<void> {
+	async complete(_job: JobRecord): Promise<void> {
 		// Nothing to do for memory driver
 	}
 
-	async retry(job: Job): Promise<void> {
+	async retry(job: JobRecord): Promise<void> {
 		job.status = "pending";
-		this.#pending.push(job);
+		this.#queue(queueOf(job)).push(job);
 	}
 
-	async failed(): Promise<Job[]> {
+	async failed(): Promise<JobRecord[]> {
 		return [...this.#failedJobs];
 	}
 
+	/**
+	 * Everything waiting, across every queue — a delayed job included.
+	 *
+	 * It is queued; it is simply not due. Leaving it out would report an empty
+	 * queue to anything draining one before shutdown.
+	 */
 	async size(): Promise<number> {
-		return this.#pending.length;
+		let total = this.#delayed.length;
+		for (const jobs of this.#pending.values()) total += jobs.length;
+		return total;
 	}
 }