@starci/hfs 4.0.7 → 4.0.9

package/templates/be/patterns/event-bus/platform/index.ts.tpl

@@ -0,0 +1,11 @@
+export { EVENT_BUS_ERROR_KINDS } from "./errors/event-bus.error"
+export { parseEventBusConfig } from "./event-bus.config"
+export type { EventBusConfig } from "./event-bus.config"
+export { BaseEvent } from "./event-bus.contracts"
+export type { EventDelivery, ParsedEvent } from "./event-bus.contracts"
+export { EVENT_BUS, EVENT_TRANSPORT, InjectEventBus, InjectEventConsumerRegistry } from "./event-bus.decorators"
+export { EventBusModule } from "./event-bus.module"
+export { readEnvelope, readEventOf } from "./event-envelope.policy"
+export type { EventBus, EventConsumer, EventConsumerRegistry } from "./event-bus.port"
+export { EVENT_BUS_MESSAGES } from "./messages/event-bus.messages"
+export { eventBusEntities, eventBusMigrations } from "./persistence/connection"

package/templates/be/patterns/event-bus/platform/kafka-event-transport.client.spec.ts.tpl

@@ -0,0 +1,348 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { IDS } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import { EventBusErrorCode } from "./errors/event-bus.error"
+import { EVENT_BUS_OPTIONS, KAFKA_FACTORY } from "./event-bus.decorators"
+import type { EventBusOptions } from "./event-bus.options"
+import type {
+    InboundMessage,
+    KafkaAdmin,
+    KafkaConsumedMessage,
+    KafkaConsumer,
+    KafkaDriver,
+    KafkaFactory,
+    KafkaMessageHeaders,
+    KafkaProducer,
+    OutboundMessage,
+} from "./event-transport.port"
+import { KafkaEventTransportClient } from "./kafka-event-transport.client"
+
+const options: EventBusOptions = {
+    brokers: ["broker-1.test:9092", "broker-2.test:9092"],
+    groupId: "orders",
+    topicPrefix: "",
+    relayIntervalMs: 100,
+    relayBatch: 50,
+    timeoutMs: 3000,
+    connections: [],
+}
+
+const outbound = (topic: string, key: string): OutboundMessage => ({
+    topic,
+    key,
+    value: `value-${key}`,
+    headers: { attempt: "2" },
+})
+
+const eachMessagePayload = (
+    partition: number,
+    offset: string,
+    key: Buffer | null,
+    value: Buffer | null,
+    headers?: KafkaMessageHeaders,
+): KafkaConsumedMessage => ({
+    topic: "events.order",
+    partition,
+    message: headers === undefined ? { key, value, offset } : { key, value, offset, headers },
+})
+
+const build = async () => {
+    const kafka = mock<KafkaDriver>()
+    const producer = mock<KafkaProducer>()
+    const consumer = mock<KafkaConsumer>()
+    const admin = mock<KafkaAdmin>()
+    const ids = mock<Ids>()
+    const factory = mock<KafkaFactory>()
+    producer.connect.mockResolvedValue(undefined)
+    producer.sendBatch.mockResolvedValue([])
+    producer.disconnect.mockResolvedValue(undefined)
+    consumer.connect.mockResolvedValue(undefined)
+    consumer.subscribe.mockResolvedValue(undefined)
+    consumer.run.mockResolvedValue(undefined)
+    consumer.disconnect.mockResolvedValue(undefined)
+    admin.connect.mockResolvedValue(undefined)
+    admin.deleteGroups.mockResolvedValue([])
+    admin.disconnect.mockResolvedValue(undefined)
+    kafka.producer.mockReturnValue(producer)
+    kafka.consumer.mockReturnValue(consumer)
+    kafka.admin.mockReturnValue(admin)
+    ids.next.mockReturnValue("read-1")
+    factory.create.mockReturnValue(kafka)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            KafkaEventTransportClient,
+            { provide: EVENT_BUS_OPTIONS, useValue: options },
+            { provide: KAFKA_FACTORY, useValue: factory },
+            { provide: IDS, useValue: ids },
+        ],
+    }).compile()
+    return { client: moduleRef.get(KafkaEventTransportClient), kafka, producer, consumer, admin, ids, factory }
+}
+
+describe("KafkaEventTransportClient", () => {
+    it("configures the Kafka driver as the event-bus probe", async () => {
+        const { client, factory } = await build()
+
+        expect(client.name).toBe("event-bus")
+        expect(factory.create).toHaveBeenCalledWith({
+            clientId: "orders",
+            brokers: ["broker-1.test:9092", "broker-2.test:9092"],
+            connectionTimeout: 3000,
+            requestTimeout: 3000,
+        })
+    })
+
+    describe("send", () => {
+        it("connects one producer and batches messages by topic", async () => {
+            const { client, kafka, producer } = await build()
+            const first = outbound("events.order", "order-1")
+            const second = outbound("events.payment", "payment-1")
+            const third = outbound("events.order", "order-2")
+
+            await client.send([first, second, third])
+            await client.send([first])
+
+            expect(kafka.producer).toHaveBeenCalledTimes(1)
+            expect(producer.connect).toHaveBeenCalledTimes(1)
+            expect(producer.sendBatch).toHaveBeenNthCalledWith(1, {
+                topicMessages: [
+                    {
+                        topic: "events.order",
+                        messages: [
+                            { key: "order-1", value: "value-order-1", headers: { attempt: "2" } },
+                            { key: "order-2", value: "value-order-2", headers: { attempt: "2" } },
+                        ],
+                    },
+                    {
+                        topic: "events.payment",
+                        messages: [{ key: "payment-1", value: "value-payment-1", headers: { attempt: "2" } }],
+                    },
+                ],
+            })
+        })
+
+        it("describes a producer failure as an unavailable broker operation", async () => {
+            const { client, producer } = await build()
+            const failure = new Error("broker refused the batch")
+            producer.sendBatch.mockRejectedValue(failure)
+
+            await expect(client.send([outbound("events.order", "order-1")])).rejects.toMatchObject({
+                code: EventBusErrorCode.BrokerUnavailable,
+                params: { operation: "send" },
+                cause: failure,
+            })
+        })
+    })
+
+    describe("subscribe", () => {
+        it("connects the app consumer and maps Kafka fields and headers to an inbound message", async () => {
+            const { client, kafka, consumer } = await build()
+            const onMessage = jest.fn<Promise<void>, [InboundMessage]>().mockResolvedValue(undefined)
+
+            await client.subscribe({ topics: ["events.order", "events.order.retry"], onMessage })
+            const eachMessage = consumer.run.mock.calls[0]?.[0].eachMessage
+            await eachMessage?.(
+                eachMessagePayload(2, "7", Buffer.from("order-1"), null, {
+                    attempt: [Buffer.from("2")],
+                    reason: Buffer.from("retry"),
+                    plain: "yes",
+                    empty: [],
+                    absent: undefined,
+                }),
+            )
+
+            expect(kafka.consumer).toHaveBeenCalledWith({ groupId: "orders", allowAutoTopicCreation: true })
+            expect(consumer.connect).toHaveBeenCalledTimes(1)
+            expect(consumer.subscribe).toHaveBeenCalledWith({
+                topics: ["events.order", "events.order.retry"],
+                fromBeginning: true,
+            })
+            expect(onMessage).toHaveBeenCalledWith({
+                topic: "events.order",
+                partition: 2,
+                offset: "7",
+                key: "order-1",
+                value: "",
+                headers: { attempt: "2", reason: "retry", plain: "yes", empty: "" },
+            })
+        })
+    })
+
+    describe("lag", () => {
+        it("counts unacknowledged messages from committed offsets and partition starts", async () => {
+            const { client, admin } = await build()
+            admin.fetchTopicOffsets.mockResolvedValue([
+                { partition: 0, low: "2", high: "10", offset: "10" },
+                { partition: 1, low: "5", high: "8", offset: "8" },
+                { partition: 2, low: "0", high: "2", offset: "2" },
+            ])
+            admin.fetchOffsets.mockResolvedValue([
+                {
+                    topic: "events.order",
+                    partitions: [
+                        { partition: 0, offset: "6", metadata: null },
+                        { partition: 2, offset: "3", metadata: null },
+                    ],
+                },
+            ])
+
+            await expect(client.lag("events.order")).resolves.toBe(7)
+
+            expect(admin.connect).toHaveBeenCalledTimes(1)
+            expect(admin.fetchOffsets).toHaveBeenCalledWith({ groupId: "orders", topics: ["events.order"] })
+        })
+
+        it("answers zero when the broker does not know the topic", async () => {
+            const { client, admin } = await build()
+            admin.fetchTopicOffsets.mockRejectedValue(new Error("unknown topic"))
+            admin.fetchOffsets.mockResolvedValue([])
+
+            await expect(client.lag("events.missing")).resolves.toBe(0)
+        })
+    })
+
+    describe("read", () => {
+        it("answers no messages without opening a reader when the topic is empty", async () => {
+            const { client, kafka, admin, ids } = await build()
+            admin.fetchTopicOffsets.mockResolvedValue([])
+
+            await expect(client.read("events.order.dlq")).resolves.toEqual([])
+
+            expect(kafka.consumer).not.toHaveBeenCalled()
+            expect(ids.next).not.toHaveBeenCalled()
+        })
+
+        it("reads the whole topic, sorts partitions and offsets, then drops its temporary group", async () => {
+            const { client, kafka, consumer: reader, admin } = await build()
+            admin.fetchTopicOffsets.mockResolvedValue([
+                { partition: 0, low: "0", high: "2", offset: "2" },
+                { partition: 1, low: "0", high: "1", offset: "1" },
+            ])
+            kafka.consumer.mockReturnValue(reader)
+            reader.run.mockImplementation(async (config) => {
+                if (config.eachMessage === undefined) return
+                await config.eachMessage(eachMessagePayload(1, "0", null, Buffer.from("partition-1")))
+                await config.eachMessage(
+                    eachMessagePayload(0, "1", Buffer.from("key-1"), Buffer.from("offset-1"), {
+                        attempt: "2",
+                    }),
+                )
+                await config.eachMessage(
+                    eachMessagePayload(0, "0", Buffer.from("key-0"), Buffer.from("offset-0"), {
+                        reason: Buffer.from("failed"),
+                    }),
+                )
+            })
+            jest.spyOn(client, "wait").mockReturnValue(new Promise<void>(() => undefined))
+
+            await expect(client.read("events.order.dlq")).resolves.toEqual([
+                {
+                    topic: "events.order.dlq",
+                    partition: 0,
+                    offset: "0",
+                    key: "key-0",
+                    value: "offset-0",
+                    headers: { reason: "failed" },
+                },
+                {
+                    topic: "events.order.dlq",
+                    partition: 0,
+                    offset: "1",
+                    key: "key-1",
+                    value: "offset-1",
+                    headers: { attempt: "2" },
+                },
+                {
+                    topic: "events.order.dlq",
+                    partition: 1,
+                    offset: "0",
+                    key: "",
+                    value: "partition-1",
+                    headers: {},
+                },
+            ])
+            expect(reader.disconnect).toHaveBeenCalledTimes(1)
+            expect(admin.deleteGroups).toHaveBeenCalledWith(["orders.read.read-1"])
+        })
+
+        it("answers the messages found before the read deadline", async () => {
+            const { client, kafka, consumer: reader, admin } = await build()
+            admin.fetchTopicOffsets.mockResolvedValue([{ partition: 0, low: "0", high: "2", offset: "2" }])
+            kafka.consumer.mockReturnValue(reader)
+            reader.run.mockImplementation(async (config) => {
+                await config.eachMessage?.(eachMessagePayload(0, "0", Buffer.from("key-0"), Buffer.from("offset-0")))
+            })
+            jest.spyOn(client, "wait").mockResolvedValue(undefined)
+
+            await expect(client.read("events.order.dlq")).resolves.toHaveLength(1)
+        })
+
+        it("disconnects and tolerates group cleanup failure when opening the reader fails", async () => {
+            const { client, kafka, consumer: reader, admin } = await build()
+            const failure = new Error("reader unavailable")
+            admin.fetchTopicOffsets.mockResolvedValue([{ partition: 0, low: "0", high: "1", offset: "1" }])
+            admin.deleteGroups.mockRejectedValue(new Error("group already gone"))
+            kafka.consumer.mockReturnValue(reader)
+            reader.connect.mockRejectedValue(failure)
+
+            await expect(client.read("events.order.dlq")).rejects.toMatchObject({
+                code: EventBusErrorCode.BrokerUnavailable,
+                params: { operation: "read" },
+                cause: failure,
+            })
+            expect(reader.disconnect).toHaveBeenCalledTimes(1)
+            expect(admin.deleteGroups).toHaveBeenCalledWith(["orders.read.read-1"])
+        })
+    })
+
+    it("waits for the requested delay", async () => {
+        jest.useFakeTimers()
+        const { client } = await build()
+
+        const waiting = client.wait(25)
+        jest.advanceTimersByTime(25)
+
+        await expect(waiting).resolves.toBeUndefined()
+        jest.useRealTimers()
+    })
+
+    it("checks broker metadata through one connected admin client", async () => {
+        const { client, kafka, admin } = await build()
+        admin.listTopics.mockResolvedValue(["events.order"])
+
+        await client.check()
+        await client.check()
+
+        expect(kafka.admin).toHaveBeenCalledTimes(1)
+        expect(admin.connect).toHaveBeenCalledTimes(1)
+        expect(admin.listTopics).toHaveBeenCalledTimes(2)
+    })
+
+    describe("onApplicationShutdown", () => {
+        it("does nothing when no broker client was opened", async () => {
+            const { client, producer, consumer, admin } = await build()
+
+            await expect(client.onApplicationShutdown()).resolves.toBeUndefined()
+
+            expect(producer.disconnect).not.toHaveBeenCalled()
+            expect(consumer.disconnect).not.toHaveBeenCalled()
+            expect(admin.disconnect).not.toHaveBeenCalled()
+        })
+
+        it("disconnects every opened client and tolerates an already-gone client", async () => {
+            const { client, producer, consumer, admin } = await build()
+            producer.disconnect.mockRejectedValue(new Error("producer already gone"))
+            admin.listTopics.mockResolvedValue([])
+            await client.send([outbound("events.order", "order-1")])
+            await client.subscribe({ topics: ["events.order"], onMessage: () => Promise.resolve() })
+            await client.check()
+
+            await expect(client.onApplicationShutdown()).resolves.toBeUndefined()
+
+            expect(producer.disconnect).toHaveBeenCalledTimes(1)
+            expect(consumer.disconnect).toHaveBeenCalledTimes(1)
+            expect(admin.disconnect).toHaveBeenCalledTimes(1)
+        })
+    })
+})

package/templates/be/patterns/event-bus/platform/kafka-event-transport.client.ts.tpl

@@ -0,0 +1,241 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationShutdown } from "@nestjs/common"
+import { InjectIds } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
+import type { Probe } from "@modules/platform/probes"
+import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
+import { InjectEventBusOptions, InjectKafkaFactory } from "./event-bus.decorators"
+import type { EventBusOptions } from "./event-bus.options"
+import type {
+    EventSubscription,
+    EventTransport,
+    InboundMessage,
+    KafkaAdmin,
+    KafkaConsumer,
+    KafkaDriver,
+    KafkaFactory,
+    KafkaMessageHeaders,
+    KafkaProducer,
+    OutboundMessage,
+} from "./event-transport.port"
+
+/** How long a read of a whole topic may take before it is given up. */
+const READ_DEADLINE_MS = 15_000
+
+/** The text of a header value or message field the library hands over as a buffer or text. */
+const textOf = (value: Buffer | string | null | undefined): string =>
+    value === null || value === undefined ? "" : value.toString()
+
+/** The end offsets of a topic as the broker answers them; a topic it does not know has none and the failure rides along. */
+interface TopicEnds {
+    /** The partitions with their low and high offsets. */
+    readonly ends: ReadonlyArray<{ readonly partition: number; readonly low: string; readonly high: string }>
+    /** Why the broker did not answer; null when it did. */
+    readonly cause: unknown
+}
+
+/** The text headers of a message. */
+const headersOf = (headers: KafkaMessageHeaders | undefined): Record<string, string> =>
+    Object.fromEntries(
+        Object.entries(headers ?? {}).flatMap(([name, value]) =>
+            value === undefined ? [] : [[name, Array.isArray(value) ? textOf(value[0]) : textOf(value)] as const],
+        ),
+    )
+
+@Injectable()
+/**
+ * The Kafka adapter of the event transport and the health probe of the broker; the driver is built by the injected factory,
+ * whose default the module composes, so the client holds logic only.
+ * One producer sends every outbound message, one consumer of the app's group reads the registered topics, and a short-lived
+ * consumer of its own group reads a whole topic for the operator calls.
+ */
+export class KafkaEventTransportClient implements EventTransport, Probe, OnApplicationShutdown {
+    /** The name the health report lists this probe under. */
+    readonly name = "event-bus"
+
+    private readonly kafka: KafkaDriver
+    private producer: KafkaProducer | null = null
+    private consumer: KafkaConsumer | null = null
+    private admin: KafkaAdmin | null = null
+
+    constructor(
+        @InjectEventBusOptions() private readonly options: EventBusOptions,
+        @InjectKafkaFactory() factory: KafkaFactory,
+        @InjectIds() private readonly ids: Ids,
+    ) {
+        this.kafka = factory.create({
+            clientId: options.groupId,
+            brokers: [...options.brokers],
+            connectionTimeout: options.timeoutMs,
+            requestTimeout: options.timeoutMs,
+        })
+    }
+
+    /** Appends the messages to their topics in one batch. */
+    async send(messages: ReadonlyArray<OutboundMessage>): Promise<void> {
+        const topics = [...new Set(messages.map((message) => message.topic))]
+        await this.run("send", async () => {
+            const producer = await this.producerOf()
+            await producer.sendBatch({
+                topicMessages: topics.map((topic) => ({
+                    topic,
+                    messages: messages
+                        .filter((message) => message.topic === topic)
+                        .map((message) => ({
+                            key: message.key,
+                            value: message.value,
+                            headers: { ...message.headers },
+                        })),
+                })),
+            })
+        })
+    }
+
+    /** Starts the consumer of the app's group on the topics; messages are read from the start of a topic the group has no offset on. */
+    async subscribe(subscription: EventSubscription): Promise<void> {
+        await this.run("subscribe", async () => {
+            const consumer = this.kafka.consumer({ groupId: this.options.groupId, allowAutoTopicCreation: true })
+            this.consumer = consumer
+            await consumer.connect()
+            await consumer.subscribe({ topics: [...subscription.topics], fromBeginning: true })
+            await consumer.run({
+                eachMessage: async ({ topic, partition, message }) => {
+                    await subscription.onMessage({
+                        topic,
+                        partition,
+                        offset: message.offset,
+                        key: textOf(message.key),
+                        value: textOf(message.value),
+                        headers: headersOf(message.headers),
+                    })
+                },
+            })
+        })
+    }
+
+    /** How many messages of the topic the group of the app has not acknowledged yet; a topic that does not exist has none. */
+    async lag(topic: string): Promise<number> {
+        return this.run("lag", async () => {
+            const admin = await this.adminOf()
+            const { ends } = await this.endsOf(admin, topic)
+            const committed = await admin.fetchOffsets({ groupId: this.options.groupId, topics: [topic] })
+            const acknowledged = new Map(
+                (committed[0]?.partitions ?? []).map((entry) => [entry.partition, Number(entry.offset)] as const),
+            )
+            return ends.reduce((sum, end) => {
+                const done = acknowledged.get(end.partition) ?? -1
+                return sum + Math.max(0, Number(end.high) - (done < 0 ? Number(end.low) : done))
+            }, 0)
+        })
+    }
+
+    /** Every message of the topic, oldest first, read by a consumer of its own group that is dropped afterwards. */
+    async read(topic: string): Promise<ReadonlyArray<InboundMessage>> {
+        return this.run("read", async () => {
+            const admin = await this.adminOf()
+            const { ends } = await this.endsOf(admin, topic)
+            const expected = ends.reduce((sum, end) => sum + (Number(end.high) - Number(end.low)), 0)
+            if (expected === 0) return []
+            const groupId = `${this.options.groupId}.read.${this.ids.next()}`
+            const reader = this.kafka.consumer({ groupId })
+            const found: Array<InboundMessage> = []
+            try {
+                await reader.connect()
+                await reader.subscribe({ topic, fromBeginning: true })
+                const complete = new Promise<void>((resolve) => {
+                    void reader.run({
+                        eachMessage: ({ partition, message }) => {
+                            found.push({
+                                topic,
+                                partition,
+                                offset: message.offset,
+                                key: textOf(message.key),
+                                value: textOf(message.value),
+                                headers: headersOf(message.headers),
+                            })
+                            if (found.length >= expected) resolve()
+                            return Promise.resolve()
+                        },
+                    })
+                })
+                await Promise.race([complete, this.wait(READ_DEADLINE_MS)])
+            } finally {
+                await reader.disconnect()
+                await this.dropGroup(admin, groupId)
+            }
+            return found.sort((a, b) => a.partition - b.partition || Number(a.offset) - Number(b.offset))
+        })
+    }
+
+    /** Resolves after `ms` milliseconds. */
+    wait(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms))
+    }
+
+    /** Resolves when the broker answers a metadata request. */
+    async check(): Promise<void> {
+        await this.run("check", async () => {
+            await (await this.adminOf()).listTopics()
+        })
+    }
+
+    /** Disconnects the producer, the consumer and the admin client. */
+    async onApplicationShutdown(): Promise<void> {
+        for (const client of [this.producer, this.consumer, this.admin]) await this.close(client)
+    }
+
+    /** The end offsets of the topic; a topic that does not exist yet answers no partitions and the cause. */
+    private async endsOf(admin: KafkaAdmin, topic: string): Promise<TopicEnds> {
+        try {
+            return { ends: await admin.fetchTopicOffsets(topic), cause: null }
+        } catch (cause) {
+            return { ends: [], cause }
+        }
+    }
+
+    /** Deletes the consumer group of a read; a group the broker already dropped is not a failure of the read. */
+    private async dropGroup(admin: KafkaAdmin, groupId: string): Promise<unknown> {
+        try {
+            await admin.deleteGroups([groupId])
+            return null
+        } catch (cause) {
+            return cause
+        }
+    }
+
+    /** Disconnects a client that was opened; the failure of a client that is already gone is the answer, not an error of the shutdown. */
+    private async close(client: Pick<KafkaProducer, "disconnect"> | null): Promise<unknown> {
+        try {
+            await client?.disconnect()
+            return null
+        } catch (cause) {
+            return cause
+        }
+    }
+
+    private async producerOf(): Promise<KafkaProducer> {
+        if (this.producer === null) {
+            const producer = this.kafka.producer({ allowAutoTopicCreation: true })
+            await producer.connect()
+            this.producer = producer
+        }
+        return this.producer
+    }
+
+    private async adminOf(): Promise<KafkaAdmin> {
+        if (this.admin === null) {
+            const admin = this.kafka.admin()
+            await admin.connect()
+            this.admin = admin
+        }
+        return this.admin
+    }
+
+    private async run<TResult>(operation: string, call: () => Promise<TResult>): Promise<TResult> {
+        try {
+            return await call()
+        } catch (cause) {
+            throw new EventBusError({ code: EventBusErrorCode.BrokerUnavailable, params: { operation }, cause })
+        }
+    }
+}

package/templates/be/patterns/event-bus/platform/messages/event-bus.messages.ts.tpl

@@ -0,0 +1,15 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the event-bus codes, Vietnamese and English. */
+export const EVENT_BUS_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.EVENT_BUS_ENVELOPE_INVALID": "Sự kiện {{event}} nhận được có nội dung không đúng dạng.",
+        "errors.EVENT_BUS_BROKER_UNAVAILABLE": "Kênh sự kiện {{operation}} không phản hồi kịp.",
+        "errors.EVENT_BUS_DEAD_LETTER_UNKNOWN": "Không có sự kiện lỗi {{id}} để đưa lại.",
+    },
+    en: {
+        "errors.EVENT_BUS_ENVELOPE_INVALID": "The received {{event}} event has a payload of the wrong shape.",
+        "errors.EVENT_BUS_BROKER_UNAVAILABLE": "The event broker did not answer {{operation}} in time.",
+        "errors.EVENT_BUS_DEAD_LETTER_UNKNOWN": "There is no dead letter {{id}} to requeue.",
+    },
+}

package/templates/be/patterns/event-bus/platform/persistence/connection.ts.tpl

@@ -0,0 +1,8 @@
+import { EventOutboxEntity } from "./entities/event-outbox.entity"
+import { CreateEventOutbox@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-event-outbox"
+
+/** The entities of the event bus, for every connection that publishes events. */
+export const eventBusEntities = [EventOutboxEntity]
+
+/** The migrations of the event bus, in the order they run. */
+export const eventBusMigrations = [CreateEventOutbox@@epochMs13@@]

package/templates/be/patterns/event-bus/platform/persistence/entities/event-outbox.entity.ts.tpl

@@ -0,0 +1,37 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+@Entity("event_outbox")
+/** One event waiting to leave the service: written in the transaction of the change it reports, handed to the broker by the relay. */
+export class EventOutboxEntity {
+    /** The position of the row: the relay sends the rows in this order. */
+    @PrimaryGeneratedColumn("increment", { type: "bigint" })
+    id!: string
+
+    /** The stable event id; a repeat of one logical event carries the same id. */
+    @Column({ name: "event_id", type: "varchar", length: 200 })
+    eventId!: string
+
+    /** The event name. */
+    @Column({ name: "event_name", type: "varchar", length: 200 })
+    eventName!: string
+
+    /** The topic the event travels on. */
+    @Column({ name: "topic", type: "varchar", length: 200 })
+    topic!: string
+
+    /** The partition key: events of one key keep their order. */
+    @Column({ name: "message_key", type: "varchar", length: 200 })
+    messageKey!: string
+
+    /** The envelope `{ eventId, eventName, payload }`. */
+    @Column({ name: "envelope", type: "jsonb" })
+    envelope!: object
+
+    /** When the row was written. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+
+    /** When the relay handed the row to the broker; null while it waits. */
+    @Column({ name: "sent_at", type: "timestamptz", nullable: true })
+    sentAt!: Date | null
+}

package/templates/be/patterns/event-bus/platform/persistence/event-bus.rows.ts.tpl

@@ -0,0 +1,11 @@
+/** One row the relay reads from the outbox. */
+export interface OutboxRow {
+    /** The position of the row (a bigint arrives as text). */
+    readonly id: string
+    /** The topic the event travels on. */
+    readonly topic: string
+    /** The partition key. */
+    readonly message_key: string
+    /** The envelope, as the database returns the jsonb value. */
+    readonly envelope: object
+}