@starci/hfs 4.10.1 → 4.11.8

package/templates/be/inbox/platform/event-bus/event-bus.contracts.ts.tpl

@@ -1,23 +1,38 @@
+/**
+ * The suffix of a consumer's dead-letter queue: a delivery past its consumer's maxDeliveries moves from `<topic>__<consumer>` to
+ * `<topic>__<consumer>__dead`, which an operator reads and replays (BE-EVENT-BUS-4).
+ */
+export const DEAD_QUEUE_SUFFIX = "__dead"
+
+/** The deliveries a consumer gets before its message moves to the dead-letter queue, when its subscription names none. */
+export const DEFAULT_MAX_DELIVERIES = 5
+
+/** What every event payload carries: the business key a consumer's inbox claims, stable across redelivery and replay. */
+export interface EventPayload {
+    /** The business identity of the fact (an order id, a receipt id): the consumer claims (consumer, dedupeKey) once. */
+    readonly dedupeKey: string
+}
+
 /** The base of each typed event in modules/events: its stable identity, name and payload. */
 export abstract class BaseEvent {
-    /** A receiver uses this stable identity to deduplicate redelivery. */
+    /** The stable identity of this event, carried for logs and tracing. */
     abstract readonly eventId: string
-    /** The event name listed by the service's vendored event contract. */
+    /** The event name listed by the service's vendored event contract; it is the pgmq topic the event is sent to. */
     abstract readonly eventName: string
-    /** The fact that a reactor or job processes after commit. */
-    abstract readonly payload: object
+    /** The fact that a reactor processes after commit, with its business dedupe key. */
+    abstract readonly payload: EventPayload
 }
 
 /** Parsing either returns the event or refuses a mismatched envelope. */
 export type ParsedEvent<Event extends BaseEvent> = Event | null
 
-/** The class side of a typed event, shared by publishers and later consumers. */
+/** The class side of a typed event, shared by publishers and consumers. */
 export interface EventClass<Event extends BaseEvent> {
     /** The contract's event name. */
     readonly eventName: string
     /** The contract's payload version. */
     readonly version: number
-    /** Reads the event from its durable envelope. */
+    /** Reads the event from its envelope. */
     parse(envelope: unknown): ParsedEvent<Event>
 }
 
@@ -25,21 +40,25 @@ export interface EventClass<Event extends BaseEvent> {
 export interface EventDelivery<Event extends BaseEvent> {
     /** The request id carried explicitly from intake to delivery. */
     readonly correlationId: string
-    /** The consumer's idempotency key. */
+    /** The stable identity of the event. */
     readonly eventId: string
+    /** The consumer's queue, `<topic>__<consumer>`: the first half of the inbox claim. */
+    readonly consumer: string
+    /** The payload's business key: the second half of the inbox claim. */
+    readonly dedupeKey: string
     /** The typed event. */
     readonly event: Event
-    /** The number of attempts, including this one. */
+    /** The number of deliveries, including this one. */
     readonly attempt: number
 }
 
 /** Explicit request context carried independently of the business payload. */
 export interface EventMetadata {
-    /** The originating request or promoted legacy event identity. */
+    /** The originating request or promoted event identity. */
     readonly correlationId: string
 }
 
-/** The typed event's durable envelope, read only after the intake transaction commits. */
+/** The typed event's envelope, sent once to its topic in the publisher's transaction and routed to every bound consumer queue. */
 export interface EventEnvelope {
     /** The originating request context, independent of the business payload. */
     readonly metadata: EventMetadata
@@ -48,5 +67,33 @@ export interface EventEnvelope {
     /** The contract's event name. */
     readonly eventName: string
     /** The data of the fact. */
-    readonly payload: object
+    readonly payload: EventPayload
+}
+
+/** One message of a consumer's queue, as event_bus_read returns it. */
+export interface EventMessage {
+    /** The pgmq message id within its queue. */
+    readonly msgId: string
+    /** How many times the message has been read, including this read. */
+    readonly readCt: number
+    /** The envelope as the publisher sent it; untrusted until parsed. */
+    readonly message: unknown
+}
+
+/** What a reactor's subscription may tune; every field is a literal of the subscription. */
+export interface EventSubscriptionOptions {
+    /** The deliveries before the message moves to the dead-letter queue. Default DEFAULT_MAX_DELIVERIES. */
+    readonly maxDeliveries?: number
+}
+
+/** A delivery a consumer gave up on, as its dead-letter queue holds it. */
+export interface DeadLetter {
+    /** The message id in the dead-letter queue: what requeue takes. */
+    readonly id: string
+    /** Why it was moved: its deliveries ran out, or its envelope was malformed. */
+    readonly reason: string
+    /** The deliveries it had. */
+    readonly readCount: number
+    /** The envelope as it was read. */
+    readonly message: unknown
 }

package/templates/be/inbox/platform/event-bus/event-bus.decorators.ts.tpl

@@ -1,9 +1,21 @@
 import { injector } from "@modules/platform/composition"
 import type { TypedParameterDecorator } from "@modules/platform/composition"
-import type { EventBus } from "./event-bus.port"
+import { MODULE_OPTIONS_TOKEN } from "./event-bus.module-definition"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventBus, EventConsumerRegistry } from "./event-bus.port"
 
 /** Token of the transactional EventBus publisher. */
 export const EVENT_BUS: unique symbol = Symbol("platform.event-bus")
 
+/** Token of the registry reactors subscribe their consumers to. */
+export const EVENT_CONSUMER_REGISTRY: unique symbol = Symbol("platform.event-bus.consumers")
+
 /** Injects the EventBus port. Parameter type: EventBus. */
 export const InjectEventBus = (): TypedParameterDecorator<EventBus> => injector<EventBus>(EVENT_BUS)
+
+/** Injects the consumer registry. Parameter type: EventConsumerRegistry. */
+export const InjectEventConsumerRegistry = (): TypedParameterDecorator<EventConsumerRegistry> =>
+    injector<EventConsumerRegistry>(EVENT_CONSUMER_REGISTRY)
+
+/** Injects the module's options. Parameter type: EventBusOptions. */
+export const InjectEventBusOptions = (): TypedParameterDecorator<EventBusOptions> => injector<EventBusOptions>(MODULE_OPTIONS_TOKEN)

package/templates/be/inbox/platform/event-bus/event-bus.log-events.ts.tpl

@@ -0,0 +1,9 @@
+/** Log events of the event bus. */
+export enum EventBusLogEvent {
+    /** A consumer threw; the message reappears after its visibility timeout. */
+    ConsumerFailed = "event-bus.consumer.failed",
+    /** A delivery ran out of deliveries or was malformed and moved to its consumer's dead-letter queue. */
+    DeliveryDead = "event-bus.delivery.dead",
+    /** A read of a consumer's queue failed; the loop reads again after its idle pause. */
+    ReadFailed = "event-bus.read.failed",
+}

package/templates/be/inbox/platform/event-bus/event-bus.module-definition.ts.tpl

@@ -1,6 +1,6 @@
 import { ConfigurableModuleBuilder } from "@nestjs/common"
 import type { EventBusOptions } from "./event-bus.options"
 
-export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } = new ConfigurableModuleBuilder<EventBusOptions>()
     .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
     .build()

package/templates/be/inbox/platform/event-bus/event-bus.module.ts.tpl

@@ -1,19 +1,25 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
-import { EVENT_BUS } from "./event-bus.decorators"
+import { EVENT_BUS, EVENT_CONSUMER_REGISTRY } from "./event-bus.decorators"
 import { ConfigurableModuleClass, OPTIONS_TYPE } from "./event-bus.module-definition"
 import { EventBusService } from "./event-bus.service"
+import { EventConsumerService } from "./event-consumer.service"
 
 @Module({})
-/** Provides the transactional lite EventBus publisher, shared by domain intake services. */
+/** Provides the lite event bus on pgmq: the transactional publisher and the read loops of the consumer groups. */
 export class EventBusModule extends ConfigurableModuleClass {
-    /** Registers the publishing capability once per app. */
+    /** Registers the capability once per app. */
     static register(options: typeof OPTIONS_TYPE): DynamicModule {
         const base = super.register(options)
         return {
             ...base,
-            providers: [...(base.providers ?? []), { provide: EVENT_BUS, useClass: EventBusService }],
-            exports: [EVENT_BUS],
+            providers: [
+                ...(base.providers ?? []),
+                { provide: EVENT_BUS, useClass: EventBusService },
+                EventConsumerService,
+                { provide: EVENT_CONSUMER_REGISTRY, useExisting: EventConsumerService },
+            ],
+            exports: [EVENT_BUS, EVENT_CONSUMER_REGISTRY],
         }
     }
 }

package/templates/be/inbox/platform/event-bus/event-bus.options.ts.tpl

@@ -1,2 +1,9 @@
-/** The lite publisher uses the caller's transaction and has no runtime options. */
-export interface EventBusOptions {}
+/** How the consumers of the app read their queues; every field has a default, so a bare registration works. */
+export interface EventBusOptions {
+    /** Seconds a read message stays hidden: a consumer that fails or dies lets it reappear after this. Default 30. */
+    readonly visibilitySeconds?: number
+    /** The most messages one read takes from a queue. Default 10. */
+    readonly batch?: number
+    /** The pause between two reads of an empty queue, in milliseconds. Default 500. */
+    readonly idleMs?: number
+}

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

@@ -1,16 +1,29 @@
 import type { EntityManager } from "typeorm"
-import type { BaseEvent, EventClass, EventDelivery } from "./event-bus.contracts"
+import type { BaseEvent, DeadLetter, EventClass, EventDelivery, EventSubscriptionOptions } from "./event-bus.contracts"
 
-/** The publishing side of the lite event bus; the reactor or job owns delivery of committed outbox rows. */
+/** The publishing and operator side of the lite event bus on pgmq. */
 export interface EventBus {
-    /** Writes the typed event in the caller's transaction; a rollback writes no durable event. */
+    /** Sends the typed event once to its topic in the caller's transaction; pgmq routes it to every bound consumer queue, and a rollback sends nothing. */
     publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void>
+    /** The oldest deliveries the consumer of `queue` gave up on, at most `limit`, for an operator's cli command. */
+    deadLetters(queue: string, limit: number): Promise<ReadonlyArray<DeadLetter>>
+    /** Sends one dead letter of `queue` back to that queue; false when it holds no dead letter with the id. */
+    requeue(queue: string, id: string): Promise<boolean>
 }
 
-/** A later message transport receives one typed event and forwards its delivery id. */
+/** A reactor's thin door: it reads one typed event and dispatches one command with the delivery's ids. */
 export interface EventConsumer<Event extends BaseEvent> {
     /** The event class the consumer reads. */
     readonly event: EventClass<Event>
-    /** Applies one delivery after commit; a throw leaves the delivery available for retry. */
+    /** Applies one delivery; a throw leaves the message to reappear after its visibility timeout. */
     handle(delivery: EventDelivery<Event>): Promise<void>
 }
+
+/** Where a reactor subscribes its consumer; reading starts when the app has bootstrapped. */
+export interface EventConsumerRegistry {
+    /**
+     * Reads `queue` for `consumer`. The queue is a literal `<TOPIC>_<CONSUMER>_TOPIC_QUEUE` constant of platform/event-bus whose
+     * pgmq queue, dead-letter queue and topic binding a migration declares (R258); the subscription is static (R336).
+     */
+    subscribe<Event extends BaseEvent>(queue: string, consumer: EventConsumer<Event>, options?: EventSubscriptionOptions): void
+}

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

@@ -1,27 +1,33 @@
 import { Test } from "@nestjs/testing"
 import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
 import { EventBusErrorCode } from "./errors/event-bus.error"
 import { BaseEvent } from "./event-bus.contracts"
 import { EventBusService } from "./event-bus.service"
 
-// The statement callDbFunction of platform/database sends for event_bus_write.
-const INSERT_OUTBOX_EVENT = "SELECT * FROM event_bus_write($1, $2, $3, $4)"
+// The statements callDbFunction of platform/database sends for the bus functions of the migration.
+const SEND = 'SELECT * FROM "public"."event_bus_send"($1, $2)'
+const DEAD_LETTERS = 'SELECT * FROM "public"."event_bus_dead_letters"($1, $2)'
+const REQUEUE = 'SELECT * FROM "public"."event_bus_requeue"($1, $2)'
+const QUEUE = "spec_delivery_recorded__mailer"
 
 class ReceiptRecordedEvent extends BaseEvent {
-    readonly eventId = "receipt-1"
+    readonly eventId = "event-1"
     readonly eventName = "spec.delivery-recorded"
-    readonly payload = { receiptId: "receipt-1" }
+    readonly payload = { dedupeKey: "receipt-1", receiptId: "receipt-1" }
 }
 
 describe("EventBusService", () => {
-    const build = async () => {
-        const module = await Test.createTestingModule({ providers: [EventBusService] }).compile()
+    const build = async (primary = mockEntityManager({})) => {
+        const module = await Test.createTestingModule({
+            providers: [EventBusService, { provide: PRIMARY_ENTITY_MANAGER, useValue: primary }],
+        }).compile()
         return module.get(EventBusService)
     }
 
     it.each(["", "unsafe\nid", "x".repeat(129)])("refuses invalid correlation before SQL: %s", async (correlationId) => {
         const subject = await build()
-        const manager = mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] })
+        const manager = mockEntityManager({ query: [SEND, [{ event_bus_send: 1 }]] })
 
         await expect(subject.publish(new ReceiptRecordedEvent(), manager, correlationId)).rejects.toMatchObject({
             code: EventBusErrorCode.CorrelationInvalid,
@@ -29,31 +35,46 @@ describe("EventBusService", () => {
         expect(manager.query).not.toHaveBeenCalled()
     })
 
-    it("writes the typed envelope through the receipt transaction", async () => {
+    it("sends the typed envelope to the event's topic through the publisher's transaction", async () => {
         const subject = await build()
-        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] }))
+        const transaction = fakeTransaction(mockEntityManager({ query: [SEND, [{ event_bus_send: 1 }]] }))
         const event = new ReceiptRecordedEvent()
 
         await transaction.em.transaction((manager) => subject.publish(event, manager, "request-1"))
 
-        expect(transaction.em.query).toHaveBeenCalledWith(INSERT_OUTBOX_EVENT, [
-            "receipt-1",
+        expect(transaction.em.query).toHaveBeenCalledWith(SEND, [
             "spec.delivery-recorded",
             JSON.stringify({ metadata: { correlationId: "request-1" }, eventId: event.eventId, eventName: event.eventName, payload: event.payload }),
-            "request-1",
         ])
         expect(transaction.commits).toBe(1)
     })
 
-    it("propagates an outbox failure so the receipt transaction rolls back", async () => {
+    it("propagates a send failure so the publisher's transaction rolls back and nothing is sent", async () => {
         const subject = await build()
-        const manager = mockEntityManager({ query: [INSERT_OUTBOX_EVENT, []] })
-        jest.spyOn(manager, "query").mockRejectedValue(new Error("outbox unavailable"))
+        const manager = mockEntityManager({ query: [SEND, []] })
+        jest.spyOn(manager, "query").mockRejectedValue(new Error("pgmq unavailable"))
         const transaction = fakeTransaction(manager)
 
-        await expect(transaction.em.transaction((tx) => subject.publish(new ReceiptRecordedEvent(), tx, "request-1"))).rejects.toThrow("outbox unavailable")
+        await expect(transaction.em.transaction((tx) => subject.publish(new ReceiptRecordedEvent(), tx, "request-1"))).rejects.toThrow("pgmq unavailable")
 
         expect(transaction.commits).toBe(0)
         expect(transaction.rollbacks).toBe(1)
     })
+
+    it("lists a consumer's dead letters and requeues one by its dead-letter id", async () => {
+        const primary = mockEntityManager({
+            query: [
+                [DEAD_LETTERS, [{ msg_id: "7", message: { reason: "max-deliveries", readCount: 6, message: { eventId: "event-1" } } }]],
+                [REQUEUE, [{ event_bus_requeue: true }]],
+            ],
+        })
+        const subject = await build(primary)
+
+        await expect(subject.deadLetters(QUEUE, 10)).resolves.toEqual([
+            { id: "7", reason: "max-deliveries", readCount: 6, message: { eventId: "event-1" } },
+        ])
+        await expect(subject.requeue(QUEUE, "7")).resolves.toBe(true)
+        expect(primary.query).toHaveBeenCalledWith(DEAD_LETTERS, [QUEUE, 10])
+        expect(primary.query).toHaveBeenCalledWith(REQUEUE, [QUEUE, "7"])
+    })
 })

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

@@ -1,15 +1,28 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { isCorrelationId } from "@modules/platform/logging"
+import { callDbFunction, InjectPrimaryEntityManager } from "@modules/platform/database"
 import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
-import type { BaseEvent, EventEnvelope } from "./event-bus.contracts"
+import type { BaseEvent, DeadLetter, EventEnvelope } from "./event-bus.contracts"
 import type { EventBus } from "./event-bus.port"
-import { callDbFunction } from "@modules/platform/database"
+
+/** One row of event_bus_dead_letters: pgmq returns the bigint id as text. */
+interface DeadLetterRow {
+    readonly msg_id: string
+    readonly message: { readonly reason?: unknown; readonly readCount?: unknown; readonly message?: unknown }
+}
+
+/** The one row event_bus_requeue answers. */
+interface RequeueRow {
+    readonly event_bus_requeue: boolean | null
+}
 
 @Injectable()
-/** Writes a receipt event into the same transaction as its inbox receipt, without running any consumer. */
+/** Sends a typed event once to its pgmq topic inside the publisher's transaction; no outbox and no relay stand between them. */
 export class EventBusService implements EventBus {
-    /** The outbox commits or rolls back with the receipt; only a later reactor or job processes it. */
+    constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
+
+    /** The send commits or rolls back with the change; pgmq copies it into every consumer queue bound to the event's name. */
     async publish(event: BaseEvent, tx: EntityManager, correlationId: string): Promise<void> {
         if (!isCorrelationId(correlationId)) throw new EventBusError({ code: EventBusErrorCode.CorrelationInvalid })
         const envelope: EventEnvelope = {
@@ -18,6 +31,21 @@ export class EventBusService implements EventBus {
             eventName: event.eventName,
             payload: event.payload,
         }
-        await callDbFunction(tx, "event_bus_write", [event.eventId, event.eventName, JSON.stringify(envelope), correlationId])
+        await callDbFunction(tx, "public.event_bus_send", [event.eventName, JSON.stringify(envelope)])
+    }
+
+    async deadLetters(queue: string, limit: number): Promise<ReadonlyArray<DeadLetter>> {
+        const rows = await callDbFunction<DeadLetterRow>(this.entityManager, "public.event_bus_dead_letters", [queue, limit])
+        return rows.map((row) => ({
+            id: row.msg_id,
+            reason: String(row.message.reason),
+            readCount: Number(row.message.readCount),
+            message: row.message.message,
+        }))
+    }
+
+    async requeue(queue: string, id: string): Promise<boolean> {
+        const [row] = await callDbFunction<RequeueRow>(this.entityManager, "public.event_bus_requeue", [queue, id])
+        return row?.event_bus_requeue === true
     }
 }

package/templates/be/inbox/platform/event-bus/event-consumer.service.spec.ts.tpl

@@ -0,0 +1,143 @@
+import { Test } from "@nestjs/testing"
+import { mockEntityManager } from "@starci/jest-preset"
+import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
+import { LOGGER } from "@modules/platform/logging"
+import { BaseEvent } from "./event-bus.contracts"
+import type { EventDelivery, ParsedEvent } from "./event-bus.contracts"
+import { MODULE_OPTIONS_TOKEN } from "./event-bus.module-definition"
+import type { EventConsumer } from "./event-bus.port"
+import { EventConsumerService } from "./event-consumer.service"
+
+// The statements callDbFunction of platform/database sends for the bus functions of the migration.
+const READ = 'SELECT * FROM "public"."event_bus_read"($1, $2, $3)'
+const ARCHIVE = 'SELECT * FROM "public"."event_bus_archive"($1, $2)'
+const BURY = 'SELECT * FROM "public"."event_bus_bury"($1, $2, $3, $4, $5)'
+const QUEUE = "spec_delivery_recorded__mailer"
+
+class ReceiptRecordedEvent extends BaseEvent {
+    static readonly eventName = "spec.delivery-recorded"
+    static readonly version = 1
+    readonly eventName = ReceiptRecordedEvent.eventName
+
+    constructor(
+        readonly eventId: string,
+        readonly payload: { readonly dedupeKey: string; readonly receiptId: string },
+    ) {
+        super()
+    }
+
+    static parse(envelope: unknown): ParsedEvent<ReceiptRecordedEvent> {
+        if (typeof envelope !== "object" || envelope === null || !("eventId" in envelope) || typeof envelope.eventId !== "string") return null
+        if (!("payload" in envelope) || typeof envelope.payload !== "object" || envelope.payload === null || !("dedupeKey" in envelope.payload)) return null
+        const dedupeKey = envelope.payload.dedupeKey
+        return typeof dedupeKey === "string" ? new ReceiptRecordedEvent(envelope.eventId, { dedupeKey, receiptId: dedupeKey }) : null
+    }
+}
+
+const envelope = {
+    metadata: { correlationId: "request-1" },
+    eventId: "event-1",
+    eventName: "spec.delivery-recorded",
+    payload: { dedupeKey: "receipt-1", receiptId: "receipt-1" },
+}
+
+class RecordingConsumer implements EventConsumer<ReceiptRecordedEvent> {
+    readonly event = ReceiptRecordedEvent
+    readonly deliveries: Array<EventDelivery<ReceiptRecordedEvent>> = []
+    failing = false
+
+    handle(delivery: EventDelivery<ReceiptRecordedEvent>): Promise<void> {
+        if (this.failing) return Promise.reject(new Error("consumer down"))
+        this.deliveries.push(delivery)
+        return Promise.resolve()
+    }
+}
+
+describe("EventConsumerService", () => {
+    const logger = { info: jest.fn(), warn: jest.fn(), error: jest.fn() }
+
+    const build = async (primary: ReturnType<typeof mockEntityManager>) => {
+        const module = await Test.createTestingModule({
+            providers: [
+                EventConsumerService,
+                { provide: PRIMARY_ENTITY_MANAGER, useValue: primary },
+                { provide: MODULE_OPTIONS_TOKEN, useValue: {} },
+                { provide: LOGGER, useValue: logger },
+            ],
+        }).compile()
+        return module.get(EventConsumerService)
+    }
+
+    it("delivers a committed event once to the consumer with its inbox claim keys and archives it", async () => {
+        const primary = mockEntityManager({
+            query: [
+                [READ, [{ msg_id: "1", read_ct: 1, message: envelope }]],
+                [ARCHIVE, [{ event_bus_archive: true }]],
+            ],
+        })
+        const subject = await build(primary)
+        const consumer = new RecordingConsumer()
+
+        await expect(subject.drain({ queue: QUEUE, consumer, maxDeliveries: 5 })).resolves.toBe(1)
+
+        expect(consumer.deliveries).toEqual([
+            { correlationId: "request-1", eventId: "event-1", consumer: QUEUE, dedupeKey: "receipt-1", event: expect.any(ReceiptRecordedEvent), attempt: 1 },
+        ])
+        expect(primary.query).toHaveBeenCalledWith(READ, [QUEUE, 30, 10])
+        expect(primary.query).toHaveBeenCalledWith(ARCHIVE, [QUEUE, "1"])
+    })
+
+    it("leaves a failed delivery to reappear after its visibility timeout", async () => {
+        const primary = mockEntityManager({ query: [READ, [{ msg_id: "1", read_ct: 2, message: envelope }]] })
+        const subject = await build(primary)
+        const consumer = new RecordingConsumer()
+        consumer.failing = true
+
+        await subject.drain({ queue: QUEUE, consumer, maxDeliveries: 5 })
+
+        expect(primary.query).toHaveBeenCalledTimes(1)
+        expect(logger.error).toHaveBeenCalled()
+    })
+
+    it.each([
+        ["max-deliveries", { msg_id: "1", read_ct: 4, message: envelope }],
+        ["malformed", { msg_id: "1", read_ct: 1, message: { eventId: 42 } }],
+        ["malformed", { msg_id: "1", read_ct: 1, message: { ...envelope, payload: { dedupeKey: " ", receiptId: "receipt-1" } } }],
+        ["malformed", { msg_id: "1", read_ct: 1, message: { ...envelope, metadata: { correlationId: "unsafe\nid" } } }],
+    ])("moves a delivery to the consumer's dead-letter queue: %s", async (reason, row) => {
+        const primary = mockEntityManager({ query: [[READ, [row]], [BURY, [{ event_bus_bury: true }]]] })
+        const subject = await build(primary)
+        const consumer = new RecordingConsumer()
+
+        await subject.drain({ queue: QUEUE, consumer, maxDeliveries: 3 })
+
+        expect(consumer.deliveries).toEqual([])
+        expect(primary.query).toHaveBeenCalledWith(BURY, [QUEUE, "1", row.read_ct, JSON.stringify(row.message), reason])
+    })
+
+    it("takes the default delivery budget of a subscription that names none", async () => {
+        const primary = mockEntityManager({ query: [[READ, [{ msg_id: "1", read_ct: 6, message: envelope }]], [BURY, [{ event_bus_bury: true }]]] })
+        const subject = await build(primary)
+        const consumer = new RecordingConsumer()
+        subject.subscribe(QUEUE, consumer)
+
+        await subject.drain({ queue: QUEUE, consumer, maxDeliveries: 5 })
+
+        expect(primary.query).toHaveBeenCalledWith(BURY, [QUEUE, "1", 6, JSON.stringify(envelope), "max-deliveries"])
+    })
+
+    it("delivers a redelivery again, leaving its dedupe to the consumer's inbox claim", async () => {
+        const primary = mockEntityManager({
+            query: [
+                [READ, [{ msg_id: "1", read_ct: 2, message: envelope }]],
+                [ARCHIVE, [{ event_bus_archive: true }]],
+            ],
+        })
+        const subject = await build(primary)
+        const consumer = new RecordingConsumer()
+
+        await subject.drain({ queue: QUEUE, consumer, maxDeliveries: 5 })
+
+        expect(consumer.deliveries.map((delivery) => [delivery.consumer, delivery.dedupeKey, delivery.attempt])).toEqual([[QUEUE, "receipt-1", 2]])
+    })
+})

package/templates/be/inbox/platform/event-bus/event-consumer.service.ts.tpl

@@ -0,0 +1,119 @@
+import { Injectable } from "@nestjs/common"
+import type { OnApplicationBootstrap, OnApplicationShutdown } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectLogger, isCorrelationId } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { callDbFunction, InjectPrimaryEntityManager } from "@modules/platform/database"
+import { InjectEventBusOptions } from "./event-bus.decorators"
+import { DEFAULT_MAX_DELIVERIES } from "./event-bus.contracts"
+import type { BaseEvent, EventMessage, EventSubscriptionOptions } from "./event-bus.contracts"
+import { EventBusLogEvent } from "./event-bus.log-events"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventConsumer, EventConsumerRegistry } from "./event-bus.port"
+
+/** One row of event_bus_read: pgmq returns the bigint id as text. */
+interface MessageRow {
+    readonly msg_id: string
+    readonly read_ct: number
+    readonly message: unknown
+}
+
+/** One consumer: its queue `<topic>__<consumer>`, the door its deliveries go through and its delivery budget. */
+export interface EventSubscription {
+    /** The consumer's pgmq queue. */
+    readonly queue: string
+    /** The thin door the consumer's deliveries go through. */
+    readonly consumer: EventConsumer<BaseEvent>
+    /** The deliveries before the message moves to `<queue>__dead`. */
+    readonly maxDeliveries: number
+}
+
+/** The correlation id of an envelope: its metadata when present and valid, else a safe event id; null refuses the message. */
+const correlationOf = (message: unknown, eventId: string): string | null => {
+    if (typeof message !== "object" || message === null || !("metadata" in message)) return isCorrelationId(eventId) ? eventId : null
+    const metadata = message.metadata
+    if (typeof metadata !== "object" || metadata === null || !("correlationId" in metadata)) return null
+    return isCorrelationId(metadata.correlationId) ? metadata.correlationId : null
+}
+
+/** True for a usable business dedupe key. */
+const isDedupeKey = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0 && value.length <= 256
+
+@Injectable()
+/**
+ * The consuming side of the lite event bus: each consumer reads its own pgmq queue with a visibility timeout, archives a message it
+ * handled, leaves a failed one to reappear, and moves one past its maxDeliveries, or malformed, to `<queue>__dead`. Delivery is at
+ * least once and unordered, so the command a consumer dispatches claims (consumer, dedupeKey) in the inbox first and reads current
+ * state rather than trusting the order of events (BE-EVENT-BUS-4).
+ */
+export class EventConsumerService implements EventConsumerRegistry, OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly subscriptions: Array<EventSubscription> = []
+    private running = false
+
+    constructor(
+        @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+        @InjectEventBusOptions() private readonly options: EventBusOptions,
+        @InjectLogger() private readonly logger: Logger,
+    ) {}
+
+    subscribe<Event extends BaseEvent>(queue: string, consumer: EventConsumer<Event>, options: EventSubscriptionOptions = {}): void {
+        this.subscriptions.push({ queue, consumer, maxDeliveries: options.maxDeliveries ?? DEFAULT_MAX_DELIVERIES })
+    }
+
+    onApplicationBootstrap(): void {
+        this.running = true
+        for (const subscription of this.subscriptions) void this.loop(subscription)
+    }
+
+    onApplicationShutdown(): void {
+        this.running = false
+    }
+
+    /** Reads one batch of the consumer's queue and settles each message in order; answers how many it read. */
+    async drain(subscription: EventSubscription): Promise<number> {
+        const rows = await callDbFunction<MessageRow>(this.entityManager, "public.event_bus_read", [
+            subscription.queue,
+            this.options.visibilitySeconds ?? 30,
+            this.options.batch ?? 10,
+        ])
+        for (const row of rows) await this.settle(subscription, { msgId: row.msg_id, readCt: row.read_ct, message: row.message })
+        return rows.length
+    }
+
+    private async loop(subscription: EventSubscription): Promise<void> {
+        while (this.running) {
+            const read = await this.drain(subscription).catch((cause: unknown) => {
+                this.logger.error(EventBusLogEvent.ReadFailed, cause, { queue: subscription.queue })
+                return 0
+            })
+            if (read === 0) await new Promise((resolve) => setTimeout(resolve, this.options.idleMs ?? 500))
+        }
+    }
+
+    private async settle(subscription: EventSubscription, message: EventMessage): Promise<void> {
+        const event = subscription.consumer.event.parse(message.message)
+        const correlationId = event === null ? null : correlationOf(message.message, event.eventId)
+        if (event === null || correlationId === null || !isDedupeKey(event.payload.dedupeKey)) return this.dead(subscription, message, "malformed", null)
+        if (message.readCt > subscription.maxDeliveries) return this.dead(subscription, message, "max-deliveries", event.eventName)
+        try {
+            await subscription.consumer.handle({
+                correlationId,
+                eventId: event.eventId,
+                consumer: subscription.queue,
+                dedupeKey: event.payload.dedupeKey,
+                event,
+                attempt: message.readCt,
+            })
+        } catch (cause) {
+            this.logger.error(EventBusLogEvent.ConsumerFailed, cause, { consumer: subscription.queue, event: event.eventName, attempt: message.readCt })
+            return
+        }
+        await callDbFunction(this.entityManager, "public.event_bus_archive", [subscription.queue, message.msgId])
+    }
+
+    /** Moves the message to `<queue>__dead` and archives the original, in one call. */
+    private async dead(subscription: EventSubscription, message: EventMessage, reason: string, eventName: string | null): Promise<void> {
+        this.logger.warn(EventBusLogEvent.DeliveryDead, { consumer: subscription.queue, event: eventName, msgId: message.msgId, reason, attempt: message.readCt })
+        await callDbFunction(this.entityManager, "public.event_bus_bury", [subscription.queue, message.msgId, message.readCt, JSON.stringify(message.message), reason])
+    }
+}