import type { JobsOptions, TypedQueue } from "./types.js"; import { toBullMqJobId } from "./job-id.js"; import { queueNames, type QueueName } from "./names.js"; import type { AdminSalesContactsExportJob, AdminSalesContactsImportJob, BrowserAutomationJob, CleanupJob, ExportJob, FileImportJob, FilePreviewJob, FileScanJob, ImportJob, KwpImportJob, KwpArchiveDiscoveryJob, KwpArchiveFileSyncJob, KwpContractSentinelJob, KwpProjectCatalogSyncJob, KwpProjectSyncJob, NotificationJob, PlatformNotificationJob, PlatformNotificationRequestedOutboxEvent, PlatformNotificationSafeMetadata, PluginInvokeJob, QueueJobDescriptor, QueueJsonValue, TransactionalMailJob, TenantNotificationJob, WebhookDeliveryJob, WorkflowExecutionContinueRequestedOutboxEvent, WorkflowExecutionRequestedOutboxEvent, WorkflowTriggerOutboxEvent, } from "./payloads.js"; import { JOB_PRIORITY_CRITICAL, priorityFromOverride, priorityLabel, resolveJobPriorityForTenant, type PriorityOverride } from "./priority.js"; /** Keep idempotency effective without allowing completed BullMQ jobs to grow forever. */ export const IDEMPOTENT_JOB_RETENTION_COUNT = 10_000; type BrowserAutomationJobForKind = BrowserAutomationJob & { kind: Kind }; export type TransactionalMailJobInput = Omit; export type WebhookDeliveryJobInput = Omit; export type NotificationJobInput = Omit; export type PlatformNotificationJobInput = Omit; export type CleanupJobInput = Omit; export type BrowserSessionRunJobInput = Omit, "kind">; export type BrowserSessionCleanupJobInput = Omit, "kind">; export type BrowserUsageFlushJobInput = Omit, "kind">; export type FileScanJobInput = Omit; export type FilePreviewJobInput = Omit; export type ExportJobInput = Omit; export type ImportJobInput = Omit; export type AdminSalesContactsImportJobInput = Omit< AdminSalesContactsImportJob, "kind" >; export type AdminSalesContactsExportJobInput = Omit< AdminSalesContactsExportJob, "kind" >; export type KwpProjectSyncJobInput = Omit; export type KwpProjectCatalogSyncJobInput = Omit; export type KwpContractSentinelJobInput = Omit; export type KwpArchiveDiscoveryJobInput = Omit; export type KwpArchiveFileSyncJobInput = Omit; export type PluginInvokeJobInput = Omit; export type WorkflowTriggerOutboxEventInput = { tenantId: string | null; event: string; data: QueueJsonValue; userId: string | null; sourceId: string; }; export const PORTAL_DOCUMENT_READY_EVENT = "portal.document_ready" as const; export type PortalDocumentReadyOutboxEventInput = { tenantId: string; projectId: string; fileId: string; fileEntityLinkId: string; linkVersion: Date; userId: string | null; }; export type WorkflowExecutionRequestedOutboxEventInput = { tenantId: string | null; workflowId: string; executionId: string; type: "manual" | "api"; input: QueueJsonValue; userId: string | null; sourceId: string; }; export type WorkflowExecutionContinueRequestedOutboxEventInput = WorkflowExecutionRequestedOutboxEventInput; export type PlatformNotificationRequestedOutboxEventInput = Omit & { metadata?: PlatformNotificationSafeMetadata; }; const WORKFLOW_OUTBOX_SOURCE_ID_PATTERN = /^[A-Za-z0-9._:-]{1,234}$/u; const PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u; const PLATFORM_NOTIFICATION_MESSAGE_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/u; const PLATFORM_NOTIFICATION_DEEPLINK_PATTERN = /^\/[A-Za-z0-9/_-]{1,239}$/u; function requireWorkflowOutboxText(value: string, fieldName: string, eventType: string): string { const trimmed = value.trim(); if (!trimmed) { throw new Error(`${eventType} outbox events require ${fieldName}.`); } return trimmed; } function requireWorkflowOutboxSourceId(value: string, eventType: string): string { const sourceId = requireWorkflowOutboxText(value, "sourceId", eventType); if (!WORKFLOW_OUTBOX_SOURCE_ID_PATTERN.test(sourceId)) { throw new Error(`${eventType} outbox events require sourceId to match ${WORKFLOW_OUTBOX_SOURCE_ID_PATTERN.source}.`); } return sourceId; } function requirePlatformNotificationIdentifier(value: string, field: string): string { const normalized = value?.trim(); if (!normalized || !PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN.test(normalized)) { throw new Error(`Platform notifications require ${field} to be a stable non-secret identifier.`); } return normalized; } function requirePlatformNotificationMessageKey(value: string): string { const normalized = value?.trim(); if (!normalized || !PLATFORM_NOTIFICATION_MESSAGE_KEY_PATTERN.test(normalized)) { throw new Error("Platform notifications require a valid messageKey."); } return normalized; } function normalizePlatformNotificationChannel(value: string): "email" | "in-app" { if (value === "email" || value === "in-app") { return value; } throw new Error(`Unsupported platform notification channel: ${value}`); } function sanitizePlatformNotificationMetadata(metadata?: PlatformNotificationSafeMetadata): PlatformNotificationSafeMetadata | undefined { if (!metadata) return undefined; const sanitized: PlatformNotificationSafeMetadata = {}; for (const key of ["deliveryId", "eventId", "leadId", "taskId", "requestId", "sourceId"] as const) { const value = metadata[key]; if (typeof value === "string" && PLATFORM_NOTIFICATION_IDENTIFIER_PATTERN.test(value.trim())) { sanitized[key] = value.trim(); } } if (typeof metadata.eventType === "string" && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/u.test(metadata.eventType.trim())) { sanitized.eventType = metadata.eventType.trim(); } if (typeof metadata.deeplink === "string" && PLATFORM_NOTIFICATION_DEEPLINK_PATTERN.test(metadata.deeplink.trim())) { sanitized.deeplink = metadata.deeplink.trim(); } if (typeof metadata.replay === "boolean") { sanitized.replay = metadata.replay; } return Object.keys(sanitized).length > 0 ? sanitized : undefined; } export type TransactionalMailJobDescriptor = QueueJobDescriptor & { jobName: "send-transactional-email"; payload: TransactionalMailJob; }; export type WebhookDeliveryJobDescriptor = QueueJobDescriptor & { jobName: "deliver-webhook"; payload: WebhookDeliveryJob; }; export type NotificationJobDescriptor = QueueJobDescriptor & { jobName: "send-notification"; payload: NotificationJob; }; export type CleanupJobDescriptor = QueueJobDescriptor & { jobName: "run-cleanup"; payload: CleanupJob; }; export type BrowserSessionRunJobDescriptor = QueueJobDescriptor & { jobName: "browser-session-run"; payload: BrowserAutomationJobForKind<"browser.session-run">; }; export type BrowserSessionCleanupJobDescriptor = QueueJobDescriptor & { jobName: "browser-session-cleanup"; payload: BrowserAutomationJobForKind<"browser.session-cleanup">; }; export type BrowserUsageFlushJobDescriptor = QueueJobDescriptor & { jobName: "usage-flush"; payload: BrowserAutomationJobForKind<"usage.flush">; }; export type FileScanJobDescriptor = QueueJobDescriptor & { jobName: "scan-file"; payload: FileScanJob; }; export type FilePreviewJobDescriptor = QueueJobDescriptor & { jobName: "generate-file-preview"; payload: FilePreviewJob; }; export type ExportJobDescriptor = QueueJobDescriptor & { jobName: "run-export"; payload: ExportJob; }; export type ImportJobDescriptor = QueueJobDescriptor & { jobName: "run-import"; payload: ImportJob; }; export type KwpImportJobDescriptor = QueueJobDescriptor & { jobName: "run-kwp-import"; payload: KwpImportJob; }; export type PluginInvokeJobDescriptor = QueueJobDescriptor & { jobName: "invoke-plugin"; payload: PluginInvokeJob; }; export type EmailProducerJobDescriptor = TransactionalMailJobDescriptor | WebhookDeliveryJobDescriptor; export type BrowserAutomationProducerJobDescriptor = BrowserSessionRunJobDescriptor | BrowserSessionCleanupJobDescriptor | BrowserUsageFlushJobDescriptor; export type ProducerJobDescriptor = | EmailProducerJobDescriptor | NotificationJobDescriptor | CleanupJobDescriptor | BrowserAutomationProducerJobDescriptor | FileScanJobDescriptor | FilePreviewJobDescriptor | ExportJobDescriptor | ImportJobDescriptor | KwpImportJobDescriptor | PluginInvokeJobDescriptor; const retryJobOptionsByQueueAndJobName: { [Name in QueueName]: Record["jobName"], Pick>; } = { [queueNames.email]: { "send-transactional-email": { attempts: 3, backoff: { type: "exponential", delay: 1_000 } }, "deliver-webhook": { attempts: 5, backoff: { type: "exponential", delay: 2_000 } }, }, [queueNames.notifications]: { "send-notification": { attempts: 3, backoff: { type: "exponential", delay: 1_000 } }, }, [queueNames.maintenance]: { "run-cleanup": { attempts: 2, backoff: { type: "fixed", delay: 5_000 } }, // Cron-scheduled grace-period scan: each tick is idempotent (the // underlying SQL filter only finds overdue rows), but we still allow // one retry on transient Prisma/Redis hiccups before letting the // next 24h tick recover the run. "dsgvo-grace-period-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } }, // AK-P21 tenant hard-delete scan: idempotent per tick (only overdue // pending requests match); one retry for transient infra hiccups. "privacy-tenant-deletion-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } }, // VA-P26b portal lifecycle scan: every mutation is claimed/idempotent and // the daily scheduler provides the long-stop retry. One near-term retry // covers transient database or object-storage failures. "portal-lifecycle-scan": { attempts: 2, backoff: { type: "fixed", delay: 30_000 } }, "product-acquisition-reconcile": { attempts: 2, backoff: { type: "fixed", delay: 5_000 } }, "telephony-webhook-maintenance": { attempts: 2, backoff: { type: "fixed", delay: 5_000 } }, }, [queueNames.browserAutomation]: { "browser-session-run": { attempts: 2, backoff: { type: "exponential", delay: 5_000 } }, "browser-session-cleanup": { attempts: 3, backoff: { type: "fixed", delay: 10_000 } }, "usage-flush": { attempts: 3, backoff: { type: "fixed", delay: 10_000 } }, }, [queueNames.fileScan]: { "scan-file": { attempts: 3, backoff: { type: "exponential", delay: 2_000 } }, }, [queueNames.filePreview]: { // Preview generation is best-effort: a couple of retries cover transient // storage/decoder hiccups, then the handler marks previewStatus=failed and // the user can re-trigger from the detail view. "generate-file-preview": { attempts: 3, backoff: { type: "exponential", delay: 3_000 } }, }, [queueNames.exports]: { "run-export": { attempts: 2, backoff: { type: "exponential", delay: 10_000 } }, }, [queueNames.imports]: { "run-import": { attempts: 2, backoff: { type: "exponential", delay: 10_000 } }, }, [queueNames.kwpImports]: { "run-kwp-import": { attempts: 5, backoff: { type: "exponential", delay: 30_000 } }, }, [queueNames.pluginInvoke]: { "invoke-plugin": { attempts: 3, backoff: { type: "exponential", delay: 2_000 } }, }, }; export function buildRetryJobOptions(descriptor: ProducerJobDescriptor): JobsOptions { const queueRetryOptions = retryJobOptionsByQueueAndJobName[descriptor.queueName] as Record< ProducerJobDescriptor["jobName"], Pick >; return { ...queueRetryOptions[descriptor.jobName], removeOnComplete: true, removeOnFail: 1_000, }; } export function buildTransactionalMailJob(input: TransactionalMailJobInput): TransactionalMailJobDescriptor { return { queueName: queueNames.email, jobName: "send-transactional-email", payload: { kind: "mail.transactional", ...input, }, }; } export function buildWebhookDeliveryJob(input: WebhookDeliveryJobInput): WebhookDeliveryJobDescriptor { return { queueName: queueNames.email, jobName: "deliver-webhook", payload: { kind: "webhook.deliver", ...input, }, }; } export function buildNotificationJob(input: NotificationJobInput): NotificationJobDescriptor { if (input.channel !== "email" && input.channel !== "in-app") { throw new Error(`Unsupported notification channel: ${input.channel}`); } if (!input.tenantId?.trim()) { throw new Error("Notification jobs require tenantId."); } return { queueName: queueNames.notifications, jobName: "send-notification", payload: { kind: "notification.send", ...input, }, }; } export function buildPlatformNotificationJob(input: PlatformNotificationJobInput): NotificationJobDescriptor { const userId = input.userId ? requirePlatformNotificationIdentifier(input.userId, "userId") : undefined; const adminUserId = input.adminUserId ? requirePlatformNotificationIdentifier(input.adminUserId, "adminUserId") : undefined; if (Boolean(userId) === Boolean(adminUserId)) { throw new Error( "Platform notification jobs require exactly one recipient identity." ); } const sourceKey = requirePlatformNotificationIdentifier(input.sourceKey, "sourceKey"); const channel = normalizePlatformNotificationChannel(input.channel); const messageKey = requirePlatformNotificationMessageKey(input.messageKey); const metadata = sanitizePlatformNotificationMetadata(input.metadata); return { queueName: queueNames.notifications, jobName: "send-notification", payload: { kind: "notification.platform.send", tenantId: null, ...(userId ? { userId } : { adminUserId }), sourceKey, channel, messageKey, ...(input.category?.trim() ? { category: input.category.trim().toLowerCase() } : {}), ...(input.email?.trim() ? { email: input.email.trim() } : {}), ...(input.subject ? { subject: input.subject } : {}), ...(input.text ? { text: input.text } : {}), ...(input.html ? { html: input.html } : {}), ...(input.templateId ? { templateId: input.templateId } : {}), ...(input.templateData ? { templateData: input.templateData } : {}), ...(metadata ? { metadata } : {}), }, }; } export function buildCleanupJob(input: CleanupJobInput): CleanupJobDescriptor { return { queueName: queueNames.maintenance, jobName: "run-cleanup", payload: { kind: "cleanup.run", ...input, }, }; } export function buildBrowserSessionRunJob(input: BrowserSessionRunJobInput): BrowserSessionRunJobDescriptor { return { queueName: queueNames.browserAutomation, jobName: "browser-session-run", payload: { kind: "browser.session-run", ...input, }, }; } export function buildBrowserSessionCleanupJob(input: BrowserSessionCleanupJobInput): BrowserSessionCleanupJobDescriptor { return { queueName: queueNames.browserAutomation, jobName: "browser-session-cleanup", payload: { kind: "browser.session-cleanup", ...input, }, }; } export function buildBrowserUsageFlushJob(input: BrowserUsageFlushJobInput): BrowserUsageFlushJobDescriptor { return { queueName: queueNames.browserAutomation, jobName: "usage-flush", payload: { kind: "usage.flush", ...input, }, }; } export function buildFileScanJob(input: FileScanJobInput): FileScanJobDescriptor { return { queueName: queueNames.fileScan, jobName: "scan-file", payload: { kind: "scan.file", ...input, }, }; } export function buildFilePreviewJob(input: FilePreviewJobInput): FilePreviewJobDescriptor { if (!input.fileId?.trim()) { throw new Error("File preview jobs require fileId."); } if (!input.tenantId?.trim()) { throw new Error("File preview jobs require tenantId."); } return { queueName: queueNames.filePreview, jobName: "generate-file-preview", payload: { kind: "preview.file", ...input, }, }; } export function buildExportJob(input: ExportJobInput): ExportJobDescriptor { return { queueName: queueNames.exports, jobName: "run-export", payload: { kind: "export.run", ...input, }, }; } export function buildImportJob(input: ImportJobInput): ImportJobDescriptor { return { queueName: queueNames.imports, jobName: "run-import", payload: { kind: "import.run", ...input, }, }; } export function buildAdminSalesContactsImportJob( input: AdminSalesContactsImportJobInput ): ImportJobDescriptor { requireAdminSalesDataJobInput( input.importJobId, input.requestedByAdminUserId, "import" ); return { queueName: queueNames.imports, jobName: "run-import", payload: { kind: "admin-sales.contacts-import", ...input }, }; } export function buildAdminSalesContactsExportJob( input: AdminSalesContactsExportJobInput ): ImportJobDescriptor { requireAdminSalesDataJobInput( input.exportJobId, input.requestedByAdminUserId, "export" ); return { queueName: queueNames.imports, jobName: "run-import", payload: { kind: "admin-sales.contacts-export", ...input }, }; } function requireAdminSalesDataJobInput( jobId: string, requestedByAdminUserId: string, operation: "import" | "export" ): void { if (!jobId?.trim() || !requestedByAdminUserId?.trim()) { throw new Error( `Admin sales contacts ${operation} jobs require stable job and operator identifiers.` ); } } export function buildKwpProjectSyncJob(input: KwpProjectSyncJobInput): KwpImportJobDescriptor { if (!input.tenantId.trim() || !input.bindingId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) { throw new Error("KWP project sync jobs require stable tenant, binding, connection and cadence identifiers."); } return { queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.project-sync", ...input }, }; } export function buildKwpProjectCatalogSyncJob(input: KwpProjectCatalogSyncJobInput): KwpImportJobDescriptor { if (!input.tenantId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) { throw new Error("KWP project catalog jobs require stable tenant, connection and cadence identifiers."); } return { queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.project-catalog-sync", ...input }, }; } export function buildKwpContractSentinelJob(input: KwpContractSentinelJobInput): KwpImportJobDescriptor { if (!input.tenantId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim()) { throw new Error("KWP contract sentinel jobs require stable tenant, connection and cadence identifiers."); } return { queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.contract-sentinel", ...input }, }; } export function buildKwpArchiveDiscoveryJob(input: KwpArchiveDiscoveryJobInput): KwpImportJobDescriptor { const folderIds = input.cursor ? [...input.cursor.pendingFolderIds, ...input.cursor.visitedFolderIds] : []; if ( !input.tenantId.trim() || !input.bindingId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim() || !Number.isInteger(input.batchNumber) || input.batchNumber < 0 || folderIds.length > 1_000 || folderIds.some((folderId) => !Number.isInteger(folderId) || folderId < -2_147_483_648 || folderId > 2_147_483_647) || (input.cursor !== undefined && input.cursor.pendingFolderIds.length === 0) ) { throw new Error("KWP archive discovery jobs require a stable project binding and a bounded folder cursor."); } return { queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.archive-discovery", ...input }, }; } export function buildKwpArchiveFileSyncJob(input: KwpArchiveFileSyncJobInput): KwpImportJobDescriptor { if ( !input.tenantId.trim() || !input.bindingId.trim() || !input.dataConnectionId.trim() || !input.cadenceBucket.trim() || !input.archiveFile.externalId.trim() || !input.archiveFile.displayName.trim() || !Number.isInteger(input.archiveFile.revisionId) ) { throw new Error("KWP archive file jobs require stable tenant, binding, connection, cadence and revision identifiers."); } return { queueName: queueNames.kwpImports, jobName: "run-kwp-import", payload: { kind: "kwp.archive-file-sync", ...input }, }; } export function buildPluginInvokeJob(input: PluginInvokeJobInput): PluginInvokeJobDescriptor { return { queueName: queueNames.pluginInvoke, jobName: "invoke-plugin", payload: { kind: "plugin.invoke", ...input, }, }; } export function buildWorkflowTriggerOutboxEvent(input: WorkflowTriggerOutboxEventInput): WorkflowTriggerOutboxEvent { const eventType = "workflow.trigger.event"; const event = requireWorkflowOutboxText(input.event, "event", eventType); const sourceId = requireWorkflowOutboxSourceId(input.sourceId, eventType); return { tenantId: input.tenantId, type: eventType, payload: { event, data: input.data, userId: input.userId, }, dispatchKey: `workflow-trigger:${sourceId}`, }; } /** * Internal, DB-backed producer contract for customer-portal auto release. * It deliberately carries no document type; the consumer must resolve the * authoritative FileEntityLink.linkRole inside its tenant transaction. */ export function buildPortalDocumentReadyOutboxEvent(input: PortalDocumentReadyOutboxEventInput): WorkflowTriggerOutboxEvent { return buildWorkflowTriggerOutboxEvent({ tenantId: input.tenantId, event: PORTAL_DOCUMENT_READY_EVENT, data: { projectId: input.projectId, fileId: input.fileId, fileEntityLinkId: input.fileEntityLinkId, }, userId: input.userId, sourceId: `portal-document-ready:${input.fileEntityLinkId}:${input.linkVersion.getTime()}`, }); } export function buildWorkflowExecutionRequestedOutboxEvent(input: WorkflowExecutionRequestedOutboxEventInput): WorkflowExecutionRequestedOutboxEvent { const eventType = "workflow.execution.requested"; const workflowId = requireWorkflowOutboxText(input.workflowId, "workflowId", eventType); const executionId = requireWorkflowOutboxText(input.executionId, "executionId", eventType); const sourceId = requireWorkflowOutboxSourceId(input.sourceId, eventType); return { tenantId: input.tenantId, type: eventType, payload: { workflowId, executionId, type: input.type, input: input.input, userId: input.userId, }, dispatchKey: `workflow-execution:${sourceId}`, }; } export function buildWorkflowExecutionContinueRequestedOutboxEvent( input: WorkflowExecutionContinueRequestedOutboxEventInput ): WorkflowExecutionContinueRequestedOutboxEvent { const eventType = "workflow.execution.continue.requested"; const workflowId = requireWorkflowOutboxText(input.workflowId, "workflowId", eventType); const executionId = requireWorkflowOutboxText(input.executionId, "executionId", eventType); const sourceId = requireWorkflowOutboxSourceId(input.sourceId, eventType); return { tenantId: input.tenantId, type: eventType, payload: { workflowId, executionId, type: input.type, input: input.input, userId: input.userId, }, dispatchKey: `workflow-continuation:${sourceId}`, }; } export function buildPlatformNotificationRequestedOutboxEvent(input: PlatformNotificationRequestedOutboxEventInput): PlatformNotificationRequestedOutboxEvent { const deliveryId = requirePlatformNotificationIdentifier(input.deliveryId, "deliveryId"); const userId = input.userId ? requirePlatformNotificationIdentifier(input.userId, "userId") : undefined; const adminUserId = input.adminUserId ? requirePlatformNotificationIdentifier(input.adminUserId, "adminUserId") : undefined; if (Boolean(userId) === Boolean(adminUserId)) { throw new Error( "Platform notification outbox events require exactly one recipient identity." ); } const sourceKey = requirePlatformNotificationIdentifier(input.sourceKey, "sourceKey"); const channel = normalizePlatformNotificationChannel(input.channel); const messageKey = requirePlatformNotificationMessageKey(input.messageKey); const metadata = sanitizePlatformNotificationMetadata(input.metadata); const outboxMetadata = { ...(metadata ?? {}) }; delete outboxMetadata.deliveryId; return { tenantId: null, type: "notification.platform.requested.v1", payload: { deliveryId, ...(userId ? { userId } : { adminUserId }), sourceKey, channel, messageKey, ...(input.category?.trim() ? { category: input.category.trim().toLowerCase() } : {}), ...(Object.keys(outboxMetadata).length > 0 ? { metadata: outboxMetadata } : {}), }, // The delivery id is stable across replay and distinct per recipient, while // sourceKey may intentionally be shared by multiple configured recipients. dispatchKey: `platform-notification:${deliveryId}`, }; } export type QueueEnqueueOptions = JobsOptions & { idempotencyKey?: string; /** * Tenant scope for plan-based priority resolution. Pass `null` for * internal/system jobs (cron, retention, audit) which always run at * CRITICAL priority. Omitting `tenantId` leaves the priority untouched * unless `priorityOverride` is set. */ tenantId?: string | null; /** * Explicit priority hint that bypasses tenant-plan lookup. Use for * semantically critical jobs (password-reset mail, verification mail) * regardless of plan, and for explicit low-priority batches. */ priorityOverride?: PriorityOverride; }; /** * Optional enqueue observer. Producer-host apps (api / web / worker) can * register one during boot to forward priority/queue/jobName info to their * Prometheus registry. Kept as a module-level setter so the queue package * does not depend on prom-client or any app metrics bundle. */ export type EnqueueObserver = (event: { queueName: QueueName; jobName: string; priority: number; priorityLabel: ReturnType }) => void; let enqueueObserver: EnqueueObserver | null = null; export function setEnqueueObserver(observer: EnqueueObserver | null): void { enqueueObserver = observer; } export function getEnqueueObserver(): EnqueueObserver | null { return enqueueObserver; } export function buildIdempotentJobId(descriptor: ProducerJobDescriptor, options?: QueueEnqueueOptions): string | undefined { if (typeof options?.jobId === "string") { return toBullMqJobId(options.jobId); } if (typeof options?.idempotencyKey === "string") { return toBullMqJobId(options.idempotencyKey); } if (descriptor.payload.kind === "export.run") { return toBullMqJobId(descriptor.payload.exportJobId); } if (descriptor.payload.kind === "import.run") { return toBullMqJobId(descriptor.payload.importJobId); } const metadata = descriptor.payload.metadata as Record | undefined; if (metadata && typeof metadata.idempotencyKey === "string") { return toBullMqJobId(metadata.idempotencyKey); } return undefined; } async function resolvePriorityForEnqueue(options: QueueEnqueueOptions | undefined): Promise { if (!options) return undefined; if (typeof options.priority === "number") { // Explicit numeric priority always wins so power-users / tests can pin // a precise value. return options.priority; } if (options.priorityOverride !== undefined) { return priorityFromOverride(options.priorityOverride); } if (options.tenantId !== undefined) { if (options.tenantId === null) { // Explicit `null` tenantId → internal job → CRITICAL. Short-circuit // the resolver to avoid a useless feature-flag round-trip. return JOB_PRIORITY_CRITICAL; } return resolveJobPriorityForTenant(options.tenantId); } return undefined; } export async function enqueueJob(queue: TypedQueue, descriptor: QueueJobDescriptor, options?: QueueEnqueueOptions) { const producerDescriptor = descriptor as ProducerJobDescriptor; const callerOptions: JobsOptions = options ? { ...options } : {}; delete (callerOptions as QueueEnqueueOptions).idempotencyKey; delete (callerOptions as QueueEnqueueOptions).tenantId; delete (callerOptions as QueueEnqueueOptions).priorityOverride; const jobId = buildIdempotentJobId(producerDescriptor, options); const idempotentCompletionRetention: Pick = jobId && callerOptions.removeOnComplete === undefined ? { removeOnComplete: IDEMPOTENT_JOB_RETENTION_COUNT } : {}; const resolvedPriority = await resolvePriorityForEnqueue(options); const priorityOptions: Pick = resolvedPriority !== undefined ? { priority: resolvedPriority } : {}; const enqueueOptions: JobsOptions = { ...buildRetryJobOptions(producerDescriptor), ...idempotentCompletionRetention, ...(jobId ? { jobId } : {}), ...priorityOptions, ...callerOptions, }; if (enqueueObserver && typeof enqueueOptions.priority === "number") { try { enqueueObserver({ queueName: descriptor.queueName as QueueName, jobName: descriptor.jobName, priority: enqueueOptions.priority, priorityLabel: priorityLabel(enqueueOptions.priority), }); } catch { // Observer must never block enqueue. Swallow. } } return queue.add(descriptor.jobName, descriptor.payload, enqueueOptions); }