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

849 lines
30 KiB
TypeScript

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<Kind extends BrowserAutomationJob["kind"]> = BrowserAutomationJob & { kind: Kind };
export type TransactionalMailJobInput = Omit<TransactionalMailJob, "kind">;
export type WebhookDeliveryJobInput = Omit<WebhookDeliveryJob, "kind">;
export type NotificationJobInput = Omit<TenantNotificationJob, "kind">;
export type PlatformNotificationJobInput = Omit<PlatformNotificationJob, "kind" | "tenantId">;
export type CleanupJobInput = Omit<CleanupJob, "kind">;
export type BrowserSessionRunJobInput = Omit<BrowserAutomationJobForKind<"browser.session-run">, "kind">;
export type BrowserSessionCleanupJobInput = Omit<BrowserAutomationJobForKind<"browser.session-cleanup">, "kind">;
export type BrowserUsageFlushJobInput = Omit<BrowserAutomationJobForKind<"usage.flush">, "kind">;
export type FileScanJobInput = Omit<FileScanJob, "kind">;
export type FilePreviewJobInput = Omit<FilePreviewJob, "kind">;
export type ExportJobInput = Omit<ExportJob, "kind">;
export type ImportJobInput = Omit<FileImportJob, "kind">;
export type AdminSalesContactsImportJobInput = Omit<
AdminSalesContactsImportJob,
"kind"
>;
export type AdminSalesContactsExportJobInput = Omit<
AdminSalesContactsExportJob,
"kind"
>;
export type KwpProjectSyncJobInput = Omit<KwpProjectSyncJob, "kind">;
export type KwpProjectCatalogSyncJobInput = Omit<KwpProjectCatalogSyncJob, "kind">;
export type KwpContractSentinelJobInput = Omit<KwpContractSentinelJob, "kind">;
export type KwpArchiveDiscoveryJobInput = Omit<KwpArchiveDiscoveryJob, "kind">;
export type KwpArchiveFileSyncJobInput = Omit<KwpArchiveFileSyncJob, "kind">;
export type PluginInvokeJobInput = Omit<PluginInvokeJob, "kind">;
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<PlatformNotificationRequestedOutboxEvent["payload"], "metadata"> & {
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<typeof queueNames.email> & {
jobName: "send-transactional-email";
payload: TransactionalMailJob;
};
export type WebhookDeliveryJobDescriptor = QueueJobDescriptor<typeof queueNames.email> & {
jobName: "deliver-webhook";
payload: WebhookDeliveryJob;
};
export type NotificationJobDescriptor = QueueJobDescriptor<typeof queueNames.notifications> & {
jobName: "send-notification";
payload: NotificationJob;
};
export type CleanupJobDescriptor = QueueJobDescriptor<typeof queueNames.maintenance> & {
jobName: "run-cleanup";
payload: CleanupJob;
};
export type BrowserSessionRunJobDescriptor = QueueJobDescriptor<typeof queueNames.browserAutomation> & {
jobName: "browser-session-run";
payload: BrowserAutomationJobForKind<"browser.session-run">;
};
export type BrowserSessionCleanupJobDescriptor = QueueJobDescriptor<typeof queueNames.browserAutomation> & {
jobName: "browser-session-cleanup";
payload: BrowserAutomationJobForKind<"browser.session-cleanup">;
};
export type BrowserUsageFlushJobDescriptor = QueueJobDescriptor<typeof queueNames.browserAutomation> & {
jobName: "usage-flush";
payload: BrowserAutomationJobForKind<"usage.flush">;
};
export type FileScanJobDescriptor = QueueJobDescriptor<typeof queueNames.fileScan> & {
jobName: "scan-file";
payload: FileScanJob;
};
export type FilePreviewJobDescriptor = QueueJobDescriptor<typeof queueNames.filePreview> & {
jobName: "generate-file-preview";
payload: FilePreviewJob;
};
export type ExportJobDescriptor = QueueJobDescriptor<typeof queueNames.exports> & {
jobName: "run-export";
payload: ExportJob;
};
export type ImportJobDescriptor = QueueJobDescriptor<typeof queueNames.imports> & {
jobName: "run-import";
payload: ImportJob;
};
export type KwpImportJobDescriptor = QueueJobDescriptor<typeof queueNames.kwpImports> & {
jobName: "run-kwp-import";
payload: KwpImportJob;
};
export type PluginInvokeJobDescriptor = QueueJobDescriptor<typeof queueNames.pluginInvoke> & {
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<QueueJobDescriptor<Name>["jobName"], Pick<JobsOptions, "attempts" | "backoff">>;
} = {
[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<JobsOptions, "attempts" | "backoff">
>;
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<typeof priorityLabel> }) => 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<string, unknown> | undefined;
if (metadata && typeof metadata.idempotencyKey === "string") {
return toBullMqJobId(metadata.idempotencyKey);
}
return undefined;
}
async function resolvePriorityForEnqueue(options: QueueEnqueueOptions | undefined): Promise<number | undefined> {
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<Name extends QueueName>(queue: TypedQueue<Name>, descriptor: QueueJobDescriptor<Name>, 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<JobsOptions, "removeOnComplete"> =
jobId && callerOptions.removeOnComplete === undefined ? { removeOnComplete: IDEMPOTENT_JOB_RETENTION_COUNT } : {};
const resolvedPriority = await resolvePriorityForEnqueue(options);
const priorityOptions: Pick<JobsOptions, "priority"> = 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);
}