114 lines
3.9 KiB
TypeScript
114 lines
3.9 KiB
TypeScript
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_<GROUP>` (uppercase, e.g.
|
|
* `WORKER_CONCURRENCY_WEBHOOK=40`).
|
|
*/
|
|
export const DEFAULT_GROUP_CONCURRENCY: Readonly<Record<WorkerQueueGroup, number>> = {
|
|
general: 10,
|
|
mail: 5,
|
|
import: 1,
|
|
webhook: 20,
|
|
plugin: 5,
|
|
};
|
|
|
|
const CONCURRENCY_ENV_VAR: Readonly<Record<WorkerQueueGroup, string>> = {
|
|
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_<GROUP>` 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],
|
|
};
|
|
}
|