Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
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);
}