160 lines
5.2 KiB
TypeScript
160 lines
5.2 KiB
TypeScript
/**
|
|
* 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<TenantPlanIdentifier | null>;
|
|
|
|
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<string, unknown>, msg: string) => void } } = {},
|
|
): Promise<number> {
|
|
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";
|
|
}
|
|
}
|