@starci/hfs 4.7.31 → 4.7.33

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

@@ -1,8 +1,8 @@
 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 { CORRELATION_RUNNER, LOGGER } from "@modules/platform/logging"
+import type { CorrelationRunner, 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"
@@ -13,8 +13,6 @@ import { readEnvelope } from "./event-envelope.policy"
 import { EventRunnerService } from "./event-runner.service"
 import type { EventSubscription, EventTransport, InboundMessage } from "./event-transport.port"
 
-/** Asymmetric matchers read as `unknown`: jest types them `any`, which may not flow into a property or a typed argument. */
-const anyOf = (type: unknown): unknown => expect.any(type)
 const objectLike = (shape: Record<string, unknown>): unknown => expect.objectContaining(shape)
 
 const AT = "2026-02-03T04:05:06.000Z"
@@ -60,7 +58,12 @@ const message = (overrides: Partial<InboundMessage> = {}): InboundMessage => ({
     partition: 0,
     offset: "4",
     key: "o-1",
-    value: JSON.stringify({ eventId: "o-1", eventName: "probe.ping", payload: { ref: "o-1" } }),
+    value: JSON.stringify({
+        metadata: { correlationId: "request-1" },
+        eventId: "o-1",
+        eventName: "probe.ping",
+        payload: { ref: "o-1" },
+    }),
     headers: {},
     ...overrides,
 })
@@ -68,6 +71,8 @@ const message = (overrides: Partial<InboundMessage> = {}): InboundMessage => ({
 const build = async (register = true) => {
     const transport = mock<EventTransport>()
     const logger = mock<Logger>()
+    const correlation = mock<CorrelationRunner>()
+    correlation.run.mockImplementation((_id, work) => work())
     const handle = jest.fn<Promise<void>, Array<never>>()
     const subscriptions: Array<EventSubscription> = []
     transport.subscribe.mockImplementation((subscription) => {
@@ -81,6 +86,7 @@ const build = async (register = true) => {
             { provide: EVENT_TRANSPORT, useValue: transport },
             { provide: CLOCK, useValue: new FakeClock(AT) },
             { provide: LOGGER, useValue: logger },
+            { provide: CORRELATION_RUNNER, useValue: correlation },
         ],
     }).compile()
     const runner = moduleRef.get(EventRunnerService)
@@ -88,202 +94,299 @@ const build = async (register = true) => {
         const consumer: EventConsumer<PingEvent> = { event: PingEvent, handle }
         runner.add(consumer)
     }
-    return { runner, transport, logger, handle, subscriptions }
+    return { runner, transport, logger, handle, subscriptions, correlation }
 }
 
-describe("EventRunnerService", () => {
-    describe("onApplicationBootstrap", () => {
-        it("subscribes to the main and retry topic of every registered event", async () => {
-            const { runner, subscriptions } = await build()
+describe("EventRunnerService onApplicationBootstrap", () => {
+    it("subscribes to the main and retry topic of every registered event", async () => {
+        const { runner, subscriptions } = await build()
 
-            await runner.onApplicationBootstrap()
+        await runner.onApplicationBootstrap()
 
-            expect(subscriptions.map((subscription) => subscription.topics)).toEqual([
-                ["run-1.events.probe", "run-1.events.probe.retry"],
-            ])
-        })
+        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)
+    it("subscribes to nothing when no consumer registered", async () => {
+        const { runner, transport } = await build(false)
 
-            await runner.onApplicationBootstrap()
+        await runner.onApplicationBootstrap()
 
-            expect(transport.subscribe).not.toHaveBeenCalled()
-        })
+        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()
 
-        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())
 
-            await subscriptions[0]?.onMessage(message())
+        expect(handle).toHaveBeenCalledTimes(1)
+    })
+})
 
-            expect(handle).toHaveBeenCalledTimes(1)
+describe("EventRunnerService correlation scope", () => {
+    it("restores the explicit correlation context around consumer work", async () => {
+        const { runner, handle, correlation } = await build()
+        let active = ""
+        correlation.run.mockImplementation((id, work) => {
+            active = id
+            return work()
+        })
+        handle.mockImplementation(() => {
+            expect(active).toBe("request-1")
+            return Promise.resolve()
         })
+
+        await runner.receive(message())
+
+        expect(handle).toHaveBeenCalledWith(objectLike({ correlationId: "request-1" }))
+        expect(correlation.run).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)
+describe("EventRunnerService legacy broker envelopes", () => {
+    it("delivers a legacy broker envelope with an explicit root at its event id", async () => {
+        const { runner, handle } = await build()
+        const legacy = { eventId: "legacy-1", eventName: "probe.ping", payload: { ref: "order-1" } }
 
-            await runner.receive(message())
+        await runner.receive(message({ value: JSON.stringify(legacy) }))
 
-            expect(handle).toHaveBeenCalledWith({
-                eventId: "o-1",
-                event: new PingEvent("o-1", { ref: "o-1" }),
-                attempt: 1,
-            })
-            expect(transport.send).not.toHaveBeenCalled()
+        expect(handle).toHaveBeenCalledWith({
+            correlationId: "legacy-1",
+            eventId: "legacy-1",
+            event: new PingEvent("legacy-1", { ref: "order-1" }),
+            attempt: 1,
         })
+    })
 
-        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.each([
+        { attempt: "2", topic: "run-1.events.probe.retry" },
+        { attempt: "5", topic: "run-1.events.probe.dlq" },
+    ])("promotes a legacy body before sending to $topic", async ({ attempt, topic }) => {
+        const { runner, handle, transport } = await build()
+        handle.mockRejectedValue(new Error("provider unavailable"))
+        const legacy = {
+            eventId: "legacy-1",
+            eventName: "probe.ping",
+            payload: { ref: "order-1", businessField: "retained" },
+            causeId: "preceding-event",
+        }
+
+        await runner.receive(message({ value: JSON.stringify(legacy), headers: { attempt } }))
+
+        expect(transport.send).toHaveBeenCalledWith([objectLike({
+            topic,
+            value: JSON.stringify({ ...legacy, metadata: { correlationId: "legacy-1" } }),
+        })])
+        expect(handle).toHaveBeenCalledWith(objectLike({ correlationId: "legacy-1" }))
+    })
+})
 
-        it("leaves an event nobody here consumes alone", async () => {
-            const { runner, handle, transport, logger } = await build()
+describe("EventRunnerService receive consumer delivery", () => {
+    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({ value: JSON.stringify({ eventId: "x", eventName: "probe.other", payload: {} }) }),
-            )
+        await runner.receive(message())
 
-            expect(handle).not.toHaveBeenCalled()
-            expect(transport.send).not.toHaveBeenCalled()
-            expect(logger.warn).not.toHaveBeenCalled()
+        expect(handle).toHaveBeenCalledWith({
+            correlationId: "request-1",
+            eventId: "o-1",
+            event: new PingEvent("o-1", { ref: "o-1" }),
+            attempt: 1,
         })
+        expect(transport.send).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]) }))
+    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)
+    })
+})
 
-            expect(handle).not.toHaveBeenCalled()
-            expect(logger.error).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, anyOf(SyntaxError), {
-                topic: "run-1.events.probe",
-            })
-            expect(logger.warn).toHaveBeenCalledTimes(1)
-            expect(logger.warn).toHaveBeenCalledWith(EventBusLogEvent.MessageSkipped, { topic: "run-1.events.probe" })
-        })
+describe("EventRunnerService receive unhandled messages", () => {
+    it("leaves an event nobody here consumes alone", async () => {
+        const { runner, handle, transport, logger } = await build()
+
+        await runner.receive(
+            message({
+                value: JSON.stringify({
+                    metadata: { correlationId: "request-1" },
+                    eventId: "x",
+                    eventName: "probe.other",
+                    payload: {},
+                }),
+            }),
+        )
 
-        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",
-                    },
-                },
-            ])
-        })
+        expect(handle).not.toHaveBeenCalled()
+        expect(transport.send).not.toHaveBeenCalled()
+        expect(logger.warn).not.toHaveBeenCalled()
+    })
 
-        it("buries once and runs no later consumer of the event when an envelope cannot be read", async () => {
-            const { runner, handle, transport } = await build()
-            const later = jest.fn<Promise<void>, Array<never>>()
-            runner.add({ event: PingEvent, handle: later })
-            const value = JSON.stringify({ eventId: "o-2", eventName: "probe.ping", payload: {} })
+    it("logs and skips a value that is not an envelope", async () => {
+        const { runner, handle, logger } = await build()
 
-            await runner.receive(message({ key: "o-2", value }))
+        await runner.receive(message({ value: "not json" }))
+        await runner.receive(message({ value: JSON.stringify([1]) }))
 
-            expect(handle).not.toHaveBeenCalled()
-            expect(later).not.toHaveBeenCalled()
-            expect(transport.send).toHaveBeenCalledTimes(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("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)
+describe("EventRunnerService receive invalid event payloads", () => {
+    it("buries present malformed metadata before calling business code", async () => {
+        const { runner, handle, transport } = await build()
+        const value = JSON.stringify({ eventId: "o-2", eventName: "probe.ping", payload: { ref: "o-2" }, metadata: null })
 
-            await runner.receive(message({ headers: { attempt: "2" } }))
+        await runner.receive(message({ value }))
 
-            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(handle).not.toHaveBeenCalled()
+        expect(transport.send).toHaveBeenCalledWith([
+            expect.objectContaining({
+                topic: "run-1.events.probe.dlq",
+                headers: objectLike({ reason: "missing or malformed correlation metadata" }),
+            }),
+        ])
+    })
+
+    it("buries an envelope the event class cannot read, without retrying it", async () => {
+        const { runner, handle, transport } = await build()
+        const value = JSON.stringify({
+            metadata: { correlationId: "request-1" },
+            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",
                 },
-            ])
-            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 once and runs no later consumer of the event when an envelope cannot be read", async () => {
+        const { runner, handle, transport } = await build()
+        const later = jest.fn<Promise<void>, Array<never>>()
+        runner.add({ event: PingEvent, handle: later })
+        const value = JSON.stringify({
+            metadata: { correlationId: "request-1" },
+            eventId: "o-2",
+            eventName: "probe.ping",
+            payload: {},
         })
 
-        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({ key: "o-2", value }))
+
+        expect(handle).not.toHaveBeenCalled()
+        expect(later).not.toHaveBeenCalled()
+        expect(transport.send).toHaveBeenCalledTimes(1)
+    })
+})
 
-            await runner.receive(message({ headers: { attempt: "5" } }))
+describe("EventRunnerService receive failed deliveries", () => {
+    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",
+        })
+    })
 
-            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("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)
+describe("EventRunnerService receive retry timing", () => {
+    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) },
-                }),
-            )
+        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(objectLike({ attempt: 2 }))
-        })
+        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)
+    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) } }))
+        await runner.receive(message({ headers: { attempt: "2", "not-before": String(NOW - 5) } }))
 
-            expect(transport.wait).not.toHaveBeenCalled()
-            expect(handle).toHaveBeenCalledTimes(1)
-        })
+        expect(transport.wait).not.toHaveBeenCalled()
+        expect(handle).toHaveBeenCalledTimes(1)
     })
 })

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

@@ -2,8 +2,8 @@ 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 { InjectCorrelationRunner, InjectLogger } from "@modules/platform/logging"
+import type { CorrelationRunner, Logger } from "@modules/platform/logging"
 import { eachInOrder } from "@modules/platform/primitives"
 import type { BaseEvent } from "./event-bus.contracts"
 import { InjectEventBusOptions, InjectEventTransport } from "./event-bus.decorators"
@@ -39,6 +39,7 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
         @InjectEventTransport() private readonly transport: EventTransport,
         @InjectClock() private readonly clock: Clock,
         @InjectLogger() private readonly logger: Logger,
+        @InjectCorrelationRunner() private readonly correlation: CorrelationRunner,
     ) {}
 
     /** Registers a consumer of its event (several features may consume one event); the read loop starts when the app has registered every consumer. */
@@ -62,7 +63,7 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
      * 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 { eventName, envelope, correlationId, cause: unreadable } = readEnvelopeText(message.value)
         const consumers = this.consumers.get(eventName) ?? []
         if (consumers.length === 0) {
             if (unreadable !== null)
@@ -70,6 +71,27 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
             else if (eventName === "") this.logger.warn(EventBusLogEvent.MessageSkipped, { topic: message.topic })
             return
         }
+        if (correlationId === null) {
+            await this.bury(
+                message,
+                eventName,
+                Number(message.headers[ATTEMPT_HEADER] ?? 1),
+                "missing or malformed correlation metadata",
+            )
+            return
+        }
+        await this.correlation.run(correlationId, () =>
+            this.deliver({ ...message, value: JSON.stringify(envelope) }, eventName, envelope, correlationId, consumers),
+        )
+    }
+
+    private async deliver(
+        message: InboundMessage,
+        eventName: string,
+        envelope: unknown,
+        correlationId: string,
+        consumers: ReadonlyArray<EventConsumer<BaseEvent>>,
+    ): Promise<void> {
         const attempt = Number(message.headers[ATTEMPT_HEADER] ?? 1)
         const notBefore = Number(message.headers[NOT_BEFORE_HEADER] ?? 0)
         const pause = notBefore - this.clock.now().getTime()
@@ -85,7 +107,7 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
                 return
             }
             try {
-                await consumer.handle({ eventId: event.eventId, event, attempt })
+                await consumer.handle({ eventId: event.eventId, event, attempt, correlationId })
             } catch (cause) {
                 this.logger.error(EventBusLogEvent.DeliveryFailed, cause, { event: eventName, attempt })
                 failures.push(cause)
@@ -109,7 +131,11 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
                 topic: retryTopicOf(this.options.topicPrefix, eventName),
                 key: message.key,
                 value: message.value,
-                headers: { [ATTEMPT_HEADER]: String(attempt + 1), [NOT_BEFORE_HEADER]: String(notBefore) },
+                headers: {
+                    ...message.headers,
+                    [ATTEMPT_HEADER]: String(attempt + 1),
+                    [NOT_BEFORE_HEADER]: String(notBefore),
+                },
             },
         ])
         this.logger.warn(EventBusLogEvent.DeliveryRetried, { event: eventName, attempt, reason })
@@ -122,6 +148,7 @@ export class EventRunnerService implements EventConsumerRegistry, OnApplicationB
                 key: message.key,
                 value: message.value,
                 headers: {
+                    ...message.headers,
                     [ATTEMPT_HEADER]: String(attempt),
                     [REASON_HEADER]: reason,
                     [ORIGIN_HEADER]: topicOf(this.options.topicPrefix, eventName),

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

@@ -3,10 +3,12 @@ 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_CORRELATION_INVALID": "M? t??ng quan s? ki?n kh?ng h?p l?.",
         "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_CORRELATION_INVALID": "The event correlation id is invalid.",
         "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/entities/event-outbox.entity.ts.tpl

@@ -11,6 +11,10 @@ export class EventOutboxEntity {
     @Column({ name: "event_id", type: "varchar", length: 200 })
     eventId!: string
 
+    /** The originating request id, retained through every relay and delivery. */
+    @Column({ name: "correlation_id", type: "varchar", length: 128, default: () => "pg_catalog.gen_random_uuid()::text" })
+    correlationId!: string
+
     /** The event name. */
     @Column({ name: "event_name", type: "varchar", length: 200 })
     eventName!: string
@@ -23,7 +27,7 @@ export class EventOutboxEntity {
     @Column({ name: "message_key", type: "varchar", length: 200 })
     messageKey!: string
 
-    /** The envelope `{ eventId, eventName, payload }`. */
+    /** The envelope `{ metadata, eventId, eventName, payload }`. */
     @Column({ name: "envelope", type: "jsonb" })
     envelope!: object
 

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

@@ -1,5 +1,7 @@
 /** One row the relay reads from the outbox. */
 export interface OutboxRow {
+    /** The originating request id persisted independently of the envelope. */
+    readonly correlation_id: string
     /** The position of the row (a bigint arrives as text). */
     readonly id: string
     /** The topic the event travels on. */