Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/worker/src/group-runtime.ts
T
2026-07-08 16:15:37 +02:00

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],
};
}