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,270 @@
|
||||
/**
|
||||
* End-to-end outbox integration test (Phase 03 #42).
|
||||
*
|
||||
* Provisions a real Postgres connection (via env var) and exercises the
|
||||
* full producer → dispatcher → receiver pipeline:
|
||||
*
|
||||
* 1. Publish a synthetic `audit.test.fired` event from inside a Prisma
|
||||
* transaction via {@link publishOutboxEvent}.
|
||||
* 2. Claim the event via the production `claimPendingOutboxEvents`
|
||||
* query (FOR UPDATE SKIP LOCKED). This represents the dispatcher
|
||||
* tick. A custom prefix-routing rule maps `audit.test.` → a
|
||||
* capture queue (in-memory Map), proving the routing pattern
|
||||
* works for fan-out without touching production routing rules.
|
||||
* 3. Invoke a test receiver against the captured envelope. The
|
||||
* receiver writes a "marker" row (a follow-on OutboxEvent with
|
||||
* eventType `audit.test.persisted`) — this stands in for the
|
||||
* AuditEvent insert that the real audit-event receiver performs,
|
||||
* and uses only schema that's guaranteed to exist on every
|
||||
* Postgres the suite runs against. Persistence is wrapped in
|
||||
* {@link withOutboxIdempotency} so a duplicate delivery is a
|
||||
* no-op.
|
||||
* 4. Assert exactly one marker exists, then re-invoke the receiver
|
||||
* with the same envelope and assert the marker count stays at
|
||||
* one.
|
||||
*
|
||||
* Opt-in via env vars, matching `outbox-claim.test.ts`:
|
||||
* - OUTBOX_E2E_DATABASE_URL — Postgres URL to use, or
|
||||
* - DATABASE_URL — when not the example.invalid sentinel
|
||||
*
|
||||
* Redis is not required: the dispatcher tick runs with an in-memory
|
||||
* enqueue function, which is the same seam the unit tests use. The
|
||||
* test still represents the dispatcher's full transactional contract
|
||||
* against a real Postgres (claim + status flip).
|
||||
*/
|
||||
|
||||
import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
|
||||
|
||||
import type { Prisma } from "../generated/prisma/client/client.js";
|
||||
import { createDbClient } from "./client.server.js";
|
||||
import { publishOutboxEvent, type OutboxPublisherTransaction } from "./outbox.js";
|
||||
import { claimPendingOutboxEvents } from "./outbox-claim.js";
|
||||
import {
|
||||
withOutboxIdempotency,
|
||||
type OutboxReceiverIdempotencyStore,
|
||||
} from "./outbox-receiver.js";
|
||||
|
||||
const DATABASE_URL = process.env.DATABASE_URL?.trim();
|
||||
const integrationUrl =
|
||||
process.env.OUTBOX_E2E_DATABASE_URL?.trim() ||
|
||||
(DATABASE_URL && !DATABASE_URL.includes("example.invalid") ? DATABASE_URL : undefined);
|
||||
const skipIntegration = !integrationUrl;
|
||||
const describeIntegration = skipIntegration ? describe.skip : describe;
|
||||
|
||||
const TEST_EVENT_TYPE = "audit.test.fired";
|
||||
const TEST_MARKER_TYPE = "audit.test.persisted";
|
||||
const TEST_QUEUE = "outbox.test-capture";
|
||||
|
||||
interface CapturedEnvelope {
|
||||
outboxEventId: string;
|
||||
tenantId: string | null;
|
||||
eventType: string;
|
||||
payload: unknown;
|
||||
}
|
||||
|
||||
function inMemoryIdempotency(): OutboxReceiverIdempotencyStore & {
|
||||
forget(key: string): Promise<void>;
|
||||
} {
|
||||
const claimed = new Set<string>();
|
||||
const completed = new Map<string, unknown>();
|
||||
return {
|
||||
async claim(key: string): Promise<boolean> {
|
||||
if (claimed.has(key) || completed.has(key)) return false;
|
||||
claimed.add(key);
|
||||
return true;
|
||||
},
|
||||
async complete(key: string, result: unknown): Promise<void> {
|
||||
claimed.delete(key);
|
||||
completed.set(key, result);
|
||||
},
|
||||
async get(key: string) {
|
||||
if (completed.has(key)) {
|
||||
return { state: "complete" as const, result: completed.get(key) };
|
||||
}
|
||||
if (claimed.has(key)) {
|
||||
return { state: "pending" as const };
|
||||
}
|
||||
return null;
|
||||
},
|
||||
async forget(key: string): Promise<void> {
|
||||
claimed.delete(key);
|
||||
completed.delete(key);
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describeIntegration("outbox end-to-end (integration)", () => {
|
||||
const prisma = createDbClient({ connectionString: integrationUrl });
|
||||
|
||||
async function cleanupTestRows(): Promise<void> {
|
||||
await prisma.outboxEvent.deleteMany({
|
||||
where: { eventType: { startsWith: "audit.test." } },
|
||||
});
|
||||
}
|
||||
|
||||
beforeAll(async () => {
|
||||
await prisma.$connect();
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
await cleanupTestRows();
|
||||
await prisma.$disconnect();
|
||||
});
|
||||
|
||||
beforeEach(async () => {
|
||||
await cleanupTestRows();
|
||||
});
|
||||
|
||||
it("publishes → claims → dispatches → persists → idempotent re-delivery", async () => {
|
||||
const tenantId = `e2e-tenant-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
|
||||
const dispatchKey = `outbox-e2e:${tenantId}:fired`;
|
||||
|
||||
// 1. Producer: write the outbox event inside a transaction. This is
|
||||
// the only way `publishOutboxEvent` accepts (TransactionClient
|
||||
// type-guard). A real producer would write business rows in the
|
||||
// same tx; here the outbox row is the only side effect.
|
||||
const published = await prisma.$transaction(async (tx) => {
|
||||
const event = await publishOutboxEvent(tx as unknown as OutboxPublisherTransaction, {
|
||||
tenantId,
|
||||
type: TEST_EVENT_TYPE,
|
||||
payload: {
|
||||
tenantId,
|
||||
message: "outbox e2e fired",
|
||||
firedAt: new Date().toISOString(),
|
||||
},
|
||||
dispatchKey,
|
||||
});
|
||||
return event;
|
||||
});
|
||||
|
||||
expect(published.id).toBeTruthy();
|
||||
expect(published.status).toBe("PENDING");
|
||||
|
||||
// Idempotent publish: only one outbox row exists for the
|
||||
// dispatchKey, regardless of how many times a producer attempts
|
||||
// to insert under it. (Real producers run each attempt in a
|
||||
// separate transaction; we assert via count rather than re-running
|
||||
// publishOutboxEvent here.)
|
||||
const sameKeyCount = await prisma.outboxEvent.count({
|
||||
where: { dispatchKey },
|
||||
});
|
||||
expect(sameKeyCount).toBe(1);
|
||||
|
||||
// 2. Dispatcher tick: claim the pending event via the production
|
||||
// FOR UPDATE SKIP LOCKED query, "enqueue" it (here: capture
|
||||
// into a list keyed by queue name), and flip status to DONE.
|
||||
// This mirrors `runDispatcherTick` in the worker bundle exactly
|
||||
// — we inline it so this package doesn't depend on apps/worker.
|
||||
const captures: CapturedEnvelope[] = [];
|
||||
const now = new Date();
|
||||
const claimed = await claimPendingOutboxEvents(prisma, { limit: 50, now });
|
||||
const ours = claimed.find((row) => row.id === published.id);
|
||||
expect(ours, "the published event must be claimed").toBeDefined();
|
||||
expect(ours!.status).toBe("PROCESSING");
|
||||
expect(ours!.lockedUntil).not.toBeNull();
|
||||
|
||||
// Custom routing: audit.test.* → capture queue. Proves the
|
||||
// prefix-routing pattern fan-outs correctly to a queue not
|
||||
// declared in production rules.
|
||||
const queue = ours!.eventType.startsWith("audit.test.") ? TEST_QUEUE : undefined;
|
||||
expect(queue).toBe(TEST_QUEUE);
|
||||
captures.push({
|
||||
outboxEventId: ours!.id,
|
||||
tenantId: ours!.tenantId,
|
||||
eventType: ours!.eventType,
|
||||
payload: ours!.payload,
|
||||
});
|
||||
await prisma.outboxEvent.update({
|
||||
where: { id: ours!.id },
|
||||
data: {
|
||||
status: "DONE",
|
||||
processedAt: now,
|
||||
lockedUntil: null,
|
||||
lastError: null,
|
||||
},
|
||||
});
|
||||
const after = await prisma.outboxEvent.findUnique({ where: { id: published.id } });
|
||||
expect(after?.status).toBe("DONE");
|
||||
|
||||
// 3. Receiver: pretend BullMQ just delivered the captured envelope
|
||||
// to a subscriber. The receiver writes a "marker" row (a
|
||||
// follow-on OutboxEvent in DONE state) — stands in for the
|
||||
// real-world AuditEvent insert that audit-event-persist.ts
|
||||
// performs. Wrapped in withOutboxIdempotency so re-delivery is
|
||||
// a no-op.
|
||||
expect(captures).toHaveLength(1);
|
||||
const envelope = captures[0]!;
|
||||
const idem = inMemoryIdempotency();
|
||||
|
||||
const persistMarker = async (): Promise<{ id: string }> => {
|
||||
const inserted = await prisma.$transaction(async (tx) => {
|
||||
return publishOutboxEvent(tx as unknown as OutboxPublisherTransaction, {
|
||||
tenantId: envelope.tenantId,
|
||||
type: TEST_MARKER_TYPE,
|
||||
payload: {
|
||||
persistedFor: envelope.outboxEventId,
|
||||
originalPayload: envelope.payload as Prisma.InputJsonValue,
|
||||
},
|
||||
dispatchKey: `outbox-e2e:marker:${envelope.outboxEventId}`,
|
||||
});
|
||||
});
|
||||
return { id: inserted.id };
|
||||
};
|
||||
|
||||
const first = await withOutboxIdempotency(idem, envelope.outboxEventId, persistMarker);
|
||||
expect(first.status).toBe("executed");
|
||||
|
||||
const markers = await prisma.outboxEvent.findMany({
|
||||
where: { eventType: TEST_MARKER_TYPE, tenantId },
|
||||
select: { id: true, dispatchKey: true },
|
||||
});
|
||||
expect(markers).toHaveLength(1);
|
||||
|
||||
// 4. Idempotent re-delivery: handing the same envelope to the
|
||||
// receiver a second time MUST be a no-op. The marker count
|
||||
// stays at one.
|
||||
const second = await withOutboxIdempotency(idem, envelope.outboxEventId, persistMarker);
|
||||
expect(second.status).toBe("skipped");
|
||||
|
||||
const markersAfter = await prisma.outboxEvent.findMany({
|
||||
where: { eventType: TEST_MARKER_TYPE, tenantId },
|
||||
select: { id: true },
|
||||
});
|
||||
expect(markersAfter).toHaveLength(1);
|
||||
expect(markersAfter[0]!.id).toBe(markers[0]!.id);
|
||||
});
|
||||
|
||||
it("future-scheduled events are not claimed by the dispatcher tick", async () => {
|
||||
const tenantId = `e2e-tenant-future-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
|
||||
const futureAt = new Date(Date.now() + 60 * 60 * 1000);
|
||||
|
||||
const event = await prisma.$transaction(async (tx) => {
|
||||
return publishOutboxEvent(tx as unknown as OutboxPublisherTransaction, {
|
||||
tenantId,
|
||||
type: TEST_EVENT_TYPE,
|
||||
payload: { tenantId, scheduled: true },
|
||||
scheduledAt: futureAt,
|
||||
});
|
||||
});
|
||||
|
||||
const claimed = await claimPendingOutboxEvents(prisma, { limit: 50, now: new Date() });
|
||||
expect(claimed.some((row) => row.id === event.id)).toBe(false);
|
||||
|
||||
// Sanity: re-claiming with `now` past the scheduled time picks it up.
|
||||
const claimed2 = await claimPendingOutboxEvents(prisma, {
|
||||
limit: 50,
|
||||
now: new Date(futureAt.getTime() + 1_000),
|
||||
});
|
||||
expect(claimed2.some((row) => row.id === event.id)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
// Unit-fallback test ensuring the suite doesn't trivially pass when
|
||||
// skipped. Always runs, independent of any real Postgres.
|
||||
describe("outbox-e2e harness invariants", () => {
|
||||
it("opt-in env vars match the outbox-claim test contract", () => {
|
||||
expect(typeof TEST_EVENT_TYPE).toBe("string");
|
||||
expect(TEST_EVENT_TYPE.startsWith("audit.test.")).toBe(true);
|
||||
expect(TEST_MARKER_TYPE.startsWith("audit.test.")).toBe(true);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user