Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,394 @@
import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { validateBooleanFlag, validateOptionalSecretString, validateOptionalSecretUrl, validateRequiredSecretString } from "./secret-validator.js";
import type {
EnvRecord,
RequiredWorkerConfigOptions,
WorkerConfig,
WorkerConfigDiagnostic,
WorkerConfigErrorDetails,
WorkerConfigOptions,
WorkerConfigRedisParseStatus,
WorkerConfigRedisSource,
WorkerConfigResult,
} from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_QUEUE_NAMES = {
email: "email",
workflow: "workflow",
} as const;
const WORKER_QUEUE_GROUP_NAMES = ["general", "mail", "import", "webhook", "plugin"] as const;
export class WorkerConfigError extends Error {
readonly diagnostics: WorkerConfigDiagnostic[];
constructor(diagnostics: readonly WorkerConfigDiagnostic[]) {
super(formatWorkerConfigErrorMessage(diagnostics));
this.name = "WorkerConfigError";
this.diagnostics = diagnostics.map(redactDiagnostic);
}
get details(): WorkerConfigErrorDetails {
return {
diagnostics: this.diagnostics,
};
}
}
export function loadRequiredWorkerConfig(env: EnvRecord = process.env, options: RequiredWorkerConfigOptions = {}): WorkerConfig {
const result = loadWorkerConfig(env, options);
if (result.ok) {
return result.config;
}
throw new WorkerConfigError(result.diagnostics);
}
export function loadWorkerConfig(env: EnvRecord = process.env, options: WorkerConfigOptions = {}): WorkerConfigResult {
const nodeEnv = options.nodeEnv ?? env.NODE_ENV ?? DEFAULT_NODE_ENV;
const enabledValidation = validateBooleanFlag("WORKER_ENABLED", env.WORKER_ENABLED, false);
const enabled = enabledValidation.value ?? false;
const redisSelection = selectRedisUrl(env);
const redisParse = parseRedisUrl(redisSelection.value, redisSelection.source === "none" ? undefined : redisSelection.source);
const concurrency = parseWorkerConcurrency(env.WORKER_CONCURRENCY);
const mailjet = parseMailjetConfig(env);
const browserRuntime = parseBrowserRuntimeConfig(env);
const diagnostics: WorkerConfigDiagnostic[] = [
...toDiagnostics(
validateEnv(env, {
target: "worker",
nodeEnv,
includeOptionalProviders: options.includeOptionalProviders,
extraRequired: options.extraRequired,
}).missing.filter((issue) => issue.name !== "APP_NAME" && issue.name !== "DATABASE_URL")
),
];
diagnostics.push(...toWorkerDiagnostics(enabledValidation.diagnostics));
diagnostics.push(...concurrency.diagnostics, ...mailjet.diagnostics, ...browserRuntime.diagnostics);
if (enabled && redisSelection.source === "none") {
diagnostics.push({
code: "missing-required",
name: "BULLMQ_REDIS_URL",
classification: getEnvVariableDefinition("BULLMQ_REDIS_URL")?.classification,
message: "BULLMQ_REDIS_URL or REDIS_URL is required when WORKER_ENABLED is true.",
});
}
if (enabled && !present(env.DATABASE_URL)) {
diagnostics.push({
code: "missing-required",
name: "DATABASE_URL",
classification: getEnvVariableDefinition("DATABASE_URL")?.classification,
message: "DATABASE_URL is required when WORKER_ENABLED is true.",
});
}
if (enabled) {
const workerQueueGroup = present(env.WORKER_QUEUE_GROUP);
if (!workerQueueGroup) {
diagnostics.push({
code: "missing-required",
name: "WORKER_QUEUE_GROUP",
classification: getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.classification,
message: "WORKER_QUEUE_GROUP is required when WORKER_ENABLED is true.",
});
} else if (!isWorkerQueueGroupName(workerQueueGroup)) {
diagnostics.push({
code: "invalid-worker-queue-group",
name: "WORKER_QUEUE_GROUP",
classification: getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.classification,
message: `WORKER_QUEUE_GROUP must be one of: ${WORKER_QUEUE_GROUP_NAMES.join(", ")}.`,
});
}
}
if (redisParse.status !== "not-provided") {
for (const issue of redisParse.diagnostics) {
diagnostics.push(issue);
}
}
const config: WorkerConfig = {
appName: present(env.APP_NAME) ?? DEFAULT_APP_NAME,
nodeEnv,
enabled,
concurrency: concurrency.value,
redis: {
source: redisSelection.source,
url: redisSelection.value,
configured: redisSelection.source !== "none" && redisParse.status === "valid",
parseStatus: redisParse.status,
database: redisParse.database,
},
queues: {
email: present(env.EMAIL_QUEUE_NAME) ?? DEFAULT_QUEUE_NAMES.email,
workflow: present(env.WORKFLOW_QUEUE_NAME) ?? DEFAULT_QUEUE_NAMES.workflow,
},
mailjet: mailjet.config,
browserRuntime: browserRuntime.config,
};
return {
ok: diagnostics.length === 0,
config,
diagnostics,
};
}
function selectRedisUrl(env: EnvRecord): { source: WorkerConfigRedisSource; value?: string } {
const bullmqUrl = validateOptionalSecretString("BULLMQ_REDIS_URL", env.BULLMQ_REDIS_URL);
if (bullmqUrl.configured) {
return { source: "BULLMQ_REDIS_URL", value: bullmqUrl.value };
}
const redisUrl = validateOptionalSecretString("REDIS_URL", env.REDIS_URL);
if (redisUrl.configured) {
return { source: "REDIS_URL", value: redisUrl.value };
}
return { source: "none" };
}
function parseRedisUrl(
value: string | undefined,
source: Exclude<WorkerConfigRedisSource, "none"> = "BULLMQ_REDIS_URL"
): { status: WorkerConfigRedisParseStatus; database?: number; diagnostics: WorkerConfigDiagnostic[] } {
if (!value) {
return { status: "not-provided", diagnostics: [] };
}
const definition = getEnvVariableDefinition(source);
let url: URL;
try {
url = new URL(value);
} catch {
return {
status: "invalid-url",
diagnostics: [
{
code: "invalid-redis-url",
name: source,
classification: definition?.classification,
message: "Configured Redis URL must be a valid URL with redis: or rediss: protocol.",
},
],
};
}
if (url.protocol !== "redis:" && url.protocol !== "rediss:") {
return {
status: "invalid-protocol",
diagnostics: [
{
code: "invalid-redis-protocol",
name: source,
classification: definition?.classification,
message: "Configured Redis URL protocol must be redis: or rediss:.",
},
],
};
}
const database = parseDatabaseIndex(url.pathname);
if (!database.valid) {
return {
status: "invalid-database",
diagnostics: [
{
code: "invalid-redis-database",
name: source,
classification: definition?.classification,
message: "Configured Redis URL database index must be a non-negative integer.",
},
],
};
}
return { status: "valid", database: database.value, diagnostics: [] };
}
function parseDatabaseIndex(pathname: string): { valid: true; value?: number } | { valid: false } {
const value = pathname.replace(/^\//, "");
if (!value) {
return { valid: true };
}
if (!/^\d+$/.test(value)) {
return { valid: false };
}
return { valid: true, value: Number(value) };
}
function isWorkerQueueGroupName(value: string): boolean {
return (WORKER_QUEUE_GROUP_NAMES as readonly string[]).includes(value);
}
function parseWorkerConcurrency(value: string | undefined): { value: number; diagnostics: WorkerConfigDiagnostic[] } {
const normalized = present(value);
if (!normalized) {
return { value: 1, diagnostics: [] };
}
if (!/^\d+$/.test(normalized)) {
return {
value: 1,
diagnostics: [
{
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
classification: getEnvVariableDefinition("WORKER_CONCURRENCY")?.classification,
message: "WORKER_CONCURRENCY must be a positive safe integer.",
},
],
};
}
const parsed = Number(normalized);
if (!Number.isSafeInteger(parsed) || parsed <= 0) {
return {
value: 1,
diagnostics: [
{
code: "invalid-concurrency",
name: "WORKER_CONCURRENCY",
classification: getEnvVariableDefinition("WORKER_CONCURRENCY")?.classification,
message: "WORKER_CONCURRENCY must be a positive safe integer.",
},
],
};
}
return { value: parsed, diagnostics: [] };
}
function parseMailjetConfig(env: EnvRecord): {
config: WorkerConfig["mailjet"];
diagnostics: WorkerConfigDiagnostic[];
} {
const apiKey = validateOptionalSecretString("MAILJET_API_KEY", env.MAILJET_API_KEY);
const secretKey = validateOptionalSecretString("MAILJET_SECRET_KEY", env.MAILJET_SECRET_KEY);
const fromEmail = validateOptionalSecretString("MAILJET_FROM_EMAIL", env.MAILJET_FROM_EMAIL);
const fromName = validateOptionalSecretString("MAILJET_FROM_NAME", env.MAILJET_FROM_NAME);
const shouldRequireSet = apiKey.configured || secretKey.configured || fromEmail.configured;
const diagnostics: WorkerConfigDiagnostic[] = [];
if (shouldRequireSet) {
if (!apiKey.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_API_KEY", env.MAILJET_API_KEY).diagnostics));
}
if (!secretKey.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_SECRET_KEY", env.MAILJET_SECRET_KEY).diagnostics));
}
if (!fromEmail.configured) {
diagnostics.push(...toWorkerDiagnostics(validateRequiredSecretString("MAILJET_FROM_EMAIL", env.MAILJET_FROM_EMAIL).diagnostics));
}
}
return {
config: {
configured: apiKey.configured && secretKey.configured && fromEmail.configured,
apiKey: apiKey.value,
secretKey: secretKey.value,
fromEmail: fromEmail.value,
fromName: fromName.value,
},
diagnostics,
};
}
function parseBrowserRuntimeConfig(env: EnvRecord): {
config: WorkerConfig["browserRuntime"];
diagnostics: WorkerConfigDiagnostic[];
} {
const url = validateOptionalSecretUrl("BROWSER_RUNTIME_URL", env.BROWSER_RUNTIME_URL, { allowedProtocols: ["http", "https"] });
const apiKey = validateOptionalSecretString("BROWSER_RUNTIME_API_KEY", env.BROWSER_RUNTIME_API_KEY);
const timeout = parseOptionalPositiveInteger("BROWSER_SESSION_TIMEOUT_MS", env.BROWSER_SESSION_TIMEOUT_MS);
return {
config: {
configured: url.ok && url.configured,
url: url.value,
apiKey: apiKey.value,
sessionTimeoutMs: timeout.value,
},
diagnostics: [...toWorkerDiagnostics(url.diagnostics), ...timeout.diagnostics],
};
}
function parseOptionalPositiveInteger(
name: string,
value: string | undefined
): { value?: number; diagnostics: WorkerConfigDiagnostic[] } {
const normalized = present(value);
if (!normalized) {
return { diagnostics: [] };
}
if (!/^\d+$/.test(normalized)) {
return {
diagnostics: [
{
code: "invalid-timeout",
name,
classification: getEnvVariableDefinition(name)?.classification,
message: `${name} must be a positive integer in milliseconds.`,
},
],
};
}
const parsed = Number(normalized);
if (!Number.isSafeInteger(parsed) || parsed <= 0) {
return {
diagnostics: [
{
code: "invalid-timeout",
name,
classification: getEnvVariableDefinition(name)?.classification,
message: `${name} must be a positive integer in milliseconds.`,
},
],
};
}
return { value: parsed, diagnostics: [] };
}
function toWorkerDiagnostics(diagnostics: readonly { code: string; name: string; message: string; classification?: WorkerConfigDiagnostic["classification"] }[]): WorkerConfigDiagnostic[] {
return diagnostics.map((diagnostic) => ({
code: diagnostic.code === "invalid-url-protocol" ? "invalid-url-protocol" : (diagnostic.code as WorkerConfigDiagnostic["code"]),
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
}));
}
function toDiagnostics(issues: ReturnType<typeof validateEnv>["missing"]): WorkerConfigDiagnostic[] {
return issues.map((issue) => ({
code: "missing-required",
name: issue.name,
classification: issue.classification,
message: issue.message,
}));
}
function formatWorkerConfigErrorMessage(diagnostics: readonly WorkerConfigDiagnostic[]): string {
const summary = diagnostics.map((diagnostic) => `${diagnostic.name}:${diagnostic.code}`).join(", ");
return `Invalid worker configuration (${summary}).`;
}
function redactDiagnostic(diagnostic: WorkerConfigDiagnostic): WorkerConfigDiagnostic {
return {
code: diagnostic.code,
name: diagnostic.name,
classification: diagnostic.classification,
message: diagnostic.message,
};
}
function present(value: string | undefined): string | undefined {
const trimmed = value?.trim();
return trimmed ? trimmed : undefined;
}