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 = "HiveGrid"; 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 = "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["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; }