@starci/hfs 4.0.7 → 4.0.9

package/templates/be/patterns/projections/projection.module.ts.tpl

@@ -0,0 +1,18 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./@@name@@.module-definition"
+import { @@Name@@Projection } from "./@@name@@.projection"
+
+@Module({})
+/** The @@name@@ read model: its projection, called by a reactor or a job to recompute and by the api to read; the app registers it once with `isGlobal`. */
+export class @@Name@@Module extends ConfigurableModuleClass {
+    /** Registers the projection once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), @@Name@@Projection],
+            exports: [@@Name@@Projection],
+        }
+    }
+}

package/templates/be/patterns/projections/projection.options.ts.tpl

@@ -0,0 +1,2 @@
+/** The @@name@@ projection takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type @@Name@@Options = Record<never, never>

package/templates/be/patterns/projections/projection.projection.spec.ts.tpl

@@ -0,0 +1,55 @@
+import { Test } from "@nestjs/testing"
+import { mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import { @@connectionUpper@@_ENTITY_MANAGER } from "@modules/platform/database"
+import { @@Name@@Projection } from "./@@name@@.projection"
+import { @@Name@@ProjectionEntity } from "./@@name@@.projection-entity"
+
+const build = async (manager: MockEntityManager = mockEntityManager()) => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [@@Name@@Projection, { provide: @@connectionUpper@@_ENTITY_MANAGER, useValue: manager }],
+    }).compile()
+    return { projection: moduleRef.get(@@Name@@Projection), manager }
+}
+
+describe("@@Name@@Projection", () => {
+    describe("recompute@@Name@@", () => {
+        it("idempotently upserts the row by its natural id", async () => {
+            const { projection, manager } = await build(
+                mockEntityManager({
+                    upsert: [@@Name@@ProjectionEntity, { identifiers: [], generatedMaps: [], raw: [] }],
+                }),
+            )
+
+            await projection.recompute@@Name@@("projection-1")
+            await projection.recompute@@Name@@("projection-1")
+
+            expect(manager.upsert).toHaveBeenNthCalledWith(1, @@Name@@ProjectionEntity, { id: "projection-1" }, [
+                "id",
+            ])
+            expect(manager.upsert).toHaveBeenNthCalledWith(2, @@Name@@ProjectionEntity, { id: "projection-1" }, [
+                "id",
+            ])
+        })
+    })
+
+    describe("get@@Name@@", () => {
+        it("maps a stored row to its public view", async () => {
+            const { projection, manager } = await build()
+            manager.findOne.mockResolvedValue(Object.assign(new @@Name@@ProjectionEntity(), { id: "projection-1" }))
+
+            await expect(projection.get@@Name@@("projection-1")).resolves.toEqual({ id: "projection-1" })
+
+            expect(manager.findOne).toHaveBeenCalledWith(@@Name@@ProjectionEntity, {
+                where: { id: "projection-1" },
+            })
+        })
+
+        it("answers null when no row was computed", async () => {
+            const { projection, manager } = await build()
+            manager.findOne.mockResolvedValue(null)
+
+            await expect(projection.get@@Name@@("missing-projection")).resolves.toBeNull()
+        })
+    })
+})

package/templates/be/patterns/projections/projection.projection.ts.tpl

@@ -0,0 +1,21 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { Inject@@Connection@@EntityManager } from "@modules/platform/database"
+import { @@Name@@ProjectionEntity } from "./@@name@@.projection-entity"
+
+@Injectable()
+/** The @@name@@ read model: the only writer of its table; callers read it with `get*`. */
+export class @@Name@@Projection {
+    constructor(@Inject@@Connection@@EntityManager() private readonly entityManager: EntityManager) {}
+
+    /** Recomputes one row from the source facts of its own context: an upsert by the natural key, so repeating it changes nothing. */
+    async recompute@@Name@@(id: string): Promise<void> {
+        await this.entityManager.upsert(@@Name@@ProjectionEntity, { id }, ["id"])
+    }
+
+    /** Reads one row; the caller never sees the table. */
+    async get@@Name@@(id: string): Promise<{ readonly id: string } | null> {
+        const row = await this.entityManager.findOne(@@Name@@ProjectionEntity, { where: { id } })
+        return row ? { id: row.id } : null
+    }
+}

package/templates/be/patterns/queues/platform/bullmq-queue-transport.client.spec.ts.tpl

@@ -0,0 +1,142 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
+import type { QueueHandler } from "./queue.contracts"
+import { QUEUE_FACTORY, QUEUE_OPTIONS } from "./queue.decorators"
+import type { QueueOptions } from "./queue.options"
+import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS } from "./queue.policy"
+import type { BullmqJob, BullmqQueue, BullmqWorker, QueueFactory } from "./queue-transport.port"
+
+const options: QueueOptions = {
+    redisHost: "redis.test",
+    redisPort: 6380,
+    prefix: "spec.",
+    relayIntervalMs: 100,
+    relayBatch: 50,
+    concurrency: 4,
+    connections: [],
+    schedulers: [],
+}
+
+const build = async () => {
+    const queue = mock<BullmqQueue>()
+    const worker = mock<BullmqWorker>()
+    const factory = mock<QueueFactory>()
+    factory.queue.mockReturnValue(queue)
+    factory.worker.mockReturnValue(worker)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            BullmqQueueTransportClient,
+            { provide: QUEUE_OPTIONS, useValue: options },
+            { provide: QUEUE_FACTORY, useValue: factory },
+        ],
+    }).compile()
+    return { client: moduleRef.get(BullmqQueueTransportClient), queue, worker, factory }
+}
+
+describe("BullmqQueueTransportClient", () => {
+    it("adds idempotent jobs with the queue retry and retention policy", async () => {
+        const { client, queue, factory } = await build()
+        const payload = { orderId: "order-1" }
+
+        await client.add("orders", "outbox-1", payload)
+        await client.add("orders", "outbox-2", payload)
+
+        expect(factory.queue).toHaveBeenCalledTimes(1)
+        expect(factory.queue).toHaveBeenCalledWith("orders", {
+            prefix: "spec.",
+            connection: { host: "redis.test", port: 6380, maxRetriesPerRequest: null },
+        })
+        expect(queue.add).toHaveBeenNthCalledWith(1, "orders", payload, {
+            jobId: "outbox-1",
+            attempts: ATTEMPTS,
+            backoff: { type: "exponential", delay: BACKOFF_MS },
+            removeOnComplete: { age: KEEP_COMPLETED_SECONDS },
+        })
+    })
+
+    it("upserts schedulers with their payload or an empty payload", async () => {
+        const { client, queue } = await build()
+
+        await client.upsertScheduler({ queue: "billing", id: "settlement", everyMs: 60_000, payload: { shard: 2 } })
+        await client.upsertScheduler({ queue: "billing", id: "cleanup", everyMs: 120_000 })
+
+        expect(queue.upsertJobScheduler).toHaveBeenNthCalledWith(
+            1,
+            "settlement",
+            { every: 60_000 },
+            { name: "billing", data: { shard: 2 }, opts: { attempts: ATTEMPTS } },
+        )
+        expect(queue.upsertJobScheduler).toHaveBeenNthCalledWith(
+            2,
+            "cleanup",
+            { every: 120_000 },
+            { name: "billing", data: {}, opts: { attempts: ATTEMPTS } },
+        )
+    })
+
+    it("starts a worker that translates BullMQ jobs into queue deliveries", async () => {
+        const { client, factory } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        handler.handle.mockResolvedValue(undefined)
+
+        await client.work(handler, 3)
+
+        expect(factory.worker).toHaveBeenCalledWith("orders", expect.any(Function), {
+            prefix: "spec.",
+            connection: { host: "redis.test", port: 6380, maxRetriesPerRequest: null },
+            concurrency: 3,
+        })
+        const processor = factory.worker.mock.calls[0]?.[1]
+        await processor?.(mock<BullmqJob>({ id: "job-1", data: { orderId: "order-1" }, attemptsMade: 2 }))
+        await processor?.(mock<BullmqJob>({ id: undefined, data: { orderId: "order-2" }, attemptsMade: 0 }))
+
+        expect(handler.handle).toHaveBeenNthCalledWith(1, {
+            id: "job-1",
+            queue: "orders",
+            payload: { orderId: "order-1" },
+            attempt: 3,
+        })
+        expect(handler.handle).toHaveBeenNthCalledWith(2, {
+            id: "",
+            queue: "orders",
+            payload: { orderId: "order-2" },
+            attempt: 1,
+        })
+    })
+
+    it("waits for the requested delay", async () => {
+        jest.useFakeTimers()
+        try {
+            const { client } = await build()
+
+            const waiting = client.wait(250)
+            await jest.advanceTimersByTimeAsync(250)
+
+            await expect(waiting).resolves.toBeUndefined()
+        } finally {
+            jest.useRealTimers()
+        }
+    })
+
+    it("closes workers before queues", async () => {
+        const { client, queue, worker } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        let finishWorkerClose: (() => void) | undefined
+        worker.close.mockReturnValue(
+            new Promise((resolve) => {
+                finishWorkerClose = resolve
+            }),
+        )
+        await client.add("orders", "outbox-1", {})
+        await client.work(handler, 3)
+
+        const closing = client.close()
+
+        expect(worker.close).toHaveBeenCalledWith(true)
+        expect(queue.close).not.toHaveBeenCalled()
+        finishWorkerClose?.()
+        await closing
+        expect(queue.close).toHaveBeenCalledTimes(1)
+    })
+})

package/templates/be/patterns/queues/platform/bullmq-queue-transport.client.ts.tpl

@@ -0,0 +1,81 @@
+import { Injectable } from "@nestjs/common"
+import { InjectQueueFactory, InjectQueueOptions } from "./queue.decorators"
+import type { QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+import type { QueueOptions } from "./queue.options"
+import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS, jobNameOf } from "./queue.policy"
+import type { BullmqConnection, BullmqQueue, BullmqWorker, QueueFactory, QueueTransport } from "./queue-transport.port"
+
+@Injectable()
+/** The QueueTransport port over a Redis the app names in its options; the BullMQ objects come from the injected factory the module composes. */
+export class BullmqQueueTransportClient implements QueueTransport {
+    private readonly queues = new Map<string, BullmqQueue>()
+    private readonly workers: Array<BullmqWorker> = []
+
+    constructor(
+        @InjectQueueOptions() private readonly options: QueueOptions,
+        @InjectQueueFactory() private readonly factory: QueueFactory,
+    ) {}
+
+    /** Adds the job with the outbox row id as its BullMQ id, so adding it twice leaves one job. */
+    async add(queue: string, jobId: string, payload: object): Promise<void> {
+        await this.queueOf(queue).add(jobNameOf(queue), payload, {
+            jobId,
+            attempts: ATTEMPTS,
+            backoff: { type: "exponential", delay: BACKOFF_MS },
+            removeOnComplete: { age: KEEP_COMPLETED_SECONDS },
+        })
+    }
+
+    /** Creates or updates the scheduler; BullMQ keeps one per id however many replicas call this. */
+    async upsertScheduler(scheduler: QueueSchedulerDefinition): Promise<void> {
+        await this.queueOf(scheduler.queue).upsertJobScheduler(
+            scheduler.id,
+            { every: scheduler.everyMs },
+            { name: jobNameOf(scheduler.queue), data: scheduler.payload ?? {}, opts: { attempts: ATTEMPTS } },
+        )
+    }
+
+    /** Starts a worker of the queue. */
+    work(handler: QueueHandler, concurrency: number): Promise<void> {
+        this.workers.push(
+            this.factory.worker(
+                handler.queue,
+                (job) =>
+                    handler.handle({
+                        id: job.id ?? "",
+                        queue: handler.queue,
+                        payload: job.data,
+                        attempt: job.attemptsMade + 1,
+                    }),
+                { ...this.connection(), concurrency },
+            ),
+        )
+        return Promise.resolve()
+    }
+
+    /** Resolves after `ms` milliseconds. */
+    wait(ms: number): Promise<void> {
+        return new Promise((resolve) => setTimeout(resolve, ms))
+    }
+
+    /** Closes the workers first, then the queues. */
+    async close(): Promise<void> {
+        await Promise.all(this.workers.map((worker) => worker.close(true)))
+        await Promise.all([...this.queues.values()].map((queue) => queue.close()))
+    }
+
+    private connection(): BullmqConnection {
+        return {
+            prefix: this.options.prefix,
+            connection: { host: this.options.redisHost, port: this.options.redisPort, maxRetriesPerRequest: null },
+        }
+    }
+
+    private queueOf(name: string): BullmqQueue {
+        const known = this.queues.get(name)
+        if (known !== undefined) return known
+        const created = this.factory.queue(name, this.connection())
+        this.queues.set(name, created)
+        return created
+    }
+}

package/templates/be/patterns/queues/platform/persistence.connection.ts.tpl

@@ -0,0 +1,8 @@
+import { QueueOutboxEntity } from "./entities/queue-outbox.entity"
+import { CreateQueueOutbox@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-queue-outbox"
+
+/** The entities of the queues, for every connection that enqueues jobs. */
+export const queueEntities = [QueueOutboxEntity]
+
+/** The migrations of the queues, in the order they run. */
+export const queueMigrations = [CreateQueueOutbox@@epochMs13@@]

package/templates/be/patterns/queues/platform/persistence.migration.ts.tpl

@@ -0,0 +1,25 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the outbox table the queues write jobs in and the relay reads them from. */
+export class CreateQueueOutbox@@epochMs13@@ implements MigrationInterface {
+    name = "CreateQueueOutbox@@epochMs13@@"
+
+    /** Creates the outbox and the partial index of the rows that wait. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE queue_outbox (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    queue varchar(200) NOT NULL,
+    payload jsonb NOT NULL,
+    created_at timestamptz NOT NULL,
+    sent_at timestamptz
+)`)
+        await queryRunner.query(
+            `CREATE INDEX queue_outbox_unsent_idx ON queue_outbox (created_at, id) WHERE sent_at IS NULL`,
+        )
+    }
+
+    /** Drops the outbox. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE queue_outbox`)
+    }
+}

package/templates/be/patterns/queues/platform/persistence.queue-outbox.entity.ts.tpl

@@ -0,0 +1,25 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+@Entity("queue_outbox")
+/** One job waiting to start: written in the transaction of the change that needs it, handed to BullMQ by the relay. */
+export class QueueOutboxEntity {
+    /** The row id; it becomes the BullMQ job id. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+
+    /** The queue the job goes to. */
+    @Column({ name: "queue", type: "varchar", length: 200 })
+    queue!: string
+
+    /** The payload of the job: ids, never an entity. */
+    @Column({ name: "payload", type: "jsonb" })
+    payload!: object
+
+    /** When the row was written. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+
+    /** When the relay handed the row to BullMQ; null while it waits. */
+    @Column({ name: "sent_at", type: "timestamptz", nullable: true })
+    sentAt!: Date | null
+}

package/templates/be/patterns/queues/platform/persistence.queue.rows.ts.tpl

@@ -0,0 +1,9 @@
+/** One row the relay reads from the queue outbox. */
+export interface QueueRow {
+    /** The row id: it is the BullMQ job id, so a repeated relay pass adds nothing. */
+    readonly id: string
+    /** The queue the job goes to. */
+    readonly queue: string
+    /** The payload, as the database returns the jsonb value. */
+    readonly payload: object
+}

package/templates/be/patterns/queues/platform/persistence.queue.sql.ts.tpl

@@ -0,0 +1,12 @@
+import { sql } from "@modules/platform/database"
+
+/** Writes one job in the outbox ($1 queue, $2 payload, $3 instant). */
+export const INSERT_QUEUE_ROW = sql`INSERT INTO queue_outbox (queue, payload, created_at)
+    VALUES ($1, $2, $3)`
+
+/** Locks and reads the oldest rows that wait ($1 batch size); a second relay skips the rows this one holds. */
+export const SELECT_WAITING_ROWS = sql`SELECT id, queue, payload FROM queue_outbox
+    WHERE sent_at IS NULL ORDER BY created_at, id LIMIT $1 FOR UPDATE SKIP LOCKED`
+
+/** Marks the rows as handed to BullMQ ($1 ids, $2 instant). */
+export const MARK_ROWS_SENT = sql`UPDATE queue_outbox SET sent_at = $2 WHERE id = ANY($1::uuid[])`

package/templates/be/patterns/queues/platform/queue-outbox.service.spec.ts.tpl

@@ -0,0 +1,48 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { QueueOutboxService } from "./queue-outbox.service"
+import { INSERT_QUEUE_ROW } from "./persistence/queue.sql"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [QueueOutboxService, { provide: CLOCK, useValue: new FakeClock(AT) }],
+    }).compile()
+    return { outbox: moduleRef.get(QueueOutboxService) }
+}
+
+describe("QueueOutboxService", () => {
+    describe("write", () => {
+        it("writes the job as a row of the outbox of the transaction it is given", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager({ query: [INSERT_QUEUE_ROW, []] }))
+
+            await tx.em.transaction((manager) => outbox.write(manager, "mail", { id: "m-1" }))
+
+            expect(tx.em.query).toHaveBeenCalledWith(INSERT_QUEUE_ROW, [
+                "mail",
+                JSON.stringify({ id: "m-1" }),
+                new Date(AT),
+            ])
+            expect(tx.commits).toBe(1)
+        })
+
+        it("leaves no row behind when the transaction rolls back", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager({ query: [INSERT_QUEUE_ROW, []] }))
+            const failure = new Error("the change failed")
+
+            await expect(
+                tx.em.transaction(async (manager) => {
+                    await outbox.write(manager, "mail", { id: "m-1" })
+                    return Promise.reject(failure)
+                }),
+            ).rejects.toBe(failure)
+
+            expect(tx.rollbacks).toBe(1)
+            expect(tx.committedWrites).toEqual([])
+        })
+    })
+})

package/templates/be/patterns/queues/platform/queue-outbox.service.ts.tpl

@@ -0,0 +1,17 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import type { QueueOutbox } from "./queue.port"
+import { INSERT_QUEUE_ROW } from "./persistence/queue.sql"
+
+@Injectable()
+/** The writing side of the queues: a job is a row of the outbox of the caller's transaction, so it exists exactly when the change that needs it commits. */
+export class QueueOutboxService implements QueueOutbox {
+    constructor(@InjectClock() private readonly clock: Clock) {}
+
+    /** Writes the job in the outbox of the transaction `tx`; the relay adds it to BullMQ after the commit. */
+    async write(tx: EntityManager, queue: string, payload: object): Promise<void> {
+        await tx.query(INSERT_QUEUE_ROW, [queue, JSON.stringify(payload), this.clock.now()])
+    }
+}

package/templates/be/patterns/queues/platform/queue-relay.service.spec.ts.tpl

@@ -0,0 +1,128 @@
+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 { QUEUE_OPTIONS, QUEUE_RELAY_MANAGERS, QUEUE_TRANSPORT } from "./queue.decorators"
+import { OutboxLogEvent } from "@modules/platform/outbox"
+import type { QueueOptions } from "./queue.options"
+import { QueueRelayService } from "./queue-relay.service"
+import type { QueueTransport } from "./queue-transport.port"
+import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/queue.sql"
+
+const AT = "2026-02-03T04:05:06.000Z"
+
+const options: QueueOptions = {
+    redisHost: "localhost",
+    redisPort: 6379,
+    prefix: "test",
+    relayIntervalMs: 100,
+    relayBatch: 2,
+    concurrency: 1,
+    connections: [],
+    schedulers: [],
+}
+
+const row = (id: string) => ({ id, queue: "mail", payload: { id: `m-${id}` } })
+
+const build = async (manager: MockEntityManager) => {
+    const transport = mock<QueueTransport>()
+    const logger = mock<Logger>()
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            QueueRelayService,
+            { provide: QUEUE_OPTIONS, useValue: options },
+            { provide: QUEUE_RELAY_MANAGERS, useValue: [manager] },
+            { provide: QUEUE_TRANSPORT, useValue: transport },
+            { provide: CLOCK, useValue: new FakeClock(AT) },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { relay: moduleRef.get(QueueRelayService), transport, logger }
+}
+
+describe("QueueRelayService", () => {
+    describe("relay", () => {
+        it("adds the waiting rows to BullMQ with the row id as the job id 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.add).toHaveBeenNthCalledWith(1, "mail", "1", { id: "m-1" })
+            expect(transport.add).toHaveBeenNthCalledWith(2, "mail", "2", { id: "m-2" })
+            expect(tx.em.query).toHaveBeenNthCalledWith(2, MARK_ROWS_SENT, [["1", "2"], new Date(AT)])
+            expect(tx.commits).toBe(1)
+        })
+
+        it("adds 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.add).not.toHaveBeenCalled()
+            expect(tx.em.query).toHaveBeenCalledTimes(1)
+        })
+
+        it("leaves the rows unmarked when BullMQ refuses, so the next pass adds them again", async () => {
+            const tx = fakeTransaction(mockEntityManager({ query: [SELECT_WAITING_ROWS, [row("1")]] }))
+            const { relay, transport } = await build(tx.em)
+            const failure = new Error("redis down")
+            transport.add.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 added 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.add).toHaveBeenCalledTimes(1)
+            expect(transport.wait).toHaveBeenCalledWith(100)
+            expect(logger.error).toHaveBeenCalledWith(OutboxLogEvent.RelayFailed, failure, { outbox: "queue" })
+        })
+    })
+})

package/templates/be/patterns/queues/platform/queue-relay.service.ts.tpl

@@ -0,0 +1,48 @@
+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 { InjectQueueOptions, InjectQueueRelayManagers, InjectQueueTransport } from "./queue.decorators"
+import type { QueueOptions } from "./queue.options"
+import type { QueueTransport } from "./queue-transport.port"
+import { MARK_ROWS_SENT, SELECT_WAITING_ROWS } from "./persistence/queue.sql"
+import type { QueueRow } from "./persistence/queue.rows"
+
+@Injectable()
+/**
+ * The relay of the queue outbox: it adds each waiting row to BullMQ with the row id as the job id and marks the rows sent in the same
+ * transaction (the loop is `OutboxRelayPolicy`'s). A crash between the add and the mark adds the row again, which BullMQ ignores while
+ * it holds the id and the job fence absorbs afterwards.
+ */
+export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
+    protected readonly outbox = "queue"
+
+    constructor(
+        @InjectQueueOptions() private readonly options: QueueOptions,
+        @InjectQueueRelayManagers() protected readonly managers: ReadonlyArray<EntityManager>,
+        @InjectQueueTransport() private readonly transport: QueueTransport,
+        @InjectClock() private readonly clock: Clock,
+        @InjectLogger() protected readonly logger: Logger,
+    ) {
+        super()
+    }
+
+    protected select(tx: EntityManager): Promise<Array<QueueRow>> {
+        return tx.query(SELECT_WAITING_ROWS, [this.options.relayBatch])
+    }
+
+    protected async deliver(rows: ReadonlyArray<QueueRow>): Promise<void> {
+        for (const row of rows) await this.transport.add(row.queue, row.id, row.payload)
+    }
+
+    protected async mark(tx: EntityManager, rows: ReadonlyArray<QueueRow>): 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)
+    }
+}