Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/queue/src/priority.ts
T

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";
}
}