/** * Plan-based job-priority resolver. * * BullMQ accepts `priority: 1-2_097_152` where `1 = highest`. We use a * fixed 4-level scale so producers, dashboards and ops runbooks stay * legible: * * - `CRITICAL=1` internal jobs, password-reset / verification mails, * cron retention / cleanup * - `HIGH=3` system-triggered workflows * - `NORMAL=5` default for tenant work without a plan override * - `LOW=10` free-tier work, low-priority batches * * Plan → priority mapping: * - `enterprise` → CRITICAL (1) * - `pro` → NORMAL (5) * - `free` → LOW (10) * - everything else / null tenantId → CRITICAL (internal job) * * The resolver supports a pluggable plan lookup (so workers and api don't * need to depend on apps/web's subscription cache). When no lookup is * registered, `resolveJobPriorityForTenant` falls back to `NORMAL` for * tenant-scoped jobs and `CRITICAL` for null tenantId. Callers can register * a lookup via `setTenantPlanLookup` at process boot. * * Feature-flag: `JOB_PRIORITY_ENABLED=false` forces every resolver call to * return `NORMAL` so the system behaves like the pre-priority queue. Default * is enabled. */ export const JOB_PRIORITY_CRITICAL = 1; export const JOB_PRIORITY_HIGH = 3; export const JOB_PRIORITY_NORMAL = 5; export const JOB_PRIORITY_LOW = 10; export type PriorityOverride = "critical" | "high" | "normal" | "low"; export type TenantPlanIdentifier = "enterprise" | "pro" | "free" | string; /** * Pluggable plan lookup. Implementations may read from a two-tier cache * (apps/web wires this up via the subscription cache) or query the database * directly. Returning `null` is treated as "unknown plan → NORMAL". */ export type TenantPlanLookup = (tenantId: string) => Promise; let registeredLookup: TenantPlanLookup | null = null; /** * Register a plan-lookup. Idempotent: passing the same lookup twice is a * no-op. Passing `null` clears the registration (used by tests). */ export function setTenantPlanLookup(lookup: TenantPlanLookup | null): void { registeredLookup = lookup; } export function getTenantPlanLookup(): TenantPlanLookup | null { return registeredLookup; } function jobPriorityEnabled(): boolean { const raw = process.env.JOB_PRIORITY_ENABLED; if (raw === undefined || raw === null || raw === "") return true; return raw.toLowerCase() !== "false" && raw !== "0"; } export function priorityFromOverride(override: PriorityOverride): number { switch (override) { case "critical": return JOB_PRIORITY_CRITICAL; case "high": return JOB_PRIORITY_HIGH; case "normal": return JOB_PRIORITY_NORMAL; case "low": return JOB_PRIORITY_LOW; default: { // Exhaustiveness: TS will narrow `override` to `never`. Defensive at // runtime in case a caller passes an untyped string. const exhaustive: never = override; throw new Error(`Unsupported priority override: ${String(exhaustive)}`); } } } export function priorityFromPlan(plan: TenantPlanIdentifier | null | undefined): number { switch (plan) { case "enterprise": return JOB_PRIORITY_CRITICAL; case "pro": return JOB_PRIORITY_NORMAL; case "free": return JOB_PRIORITY_LOW; default: // Unknown / null plan → NORMAL so a tenant whose plan can't be looked // up still gets fair scheduling instead of being silently demoted. return JOB_PRIORITY_NORMAL; } } /** * Resolve a BullMQ priority for the given tenantId. * * - `tenantId == null` → CRITICAL (internal jobs always preempt user work) * - feature-flag off → NORMAL (priority neutralised) * - no lookup registered → NORMAL for tenant-scoped jobs * - lookup throws → NORMAL (warn-only; never block enqueue on a * cache/db error) */ export async function resolveJobPriorityForTenant( tenantId: string | null | undefined, options: { lookup?: TenantPlanLookup | null; logger?: { warn: (obj: Record, msg: string) => void } } = {}, ): Promise { if (!tenantId) { return JOB_PRIORITY_CRITICAL; } if (!jobPriorityEnabled()) { return JOB_PRIORITY_NORMAL; } const lookup = options.lookup === undefined ? registeredLookup : options.lookup; if (!lookup) { return JOB_PRIORITY_NORMAL; } try { const plan = await lookup(tenantId); return priorityFromPlan(plan); } catch (error) { options.logger?.warn( { tenantId, error: error instanceof Error ? error.message : String(error), }, "resolveJobPriorityForTenant: plan lookup failed, defaulting to NORMAL", ); return JOB_PRIORITY_NORMAL; } } /** * Translate a numeric BullMQ priority back to its label. Used by metrics * exporters so the `priority` label stays low-cardinality * (`critical|high|normal|low|other`). */ export function priorityLabel(priority: number): "critical" | "high" | "normal" | "low" | "other" { switch (priority) { case JOB_PRIORITY_CRITICAL: return "critical"; case JOB_PRIORITY_HIGH: return "high"; case JOB_PRIORITY_NORMAL: return "normal"; case JOB_PRIORITY_LOW: return "low"; default: return "other"; } }