280 lines
11 KiB
TypeScript
280 lines
11 KiB
TypeScript
/**
|
|
* 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 { databaseTargetLabel, isDatabaseReachable } from "./database-reachable.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);
|
|
|
|
// A non-sentinel URL is necessary but not sufficient: the CI "Workspace
|
|
// package tests" job injects a localhost DATABASE_URL without running a
|
|
// Postgres service, so probe the server before connecting and skip (rather
|
|
// than fail with P1001) when nothing is reachable.
|
|
const databaseReachable = integrationUrl ? await isDatabaseReachable(integrationUrl) : false;
|
|
if (integrationUrl && !databaseReachable) {
|
|
console.warn(`[outbox-e2e] skipped: no database reachable at ${databaseTargetLabel(integrationUrl)}`);
|
|
}
|
|
const describeIntegration = databaseReachable ? describe : describe.skip;
|
|
|
|
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);
|
|
});
|
|
});
|