849 lines
30 KiB
TypeScript
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);
|
|
}
|