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,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;
|
||||
}
|
||||
Reference in new issue
Block a user