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,159 @@
|
||||
/**
|
||||
* 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";
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user