Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,108 @@
|
||||
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",
|
||||
"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);
|
||||
}
|
||||
Reference in new issue
Block a user