@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,93 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import { EventBusError, EventBusErrorCode } from "./errors/event-bus.error"
+import type { BaseEvent, EventClass, EventDeadLetter, EventEnvelope } from "./event-bus.contracts"
+import { InjectEventBusOptions, InjectEventTransport } from "./event-bus.decorators"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventBus } from "./event-bus.port"
+import { readEnvelopeText } from "./event-envelope.policy"
+import type { EventTransport, InboundMessage } from "./event-transport.port"
+import {
+    ATTEMPT_HEADER,
+    DEAD_LETTER_ID_SEPARATOR,
+    ORIGIN_HEADER,
+    REASON_HEADER,
+    REQUEUED_HEADER,
+    deadLetterTopicOf,
+    retryTopicOf,
+    topicOf,
+} from "./event.policy"
+import { INSERT_OUTBOX_ROW } from "./persistence/event-bus.sql"
+
+/** The body of a marker message: it carries nothing, its header says which dead letter it closes. */
+const MARKER_VALUE = "{}"
+
+/** The id of a dead letter: where its message sits on the dead-letter topic. */
+const deadLetterIdOf = (message: InboundMessage): string =>
+    [message.topic, message.partition, message.offset].join(DEAD_LETTER_ID_SEPARATOR)
+
+@Injectable()
+/**
+ * The publishing side of the event bus. `publish` writes the event as a row of the outbox of the caller's transaction, so the
+ * event exists exactly when the change it reports commits; the relay hands the row to the broker afterwards. The operator
+ * reads follow the broker: the retry topic says what waits for its backoff, the dead-letter topic what ran out of attempts,
+ * and a requeue puts the original message back on its main topic and closes the dead letter with a marker.
+ */
+export class EventBusService implements EventBus {
+    constructor(
+        @InjectEventBusOptions() private readonly options: EventBusOptions,
+        @InjectEventTransport() private readonly transport: EventTransport,
+        @InjectClock() private readonly clock: Clock,
+    ) {}
+
+    /** Writes the event in the outbox of the transaction `tx`; the event id is the partition key, so the events of one aggregate keep their order. */
+    async publish(event: BaseEvent, tx: EntityManager): Promise<void> {
+        const envelope: EventEnvelope = { eventId: event.eventId, eventName: event.eventName, payload: event.payload }
+        await tx.query(INSERT_OUTBOX_ROW, [
+            event.eventId,
+            event.eventName,
+            topicOf(this.options.topicPrefix, event.eventName),
+            event.eventId,
+            JSON.stringify(envelope),
+            this.clock.now(),
+        ])
+    }
+
+    /** How many deliveries of the class wait on the retry topic for their backoff to pass. */
+    pendingRetries(event: EventClass<BaseEvent>): Promise<number> {
+        return this.transport.lag(retryTopicOf(this.options.topicPrefix, event.eventName))
+    }
+
+    /** The events of the class that ran out of attempts and were not requeued since. */
+    async deadLetters(event: EventClass<BaseEvent>): Promise<ReadonlyArray<EventDeadLetter>> {
+        const messages = await this.transport.read(deadLetterTopicOf(this.options.topicPrefix, event.eventName))
+        const closed = new Set(messages.map((message) => message.headers[REQUEUED_HEADER]))
+        return messages
+            .filter((message) => message.headers[REQUEUED_HEADER] === undefined)
+            .filter((message) => readEnvelopeText(message.value).eventName === event.eventName)
+            .filter((message) => !closed.has(deadLetterIdOf(message)))
+            .map((message) => ({
+                id: deadLetterIdOf(message),
+                eventName: event.eventName,
+                eventId: message.key,
+                reason: message.headers[REASON_HEADER] ?? "",
+                attempts: Number(message.headers[ATTEMPT_HEADER] ?? 0),
+            }))
+    }
+
+    /** Puts a dead letter back on its main topic with a fresh attempt count and closes it with a marker; an id the topic does not hold is refused. */
+    async requeue(deadLetterId: string): Promise<void> {
+        const topic = deadLetterId.slice(0, deadLetterId.indexOf(DEAD_LETTER_ID_SEPARATOR))
+        const letter = (await this.transport.read(topic)).find((message) => deadLetterIdOf(message) === deadLetterId)
+        const origin = letter?.headers[ORIGIN_HEADER]
+        if (letter === undefined || origin === undefined) {
+            throw new EventBusError({ code: EventBusErrorCode.DeadLetterUnknown, params: { id: deadLetterId } })
+        }
+        await this.transport.send([
+            { topic: origin, key: letter.key, value: letter.value, headers: {} },
+            { topic, key: letter.key, value: MARKER_VALUE, headers: { [REQUEUED_HEADER]: deadLetterId } },
+        ])
+    }
+}

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

@@ -0,0 +1,90 @@
+import { BaseEvent } from "./event-bus.contracts"
+import { readEnvelope, readEnvelopeText, readEventOf } from "./event-envelope.policy"
+
+interface PingPayload {
+    readonly note: string
+}
+
+class PingEvent extends BaseEvent {
+    readonly eventName = "probe.ping"
+
+    constructor(
+        readonly eventId: string,
+        readonly payload: PingPayload,
+    ) {
+        super()
+    }
+}
+
+const isPingPayload = (payload: Record<string, unknown>): payload is PingPayload & Record<string, unknown> =>
+    typeof payload.note === "string"
+const buildPing = (eventId: string, payload: PingPayload): PingEvent => new PingEvent(eventId, payload)
+
+describe("event envelope policies", () => {
+    describe("readEnvelope", () => {
+        it("reads the event id and payload of an envelope", () => {
+            expect(readEnvelope({ eventId: "event-1", payload: { note: "hello" }, ignored: true })).toEqual({
+                eventId: "event-1",
+                payload: { note: "hello" },
+            })
+        })
+
+        it.each([
+            [null, "a non-record"],
+            [{ eventId: 1, payload: {} }, "a non-text event id"],
+            [{ eventId: "event-1", payload: 1 }, "a non-record payload"],
+        ])("refuses %s because it is %s", (envelope: unknown, _why: string) => {
+            expect(readEnvelope(envelope)).toBeNull()
+        })
+    })
+
+    describe("readEnvelopeText", () => {
+        it("parses an envelope and names its event", () => {
+            const envelope = { eventId: "event-1", eventName: "probe.ping", payload: { note: "hello" } }
+
+            expect(readEnvelopeText(JSON.stringify(envelope))).toEqual({
+                eventName: "probe.ping",
+                envelope,
+                cause: null,
+            })
+        })
+
+        it.each([JSON.stringify([]), JSON.stringify({ eventName: 1 })])(
+            "keeps a parsed JSON value without a text event name unnamed",
+            (value) => {
+                expect(readEnvelopeText(value)).toMatchObject({ eventName: "", cause: null })
+            },
+        )
+
+        it("returns the parse failure for text that is not JSON", () => {
+            const result = readEnvelopeText("not json")
+
+            expect(result.eventName).toBe("")
+            expect(result.envelope).toBeNull()
+            expect(result.cause).toBeInstanceOf(SyntaxError)
+        })
+    })
+
+    describe("readEventOf", () => {
+        it("builds an event after the envelope and its payload are proven", () => {
+            expect(readEventOf({ eventId: "event-1", payload: { note: "hello" } }, isPingPayload, buildPing)).toEqual(
+                new PingEvent("event-1", { note: "hello" }),
+            )
+        })
+
+        it("refuses a value that is not an envelope without checking its payload", () => {
+            let checked = false
+            const guard = (payload: Record<string, unknown>): payload is PingPayload & Record<string, unknown> => {
+                checked = true
+                return isPingPayload(payload)
+            }
+
+            expect(readEventOf(null, guard, buildPing)).toBeNull()
+            expect(checked).toBe(false)
+        })
+
+        it("refuses an envelope whose payload does not have the event fields", () => {
+            expect(readEventOf({ eventId: "event-1", payload: {} }, isPingPayload, buildPing)).toBeNull()
+        })
+    })
+})

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

@@ -0,0 +1,58 @@
+import type { BaseEvent, ParsedEvent } from "./event-bus.contracts"
+import { isRecord } from "@modules/platform/primitives"
+
+/** What a received envelope carries once its shape is checked: the event id and the payload record. */
+export interface ReadEnvelope {
+    /** The stable event id. */
+    readonly eventId: string
+    /** The payload record, its fields still unchecked. */
+    readonly payload: Record<string, unknown>
+}
+
+/** What reading an envelope answers: the checked envelope, or null when the value does not have the shape. */
+export type ReadEnvelopeResult = ReadEnvelope | null
+
+/** What reading the text of a message answers: the event name it carries (empty when none), the parsed value, and the failure when the text is not JSON. */
+export interface ReadEnvelopeText {
+    /** The event name of the envelope, or an empty text when the value is not an envelope. */
+    readonly eventName: string
+    /** The parsed value, or null when the text is not JSON. */
+    readonly envelope: unknown
+    /** Why the text could not be parsed; null when it could. */
+    readonly cause: unknown
+}
+
+/** Checks the shape every envelope has, `{ eventId, payload }`: what an event class reads its own fields from. */
+export const readEnvelope = (envelope: unknown): ReadEnvelopeResult =>
+    isRecord(envelope) && typeof envelope.eventId === "string" && isRecord(envelope.payload)
+        ? { eventId: envelope.eventId, payload: envelope.payload }
+        : null
+
+/** Parses the text of a message and names the event it carries; a text that is not JSON has no name and carries the cause. */
+export const readEnvelopeText = (value: string): ReadEnvelopeText => {
+    try {
+        const envelope: unknown = JSON.parse(value)
+        const eventName = isRecord(envelope) && typeof envelope.eventName === "string" ? envelope.eventName : ""
+        return { eventName, envelope, cause: null }
+    } catch (cause) {
+        return { eventName: "", envelope: null, cause }
+    }
+}
+
+/** What proves the payload record of an envelope has the fields of an event's payload. */
+export type PayloadGuard<Payload extends object> = (
+    payload: Record<string, unknown>,
+) => payload is Payload & Record<string, unknown>
+
+/** What makes an event from a checked envelope: its id and its proven payload. */
+export type EventBuilder<Payload extends object, Event extends BaseEvent> = (eventId: string, payload: Payload) => Event
+
+/** Reads an envelope into an event: the shape is checked, `isPayload` proves the payload fields, `build` makes the event; null when either check fails. */
+export const readEventOf = <Payload extends object, Event extends BaseEvent>(
+    envelope: unknown,
+    isPayload: PayloadGuard<Payload>,
+    build: EventBuilder<Payload, Event>,
+): ParsedEvent<Event> => {
+    const read = readEnvelope(envelope)
+    return read !== null && isPayload(read.payload) ? build(read.eventId, read.payload) : null
+}

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

@@ -0,0 +1,136 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { EVENT_BUS_OPTIONS, EVENT_RELAY_MANAGERS, EVENT_TRANSPORT } from "./event-bus.decorators"
+import { OutboxLogEvent } from "@modules/platform/outbox"
+import type { EventBusOptions } from "./event-bus.options"
+import { EventRelayService } from "./event-relay.service"
+import type { EventTransport } from "./event-transport.port"
+import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/event-bus.sql"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const options: EventBusOptions = {
+    brokers: ["localhost:9094"],
+    groupId: "app",
+    topicPrefix: "",
+    relayIntervalMs: 100,
+    relayBatch: 2,
+    timeoutMs: 3000,
+    connections: [],
+}
+
+const row = (id: string) => ({
+    id,
+    topic: "events.probe",
+    message_key: `o-${id}`,
+    envelope: { eventId: `o-${id}`, eventName: "probe.ping", payload: {} },
+})
+
+const build = async (manager: MockEntityManager) => {
+    const transport = mock<EventTransport>()
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            EventRelayService,
+            { provide: EVENT_BUS_OPTIONS, useValue: options },
+            { provide: EVENT_RELAY_MANAGERS, useValue: [manager] },
+            { provide: EVENT_TRANSPORT, useValue: transport },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { relay: moduleRef.get(EventRelayService), transport, logger }
+}
+
+describe("EventRelayService", () => {
+    describe("relay", () => {
+        it("sends the waiting rows in order and marks them sent in the same transaction", async () => {
+            const tx = fakeTransaction(
+                mockEntityManager({
+                    query: [
+                        [SELECT_WAITING_ROWS, [row("1"), row("2")]],
+                        [MARK_ROWS_SENT, []],
+                    ],
+                }),
+            )
+            const { relay, transport } = await build(tx.em)
+
+            await expect(relay.relay()).resolves.toBe(2)
+
+            expect(tx.em.query).toHaveBeenNthCalledWith(1, SELECT_WAITING_ROWS, [2])
+            expect(transport.send).toHaveBeenCalledWith([
+                { topic: "events.probe", key: "o-1", value: JSON.stringify(row("1").envelope), headers: {} },
+                { topic: "events.probe", key: "o-2", value: JSON.stringify(row("2").envelope), headers: {} },
+            ])
+            expect(tx.em.query).toHaveBeenNthCalledWith(2, MARK_ROWS_SENT, [["1", "2"], new Date(AT)])
+            expect(tx.commits).toBe(1)
+        })
+
+        it("sends nothing and marks nothing when no row waits", async () => {
+            const tx = fakeTransaction(mockEntityManager({ query: [SELECT_WAITING_ROWS, []] }))
+            const { relay, transport } = await build(tx.em)
+
+            await expect(relay.relay()).resolves.toBe(0)
+
+            expect(transport.send).not.toHaveBeenCalled()
+            expect(tx.em.query).toHaveBeenCalledTimes(1)
+        })
+
+        it("leaves the rows unmarked when the broker refuses, so the next pass sends them again", async () => {
+            const tx = fakeTransaction(mockEntityManager({ query: [SELECT_WAITING_ROWS, [row("1")]] }))
+            const { relay, transport } = await build(tx.em)
+            const failure = new Error("broker down")
+            transport.send.mockRejectedValue(failure)
+
+            await expect(relay.relay()).rejects.toBe(failure)
+
+            expect(tx.rollbacks).toBe(1)
+            expect(tx.em.query).toHaveBeenCalledTimes(1)
+        })
+    })
+
+    describe("the loop", () => {
+        it("passes again at once after a pass that sent rows, pauses on an empty outbox, logs a failed pass and stops on shutdown", async () => {
+            const tx = fakeTransaction(
+                mockEntityManager({
+                    query: [
+                        [SELECT_WAITING_ROWS, [row("1")]],
+                        [MARK_ROWS_SENT, []],
+                        [SELECT_WAITING_ROWS, []],
+                    ],
+                }),
+            )
+            const { relay, transport, logger } = await build(tx.em)
+            const failure = new Error("outbox unreadable")
+            let waits = 0
+            let shutdown: Promise<void> = Promise.resolve()
+            let reachedSecondWait: () => void = () => undefined
+            const secondWait = new Promise<void>((resolve) => {
+                reachedSecondWait = resolve
+            })
+            transport.wait.mockImplementation(() => {
+                waits += 1
+                if (waits === 1) tx.em.query.mockRejectedValueOnce(failure)
+                else {
+                    shutdown = relay.onApplicationShutdown()
+                    reachedSecondWait()
+                }
+                return Promise.resolve()
+            })
+
+            relay.onApplicationBootstrap()
+            await secondWait
+            await shutdown
+
+            expect(transport.send).toHaveBeenCalledTimes(1)
+            expect(transport.wait).toHaveBeenCalledWith(100)
+            expect(logger.error).toHaveBeenCalledWith(OutboxLogEvent.RelayFailed, failure, {
+                outbox: "event-bus",
+            })
+        })
+    })
+})

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

@@ -0,0 +1,56 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+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 { OutboxRelayPolicy } from "@modules/platform/outbox"
+import { InjectEventBusOptions, InjectEventRelayManagers, InjectEventTransport } from "./event-bus.decorators"
+import type { EventBusOptions } from "./event-bus.options"
+import type { EventTransport, OutboundMessage } from "./event-transport.port"
+import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/event-bus.sql"
+import type { OutboxRow } from "./persistence/event-bus.rows"
+
+/** The message the broker receives for one outbox row. */
+const messageOf = (row: OutboxRow): OutboundMessage => ({
+    topic: row.topic,
+    key: row.message_key,
+    value: JSON.stringify(row.envelope),
+    headers: {},
+})
+
+@Injectable()
+/**
+ * The relay of the event outbox: it hands the waiting rows of each connection to the broker and marks them sent in the same
+ * transaction (the loop is `OutboxRelayPolicy`'s). A crash between the send and the mark sends the row again, which the consumers
+ * absorb through their inbox.
+ */
+export class EventRelayService extends OutboxRelayPolicy<OutboxRow> {
+    protected readonly outbox = "event-bus"
+
+    constructor(
+        @InjectEventBusOptions() private readonly options: EventBusOptions,
+        @InjectEventRelayManagers() protected readonly managers: ReadonlyArray<EntityManager>,
+        @InjectEventTransport() private readonly transport: EventTransport,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() protected readonly logger: Logger,
+    ) {
+        super()
+    }
+
+    protected select(tx: EntityManager): Promise<Array<OutboxRow>> {
+        return tx.query(SELECT_WAITING_ROWS, [this.options.relayBatch])
+    }
+
+    protected deliver(rows: ReadonlyArray<OutboxRow>): Promise<void> {
+        return this.transport.send(rows.map(messageOf))
+    }
+
+    protected async mark(tx: EntityManager, rows: ReadonlyArray<OutboxRow>): Promise<void> {
+        await tx.query(MARK_ROWS_SENT, [rows.map((row) => row.id), this.clock.now()])
+    }
+
+    protected idle(): Promise<void> {
+        return this.transport.wait(this.options.relayIntervalMs)
+    }
+}