import { Prisma, type OutboxEvent } from "../generated/prisma/client/client.js"; /** * Atomic claim-batch query for the outbox dispatcher. * * Uses `UPDATE ... WHERE id IN (SELECT ... FOR UPDATE SKIP LOCKED) * RETURNING *` so that multiple dispatcher replicas can poll the same * table without ever picking the same event twice. The claim: * * 1. Selects up to `limit` rows whose `status = 'PENDING'` and * `scheduledAt <= now`. Higher priority first, then oldest first. * 2. `FOR UPDATE SKIP LOCKED` makes concurrent claims race-free — * replica B simply sees fewer rows when replica A already locked some. * 3. Flips the rows to `PROCESSING` and sets `lockedUntil = now + leaseMs` * so a crashed dispatcher's events get recovered by the next pass. * * Returns the freshly claimed rows; caller (dispatcher) then enqueues each * payload to the appropriate BullMQ queue. * * See docs/architecture/outbox-pattern.md. */ /** * Default lease: a claimed event must finish dispatching within this * window or the next polling pass treats it as crashed and re-claims it * (the recovery query filters on `lockedUntil < now`). */ export const OUTBOX_CLAIM_LEASE_MS = 5 * 60 * 1000; /** Default batch size; can be overridden via `OUTBOX_DISPATCH_BATCH_SIZE`. */ export const OUTBOX_CLAIM_DEFAULT_LIMIT = 100; export type OutboxClaimRunner = { $queryRaw(query: Prisma.Sql, ...values: unknown[]): Promise; }; export type ClaimPendingOutboxEventsOptions = { /** Max events claimed in one pass. */ limit?: number; /** Clock injection for deterministic tests. */ now?: Date; /** Override the claim lease. */ leaseMs?: number; }; /** * Atomically claim a batch of pending outbox events. Returns the claimed * rows with status set to PROCESSING and `lockedUntil = now + leaseMs`. * * Always runs on the write-primary (not a replica): the row update happens * inside the same statement as the select, so the read-from-replica race * window does not exist. */ export async function claimPendingOutboxEvents( prisma: OutboxClaimRunner, options: ClaimPendingOutboxEventsOptions = {} ): Promise { const limit = clampLimit(options.limit); const now = options.now ?? new Date(); const leaseMs = options.leaseMs ?? OUTBOX_CLAIM_LEASE_MS; const lockedUntil = new Date(now.getTime() + leaseMs); // Drift recovery: rows stuck in PROCESSING past their lease are treated // as crashed and become eligible for re-claim. The status filter accepts // either PENDING (normal) or PROCESSING-with-expired-lockedUntil. const sql = Prisma.sql` UPDATE "OutboxEvent" SET "status" = 'PROCESSING', "lockedUntil" = ${lockedUntil} WHERE "id" IN ( SELECT "id" FROM "OutboxEvent" WHERE ( ("status" = 'PENDING' AND "scheduledAt" <= ${now}) OR ("status" = 'PROCESSING' AND "lockedUntil" IS NOT NULL AND "lockedUntil" < ${now}) ) ORDER BY "priority" DESC, "createdAt" ASC LIMIT ${limit} FOR UPDATE SKIP LOCKED ) RETURNING "id", "tenantId", "eventType", "payload", "status", "createdAt", "processedAt", "retries", "deliveryGeneration", "lastError", "scheduledAt", "dispatchKey", "priority", "lockedUntil" `; const rows = await prisma.$queryRaw(sql); return Array.isArray(rows) ? rows : []; } function clampLimit(limit: number | undefined): number { if (typeof limit !== "number" || !Number.isFinite(limit)) { return OUTBOX_CLAIM_DEFAULT_LIMIT; } if (limit < 1) return 1; if (limit > 1000) return 1000; return Math.floor(limit); }