Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,113 @@
|
||||
import type { EnvRecord } from "@toolctrl/config";
|
||||
import {
|
||||
WORKER_QUEUE_GROUP_NAMES,
|
||||
getQueueNamesForGroup,
|
||||
isWorkerQueueGroup,
|
||||
type QueueName,
|
||||
type WorkerQueueGroup,
|
||||
} from "@toolctrl/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],
|
||||
};
|
||||
}
|
||||
Reference in new issue
Block a user