import type { EnvRecord } from "@hivegrid/config"; import { WORKER_QUEUE_GROUP_NAMES, getQueueNamesForGroup, isWorkerQueueGroup, type QueueName, type WorkerQueueGroup, } from "@hivegrid/queue"; /** * Default per-group concurrency. These are deliberate — they reflect the * workload profile of each group, not a guess: * - general : 10 (mixed I/O, short jobs) * - mail : 5 (SMTP/API throughput-bound) * - import : 1 (CPU/memory-bound long-running) * - webhook : 20 (I/O-bound external HTTP) * - plugin : 5 (WASM-sandboxed third-party code; tight memory cap) * * Operators override via `WORKER_CONCURRENCY_` (uppercase, e.g. * `WORKER_CONCURRENCY_WEBHOOK=40`). */ export const DEFAULT_GROUP_CONCURRENCY: Readonly> = { general: 10, mail: 5, import: 1, webhook: 20, plugin: 5, }; const CONCURRENCY_ENV_VAR: Readonly> = { general: "WORKER_CONCURRENCY_GENERAL", mail: "WORKER_CONCURRENCY_MAIL", import: "WORKER_CONCURRENCY_IMPORT", webhook: "WORKER_CONCURRENCY_WEBHOOK", plugin: "WORKER_CONCURRENCY_PLUGIN", }; export class InvalidWorkerQueueGroupError extends Error { override readonly name = "InvalidWorkerQueueGroupError"; constructor(value: string) { super( `WORKER_QUEUE_GROUP must be one of [${WORKER_QUEUE_GROUP_NAMES.join(", ")}]; received ${JSON.stringify(value)}. ` + "See docs/ops/worker-queues.md." ); } } /** * Reads `WORKER_QUEUE_GROUP` from the given env and returns the validated * group. Throws `InvalidWorkerQueueGroupError` (a thin subclass of Error) * if the value is missing or unknown — caller is expected to log the * message and `process.exit(1)`. */ export function resolveWorkerQueueGroup(env: EnvRecord = process.env as EnvRecord): WorkerQueueGroup { const raw = env.WORKER_QUEUE_GROUP; if (typeof raw !== "string" || raw.length === 0) { throw new InvalidWorkerQueueGroupError(raw === undefined ? "" : String(raw)); } if (!isWorkerQueueGroup(raw)) { throw new InvalidWorkerQueueGroupError(raw); } return raw; } /** * Returns the BullMQ queue names this worker process should subscribe to, * given its group. Wrapper over `getQueueNamesForGroup` kept as a separate * module-level helper so callers don't have to import from the queue * package directly when they already depend on the group runtime. */ export function resolveQueueNamesForGroup(group: WorkerQueueGroup): readonly QueueName[] { return getQueueNamesForGroup(group); } /** * Reads `WORKER_CONCURRENCY_` from env (e.g. `WORKER_CONCURRENCY_MAIL`). * Falls back to the documented default for the group. Non-numeric or non- * positive overrides fall back to the default rather than throwing — a * misconfigured env var should not knock the worker offline. */ export function resolveGroupConcurrency(group: WorkerQueueGroup, env: EnvRecord = process.env as EnvRecord): number { const raw = env[CONCURRENCY_ENV_VAR[group]]; if (typeof raw === "string" && raw.length > 0) { const parsed = Number.parseInt(raw, 10); if (Number.isFinite(parsed) && parsed > 0) { return parsed; } } return DEFAULT_GROUP_CONCURRENCY[group]; } export type WorkerGroupResolution = { group: WorkerQueueGroup; queueNames: readonly QueueName[]; concurrency: number; concurrencyEnvVar: string; }; /** * One-shot bootstrap helper for the worker entry point. Validates env and * returns the group + its queues + the resolved concurrency in a single * record — that record is enough for `startWorkerRuntime` to register the * right BullMQ workers without re-reading env. */ export function bootstrapWorkerGroup(env: EnvRecord = process.env as EnvRecord): WorkerGroupResolution { const group = resolveWorkerQueueGroup(env); return { group, queueNames: resolveQueueNamesForGroup(group), concurrency: resolveGroupConcurrency(group, env), concurrencyEnvVar: CONCURRENCY_ENV_VAR[group], }; }