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,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);
});
});