@starci/hfs 4.0.8 → 4.0.10

package/templates/be/patterns/event-bus/platform/event-runner.service.spec.ts.tpl

@@ -0,0 +1,272 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, mock } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { BaseEvent } from "./event-bus.contracts"
+import type { ParsedEvent } from "./event-bus.contracts"
+import { EVENT_BUS_OPTIONS, EVENT_TRANSPORT } from "./event-bus.decorators"
+import { EventBusLogEvent } from "./event-bus.log-events"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventConsumer } from "./event-bus.port"
+import { readEnvelope } from "./event-envelope.policy"
+import { EventRunnerService } from "./event-runner.service"
+import type { EventSubscription, EventTransport, InboundMessage } from "./event-transport.port"
+
+const AT = "2026-02-03T04:05:06.000Z"
+const NOW = new Date(AT).getTime()
+
+const options: EventBusOptions = {
+    brokers: ["localhost:9094"],
+    groupId: "app",
+    topicPrefix: "run-1.",
+    relayIntervalMs: 100,
+    relayBatch: 50,
+    timeoutMs: 3000,
+    connections: [],
+}
+
+interface PingPayload {
+    readonly ref: string
+}
+
+class PingEvent extends BaseEvent {
+    static readonly eventName = "probe.ping"
+    static readonly version = 1
+
+    readonly eventName = PingEvent.eventName
+
+    constructor(
+        readonly eventId: string,
+        readonly payload: PingPayload,
+    ) {
+        super()
+    }
+
+    static parse(envelope: unknown): ParsedEvent<PingEvent> {
+        const read = readEnvelope(envelope)
+        return read !== null && typeof read.payload.ref === "string"
+            ? new PingEvent(read.eventId, { ref: read.payload.ref })
+            : null
+    }
+}
+
+const message = (overrides: Partial<InboundMessage> = {}): InboundMessage => ({
+    topic: "run-1.events.probe",
+    partition: 0,
+    offset: "4",
+    key: "o-1",
+    value: JSON.stringify({ eventId: "o-1", eventName: "probe.ping", payload: { ref: "o-1" } }),
+    headers: {},
+    ...overrides,
+})
+
+const build = async (register = true) => {
+    const transport = mock<EventTransport>()
+    const logger = mock<Logger>()
+    const handle = jest.fn<Promise<void>, Array<never>>()
+    const subscriptions: Array<EventSubscription> = []
+    transport.subscribe.mockImplementation((subscription) => {
+        subscriptions.push(subscription)
+        return Promise.resolve()
+    })
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            EventRunnerService,
+            { provide: EVENT_BUS_OPTIONS, useValue: options },
+            { provide: EVENT_TRANSPORT, useValue: transport },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    const runner = moduleRef.get(EventRunnerService)
+    if (register) {
+        const consumer: EventConsumer<PingEvent> = { event: PingEvent, handle }
+        runner.add(consumer)
+    }
+    return { runner, transport, logger, handle, subscriptions }
+}
+
+describe("EventRunnerService", () => {
+    describe("onApplicationBootstrap", () => {
+        it("subscribes to the main and retry topic of every registered event", async () => {
+            const { runner, subscriptions } = await build()
+
+            await runner.onApplicationBootstrap()
+
+            expect(subscriptions.map((subscription) => subscription.topics)).toEqual([
+                ["run-1.events.probe", "run-1.events.probe.retry"],
+            ])
+        })
+
+        it("subscribes to nothing when no consumer registered", async () => {
+            const { runner, transport } = await build(false)
+
+            await runner.onApplicationBootstrap()
+
+            expect(transport.subscribe).not.toHaveBeenCalled()
+        })
+
+        it("hands what the transport delivers to receive", async () => {
+            const { runner, subscriptions, handle } = await build()
+            handle.mockResolvedValue(undefined)
+            await runner.onApplicationBootstrap()
+
+            await subscriptions[0]?.onMessage(message())
+
+            expect(handle).toHaveBeenCalledTimes(1)
+        })
+    })
+
+    describe("receive", () => {
+        it("hands the parsed event to its consumer with the event id and the first attempt", async () => {
+            const { runner, handle, transport } = await build()
+            handle.mockResolvedValue(undefined)
+
+            await runner.receive(message())
+
+            expect(handle).toHaveBeenCalledWith({
+                eventId: "o-1",
+                event: new PingEvent("o-1", { ref: "o-1" }),
+                attempt: 1,
+            })
+            expect(transport.send).not.toHaveBeenCalled()
+        })
+
+        it("hands one event to every consumer registered for it and retries it once when any of them failed", async () => {
+            const { runner, handle, transport } = await build()
+            const second = jest.fn<Promise<void>, Array<never>>()
+            const third = jest.fn<Promise<void>, Array<never>>()
+            handle.mockRejectedValue(new Error("the first consumer failed"))
+            second.mockResolvedValue(undefined)
+            third.mockRejectedValue(new Error("the third consumer failed too"))
+            runner.add({ event: PingEvent, handle: second })
+            runner.add({ event: PingEvent, handle: third })
+
+            await runner.receive(message())
+
+            expect(second).toHaveBeenCalledTimes(1)
+            expect(third).toHaveBeenCalledTimes(1)
+            expect(transport.send).toHaveBeenCalledTimes(1)
+        })
+
+        it("leaves an event nobody here consumes alone", async () => {
+            const { runner, handle, transport, logger } = await build()
+
+            await runner.receive(
+                message({ value: JSON.stringify({ eventId: "x", eventName: "probe.other", payload: {} }) }),
+            )
+
+            expect(handle).not.toHaveBeenCalled()
+            expect(transport.send).not.toHaveBeenCalled()
+            expect(logger.warn).not.toHaveBeenCalled()
+        })
+
+        it("logs and skips a value that is not an envelope", async () => {
+            const { runner, handle, logger } = await build()
+
+            await runner.receive(message({ value: "not json" }))
+            await runner.receive(message({ value: JSON.stringify([1]) }))
+
+            expect(handle).not.toHaveBeenCalled()
+            expect(logger.error).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, expect.any(SyntaxError), {
+                topic: "run-1.events.probe",
+            })
+            expect(logger.warn).toHaveBeenCalledTimes(1)
+            expect(logger.warn).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, { topic: "run-1.events.probe" })
+        })
+
+        it("buries an envelope the event class cannot read, without retrying it", async () => {
+            const { runner, handle, transport } = await build()
+            const value = JSON.stringify({ eventId: "o-2", eventName: "probe.ping", payload: {} })
+
+            await runner.receive(message({ key: "o-2", value }))
+
+            expect(handle).not.toHaveBeenCalled()
+            expect(transport.send).toHaveBeenCalledWith([
+                {
+                    topic: "run-1.events.probe.dlq",
+                    key: "o-2",
+                    value,
+                    headers: {
+                        attempt: "1",
+                        reason: "the envelope does not have the shape of the event",
+                        "origin-topic": "run-1.events.probe",
+                    },
+                },
+            ])
+        })
+
+        it("puts a failed delivery on the retry topic with the next attempt and a doubled backoff", async () => {
+            const { runner, handle, transport, logger } = await build()
+            const failure = new Error("the database is down")
+            handle.mockRejectedValue(failure)
+
+            await runner.receive(message({ headers: { attempt: "2" } }))
+
+            expect(transport.send).toHaveBeenCalledWith([
+                {
+                    topic: "run-1.events.probe.retry",
+                    key: "o-1",
+                    value: message().value,
+                    headers: { attempt: "3", "not-before": String(NOW + 1000) },
+                },
+            ])
+            expect(logger.error).toHaveBeenCalledWith(EventBusLogEvent.DeliveryFailed, failure, {
+                event: "probe.ping",
+                attempt: 2,
+            })
+            expect(logger.warn).toHaveBeenCalledWith(EventBusLogEvent.DeliveryRetried, {
+                event: "probe.ping",
+                attempt: 2,
+                reason: "the database is down",
+            })
+        })
+
+        it("buries the delivery that ran out of attempts, naming the reason and the topic it came from", async () => {
+            const { runner, handle, transport, logger } = await build()
+            handle.mockRejectedValue("a text, not an error")
+
+            await runner.receive(message({ headers: { attempt: "5" } }))
+
+            expect(transport.send).toHaveBeenCalledWith([
+                {
+                    topic: "run-1.events.probe.dlq",
+                    key: "o-1",
+                    value: message().value,
+                    headers: { attempt: "5", reason: "a text, not an error", "origin-topic": "run-1.events.probe" },
+                },
+            ])
+            expect(logger.warn).toHaveBeenCalledWith(EventBusLogEvent.DeliveryBuried, {
+                event: "probe.ping",
+                attempts: 5,
+                reason: "a text, not an error",
+            })
+        })
+
+        it("waits for the backoff of a retry message before handing it over", async () => {
+            const { runner, handle, transport } = await build()
+            handle.mockResolvedValue(undefined)
+
+            await runner.receive(
+                message({
+                    topic: "run-1.events.probe.retry",
+                    headers: { attempt: "2", "not-before": String(NOW + 800) },
+                }),
+            )
+
+            expect(transport.wait).toHaveBeenCalledWith(800)
+            expect(handle).toHaveBeenCalledWith(expect.objectContaining({ attempt: 2 }))
+        })
+
+        it("does not wait for a retry message whose backoff has passed", async () => {
+            const { runner, handle, transport } = await build()
+            handle.mockResolvedValue(undefined)
+
+            await runner.receive(message({ headers: { attempt: "2", "not-before": String(NOW - 5) } }))
+
+            expect(transport.wait).not.toHaveBeenCalled()
+            expect(handle).toHaveBeenCalledTimes(1)
+        })
+    })
+})

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

@@ -0,0 +1,128 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap } from "@nestjs/common"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import type { BaseEvent } from "./event-bus.contracts"
+import { InjectEventBusOptions, InjectEventTransport } from "./event-bus.decorators"
+import { EventBusLogEvent } from "./event-bus.log-events"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventConsumer, EventConsumerRegistry } from "./event-bus.port"
+import { readEnvelopeText } from "./event-envelope.policy"
+import type { EventTransport, InboundMessage } from "./event-transport.port"
+import {
+    ATTEMPTS,
+    ATTEMPT_HEADER,
+    NOT_BEFORE_HEADER,
+    ORIGIN_HEADER,
+    REASON_HEADER,
+    backoffMs,
+    deadLetterTopicOf,
+    retryTopicOf,
+    topicOf,
+} from "./event.policy"
+
+@Injectable()
+/**
+ * The consumer side of the event bus: the registry the message transport modules fill, and the read loop over the topics of the
+ * registered events. A delivery is at least once: the consumer acknowledges by returning; a throw puts the message on the retry
+ * topic with a doubling backoff, and after the last attempt on the dead-letter topic, where an operator reads and requeues it.
+ * The runner never throws for a failed delivery, so one poisoned event does not stop the partition behind it.
+ */
+export class EventRunnerService implements EventConsumerRegistry, OnApplicationBootstrap {
+    private readonly consumers = new Map<string, ReadonlyArray<EventConsumer<BaseEvent>>>()
+
+    constructor(
+        @InjectEventBusOptions() private readonly options: EventBusOptions,
+        @InjectEventTransport() private readonly transport: EventTransport,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    /** Registers a consumer of its event (several features may consume one event); the read loop starts when the app has registered every consumer. */
+    add<Event extends BaseEvent>(consumer: EventConsumer<Event>): void {
+        const name = consumer.event.eventName
+        this.consumers.set(name, [...(this.consumers.get(name) ?? []), consumer])
+    }
+
+    /** Starts reading the topics of the registered events and their retry topics. */
+    async onApplicationBootstrap(): Promise<void> {
+        const names = [...this.consumers.keys()]
+        if (names.length === 0) return
+        const prefix = this.options.topicPrefix
+        const topics = [...new Set(names.flatMap((name) => [topicOf(prefix, name), retryTopicOf(prefix, name)]))]
+        await this.transport.subscribe({ topics, onMessage: (message) => this.receive(message) })
+    }
+
+    /**
+     * Hands one message to every consumer of its event, in the order they registered; the events of the topic nobody here consumes
+     * are left alone. A failing consumer does not stop the others; the message goes once to the retry topic when any failed, and
+     * each consumer takes a redelivery through its own inbox, so one that already succeeded changes nothing.
+     */
+    async receive(message: InboundMessage): Promise<void> {
+        const { eventName, envelope, cause: unreadable } = readEnvelopeText(message.value)
+        const consumers = this.consumers.get(eventName) ?? []
+        if (consumers.length === 0) {
+            if (unreadable !== null)
+                this.logger.error(EventBusLogEvent.MessageSkipped, unreadable, { topic: message.topic })
+            else if (eventName === "") this.logger.warn(EventBusLogEvent.MessageSkipped, { topic: message.topic })
+            return
+        }
+        const attempt = Number(message.headers[ATTEMPT_HEADER] ?? 1)
+        const notBefore = Number(message.headers[NOT_BEFORE_HEADER] ?? 0)
+        const pause = notBefore - this.clock.now().getTime()
+        if (pause > 0) await this.transport.wait(pause)
+        const failures: Array<unknown> = []
+        for (const consumer of consumers) {
+            const event = consumer.event.parse(envelope)
+            if (event === null) {
+                await this.bury(message, eventName, attempt, "the envelope does not have the shape of the event")
+                return
+            }
+            try {
+                await consumer.handle({ eventId: event.eventId, event, attempt })
+            } catch (cause) {
+                this.logger.error(EventBusLogEvent.DeliveryFailed, cause, { event: eventName, attempt })
+                failures.push(cause)
+            }
+        }
+        const [first] = failures
+        if (failures.length > 0) {
+            await this.failed(message, eventName, attempt, first instanceof Error ? first.message : String(first))
+        }
+    }
+
+    private async failed(message: InboundMessage, eventName: string, attempt: number, reason: string): Promise<void> {
+        if (attempt >= ATTEMPTS) {
+            await this.bury(message, eventName, attempt, reason)
+            return
+        }
+        const notBefore = this.clock.now().getTime() + backoffMs(attempt)
+        await this.transport.send([
+            {
+                topic: retryTopicOf(this.options.topicPrefix, eventName),
+                key: message.key,
+                value: message.value,
+                headers: { [ATTEMPT_HEADER]: String(attempt + 1), [NOT_BEFORE_HEADER]: String(notBefore) },
+            },
+        ])
+        this.logger.warn(EventBusLogEvent.DeliveryRetried, { event: eventName, attempt, reason })
+    }
+
+    private async bury(message: InboundMessage, eventName: string, attempt: number, reason: string): Promise<void> {
+        await this.transport.send([
+            {
+                topic: deadLetterTopicOf(this.options.topicPrefix, eventName),
+                key: message.key,
+                value: message.value,
+                headers: {
+                    [ATTEMPT_HEADER]: String(attempt),
+                    [REASON_HEADER]: reason,
+                    [ORIGIN_HEADER]: topicOf(this.options.topicPrefix, eventName),
+                },
+            },
+        ])
+        this.logger.warn(EventBusLogEvent.DeliveryBuried, { event: eventName, attempts: attempt, reason })
+    }
+}

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

@@ -0,0 +1,180 @@
+/** One message to put on a topic. */
+export interface OutboundMessage {
+    /** The topic. */
+    readonly topic: string
+    /** The partition key: messages of one key keep their order. */
+    readonly key: string
+    /** The serialized envelope. */
+    readonly value: string
+    /** Text headers: the attempt, the earliest redelivery instant, the failure reason. */
+    readonly headers: Readonly<Record<string, string>>
+}
+
+/** One message as the transport hands it to a subscriber, with its position on the topic. */
+export interface InboundMessage extends OutboundMessage {
+    /** The partition. */
+    readonly partition: number
+    /** The offset on the partition, as text. */
+    readonly offset: string
+}
+
+/** What a subscriber of the transport asks for. */
+export interface EventSubscription {
+    /** The topics to read. */
+    readonly topics: ReadonlyArray<string>
+    /** Handles one message; a return acknowledges it, a throw makes the transport deliver it again. */
+    onMessage(message: InboundMessage): Promise<void>
+}
+
+/** The broker as the event bus sees it: the one port the Kafka client implements. */
+export interface EventTransport {
+    /** Appends the messages to their topics. */
+    send(messages: ReadonlyArray<OutboundMessage>): Promise<void>
+    /** Starts reading the topics for the consumer group of the service. */
+    subscribe(subscription: EventSubscription): Promise<void>
+    /** How many messages of the topic the consumer group of the service has not acknowledged yet. */
+    lag(topic: string): Promise<number>
+    /** Every message of the topic, oldest first. */
+    read(topic: string): Promise<ReadonlyArray<InboundMessage>>
+    /** Resolves after `ms` milliseconds: the only clock of the retry backoff and the relay loop. */
+    wait(ms: number): Promise<void>
+}
+
+/** A header value of a message as the driver hands it over: text or binary, one or a list per name. */
+export type KafkaMessageHeaders = Readonly<Record<string, Buffer | string | Array<Buffer | string> | undefined>>
+
+/** The settings the module hands the factory when it builds the driver of the app. */
+export interface KafkaDriverConfig {
+    /** The client id the broker sees: the consumer group of the app. */
+    readonly clientId: string
+    /** The broker addresses. */
+    readonly brokers: ReadonlyArray<string>
+    /** How long connecting may take, in milliseconds. */
+    readonly connectionTimeout: number
+    /** How long a broker request may take, in milliseconds. */
+    readonly requestTimeout: number
+}
+
+/** One message of a batch the producer appends. */
+export interface KafkaBatchMessage {
+    /** The partition key. */
+    readonly key?: Buffer | string | null
+    /** The serialized value. */
+    readonly value: Buffer | string | null
+    /** The headers. */
+    readonly headers?: KafkaMessageHeaders
+}
+
+/** The producer as the transport uses it. */
+export interface KafkaProducer {
+    /** Opens the connection to the brokers. */
+    connect(): Promise<void>
+    /** Appends the grouped messages to their topics in one batch. */
+    sendBatch(batch: { topicMessages: Array<{ topic: string; messages: Array<KafkaBatchMessage> }> }): Promise<unknown>
+    /** Closes the connection. */
+    disconnect(): Promise<void>
+}
+
+/** What a consumer of a topic reads from; either one topic or a list of them. */
+export type KafkaConsumerSubscription =
+    | { readonly topics: Array<string>; readonly fromBeginning?: boolean }
+    | { readonly topic: string; readonly fromBeginning?: boolean }
+
+/** The record of a consumed message as the driver hands it over. */
+export interface KafkaConsumedRecord {
+    /** The offset on the partition, as text. */
+    readonly offset: string
+    /** The partition key. */
+    readonly key: Buffer | null
+    /** The serialized value. */
+    readonly value: Buffer | null
+    /** The headers; a message of the old wire format has none. */
+    readonly headers?: KafkaMessageHeaders
+}
+
+/** A message as the driver hands it to the eachMessage callback. */
+export interface KafkaConsumedMessage {
+    /** The topic the message was read from. */
+    readonly topic: string
+    /** The partition. */
+    readonly partition: number
+    /** The record. */
+    readonly message: KafkaConsumedRecord
+}
+
+/** The callbacks a consumer runs per message; the only one the transport sets. */
+export interface KafkaConsumerRun {
+    /** Handles one message. */
+    eachMessage?(payload: KafkaConsumedMessage): Promise<void>
+}
+
+/** The consumer as the transport uses it. */
+export interface KafkaConsumer {
+    /** Opens the connection and joins the group. */
+    connect(): Promise<void>
+    /** Subscribes to the topics. */
+    subscribe(subscription: KafkaConsumerSubscription): Promise<void>
+    /** Starts delivering messages. */
+    run(config: KafkaConsumerRun): Promise<void>
+    /** Leaves the group and closes the connection. */
+    disconnect(): Promise<void>
+}
+
+/** The end offsets of one partition as the broker answers them. */
+export interface KafkaPartitionOffsets {
+    /** The partition. */
+    readonly partition: number
+    /** The offset of the latest record, as text. */
+    readonly offset: string
+    /** The log start offset, as text. */
+    readonly low: string
+    /** The log end offset, as text. */
+    readonly high: string
+}
+
+/** The offsets a consumer group committed on one topic. */
+export interface KafkaGroupOffsets {
+    /** The topic. */
+    readonly topic: string
+    /** The committed offset per partition. */
+    readonly partitions: Array<{
+        readonly partition: number
+        readonly offset: string
+        readonly metadata: string | null
+    }>
+}
+
+/** The admin client as the transport uses it. */
+export interface KafkaAdmin {
+    /** Opens the connection. */
+    connect(): Promise<void>
+    /** Closes the connection. */
+    disconnect(): Promise<void>
+    /** The topics the broker knows. */
+    listTopics(): Promise<Array<string>>
+    /** The end offsets of every partition of the topic. */
+    fetchTopicOffsets(topic: string): Promise<Array<KafkaPartitionOffsets>>
+    /** The offsets the group committed on the topics. */
+    fetchOffsets(options: {
+        readonly groupId: string
+        readonly topics?: Array<string>
+    }): Promise<Array<KafkaGroupOffsets>>
+    /** Deletes the consumer groups. */
+    deleteGroups(groupIds: Array<string>): Promise<Array<unknown>>
+}
+
+/** The driver of the brokers: the minimal shape of the library object the client uses, so the client never imports it. */
+export interface KafkaDriver {
+    /** The producer of the app. */
+    producer(options: { readonly allowAutoTopicCreation?: boolean }): KafkaProducer
+    /** A consumer of a group. */
+    consumer(options: { readonly groupId: string; readonly allowAutoTopicCreation?: boolean }): KafkaConsumer
+    /** The admin client. */
+    admin(): KafkaAdmin
+}
+
+/** Builds the Kafka driver; the module provides it so a spec can double it through the injection token. */
+export interface KafkaFactory {
+    /** The driver over the brokers the config names. */
+    create(config: KafkaDriverConfig): KafkaDriver
+}

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

@@ -0,0 +1,67 @@
+import {
+    ATTEMPTS,
+    ATTEMPT_HEADER,
+    BACKOFF_MS,
+    DEAD_LETTER_ID_SEPARATOR,
+    NOT_BEFORE_HEADER,
+    ORIGIN_HEADER,
+    REASON_HEADER,
+    REQUEUED_HEADER,
+    backoffMs,
+    deadLetterTopicOf,
+    retryTopicOf,
+    serviceOf,
+    topicOf,
+} from "./event.policy"
+
+describe("event policies", () => {
+    it("declares the delivery and wire constants", () => {
+        expect({
+            attempts: ATTEMPTS,
+            backoffMs: BACKOFF_MS,
+            attemptHeader: ATTEMPT_HEADER,
+            notBeforeHeader: NOT_BEFORE_HEADER,
+            reasonHeader: REASON_HEADER,
+            originHeader: ORIGIN_HEADER,
+            requeuedHeader: REQUEUED_HEADER,
+            deadLetterIdSeparator: DEAD_LETTER_ID_SEPARATOR,
+        }).toEqual({
+            attempts: 5,
+            backoffMs: 500,
+            attemptHeader: "attempt",
+            notBeforeHeader: "not-before",
+            reasonHeader: "reason",
+            originHeader: "origin-topic",
+            requeuedHeader: "requeued",
+            deadLetterIdSeparator: "|",
+        })
+    })
+
+    it.each([
+        ["order.created", "order"],
+        ["order", "order"],
+        ["", ""],
+    ])("reads the service of %s", (eventName, service) => {
+        expect(serviceOf(eventName)).toBe(service)
+    })
+
+    it("builds the main topic from the prefix and event service", () => {
+        expect(topicOf("run-1.", "order.created")).toBe("run-1.events.order")
+    })
+
+    it("builds the retry topic from the main topic", () => {
+        expect(retryTopicOf("run-1.", "order.created")).toBe("run-1.events.order.retry")
+    })
+
+    it("builds the dead-letter topic from the main topic", () => {
+        expect(deadLetterTopicOf("run-1.", "order.created")).toBe("run-1.events.order.dlq")
+    })
+
+    it.each([
+        [1, 500],
+        [2, 1000],
+        [4, 4000],
+    ])("doubles the backoff after delivery %i", (attempt, delay) => {
+        expect(backoffMs(attempt)).toBe(delay)
+    })
+})

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

@@ -0,0 +1,38 @@
+/** How many deliveries an event gets before it is a dead letter. */
+export const ATTEMPTS = 5
+
+/** The pause after the first failed delivery; it doubles with every further failure. */
+export const BACKOFF_MS = 500
+
+/** The header that carries the number of the delivery a retry message stands for. */
+export const ATTEMPT_HEADER = "attempt"
+
+/** The header that carries the instant before which a retry message must not be delivered again. */
+export const NOT_BEFORE_HEADER = "not-before"
+
+/** The header that carries why a message was buried. */
+export const REASON_HEADER = "reason"
+
+/** The header of a dead-letter message that names the main topic its event travelled on. */
+export const ORIGIN_HEADER = "origin-topic"
+
+/** The header of a marker message that says which dead letter was requeued. */
+export const REQUEUED_HEADER = "requeued"
+
+/** What joins the topic, partition and offset in the id of a dead letter. */
+export const DEAD_LETTER_ID_SEPARATOR = "|"
+
+/** The service an event belongs to: the part of its name before the first dot. */
+export const serviceOf = (eventName: string): string => eventName.replace(/\..*$/s, "")
+
+/** The topic the events of a service travel on. */
+export const topicOf = (prefix: string, eventName: string): string => `${prefix}events.${serviceOf(eventName)}`
+
+/** The topic a failed delivery waits on until its backoff has passed. */
+export const retryTopicOf = (prefix: string, eventName: string): string => `${topicOf(prefix, eventName)}.retry`
+
+/** The topic an event goes to when it ran out of attempts. */
+export const deadLetterTopicOf = (prefix: string, eventName: string): string => `${topicOf(prefix, eventName)}.dlq`
+
+/** The pause before the delivery that follows the failed delivery number `attempt`: it doubles with every failure. */
+export const backoffMs = (attempt: number): number => BACKOFF_MS * 2 ** (attempt - 1)