110 lines
3.6 KiB
TypeScript
110 lines
3.6 KiB
TypeScript
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<T = unknown>(query: Prisma.Sql, ...values: unknown[]): Promise<T>;
|
|
};
|
|
|
|
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<OutboxEvent[]> {
|
|
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<OutboxEvent[]>(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);
|
|
}
|