@starci/hfs 4.7.32 → 4.7.34

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

@@ -1,9 +1,24 @@
 import { Injectable } from "@nestjs/common"
+import { isRecord } from "@modules/platform/primitives"
+import { InjectLogger, isCorrelationId } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { InjectIds } from "@modules/platform/ids"
+import type { Ids } from "@modules/platform/ids"
 import { InjectQueueFactory, InjectQueueOptions } from "./queue.decorators"
-import type { QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+import { BULLMQ_JOB_SCHEMA } from "./queue.contracts"
+import type { QueueDelivery, QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+import { QueueError, QueueErrorCode } from "./errors/queue.error"
+import { QueueLogEvent } from "./queue.log-events"
 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"
+import type {
+    BullmqConnection,
+    BullmqJob,
+    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. */
@@ -14,16 +29,23 @@ export class BullmqQueueTransportClient implements QueueTransport {
     constructor(
         @InjectQueueOptions() private readonly options: QueueOptions,
         @InjectQueueFactory() private readonly factory: QueueFactory,
+        @InjectIds() private readonly ids: Ids,
+        @InjectLogger() private readonly logger: Logger,
     ) {}
 
     /** 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 },
-        })
+    async add(queue: string, jobId: string, payload: object, correlationId: string): Promise<void> {
+        if (!isCorrelationId(correlationId)) throw new QueueError({ code: QueueErrorCode.CorrelationInvalid })
+        await this.queueOf(queue).add(
+            jobNameOf(queue),
+            { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload, correlationId },
+            {
+                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. */
@@ -31,25 +53,25 @@ export class BullmqQueueTransportClient implements QueueTransport {
         await this.queueOf(scheduler.queue).upsertJobScheduler(
             scheduler.id,
             { every: scheduler.everyMs },
-            { name: jobNameOf(scheduler.queue), data: scheduler.payload ?? {}, opts: { attempts: ATTEMPTS } },
+            {
+                name: jobNameOf(scheduler.queue),
+                data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: 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 },
-            ),
+        const worker = this.factory.worker(
+            handler.queue,
+            async (job) => {
+                await handler.handle(this.deliveryOf(handler.queue, job))
+            },
+            { ...this.connection(), concurrency },
         )
+        worker.on("error", (cause) => this.logger.error(QueueLogEvent.WorkerFailed, cause, { queue: handler.queue }))
+        this.workers.push(worker)
         return Promise.resolve()
     }
 
@@ -64,6 +86,39 @@ export class BullmqQueueTransportClient implements QueueTransport {
         await Promise.all([...this.queues.values()].map((queue) => queue.close()))
     }
 
+    /** Reads current envelopes and stored raw payloads without changing the identity of a retried job. */
+    private deliveryOf(queue: string, job: BullmqJob): QueueDelivery {
+        const data = job.data
+        if (!isRecord(data)) throw new QueueError({ code: QueueErrorCode.MalformedMessage })
+        let payload: object = data
+        let correlationId = job.id
+        const schema = data.schema
+        const schemaPrefix = BULLMQ_JOB_SCHEMA.slice(0, BULLMQ_JOB_SCHEMA.lastIndexOf("@") + 1)
+        if (typeof schema === "string" && schema.startsWith(schemaPrefix)) {
+            if (
+                schema !== BULLMQ_JOB_SCHEMA ||
+                (data.kind !== "enqueued" && data.kind !== "scheduled") ||
+                !isRecord(data.payload)
+            ) {
+                throw new QueueError({ code: QueueErrorCode.MalformedMessage })
+            }
+            payload = data.payload
+            if (data.kind === "enqueued" || "correlationId" in data) {
+                if (!isCorrelationId(data.correlationId)) {
+                    throw new QueueError({ code: QueueErrorCode.MalformedMessage })
+                }
+                correlationId = data.correlationId
+            }
+        }
+        return {
+            id: job.id ?? "",
+            queue,
+            correlationId: correlationId ?? this.ids.next(),
+            payload,
+            attempt: job.attemptsMade + 1,
+        }
+    }
+
     private connection(): BullmqConnection {
         return {
             prefix: this.options.prefix,
@@ -80,6 +135,7 @@ export class BullmqQueueTransportClient implements QueueTransport {
         const known = this.queues.get(name)
         if (known !== undefined) return known
         const created = this.factory.queue(name, this.connection())
+        created.on("error", (cause) => this.logger.error(QueueLogEvent.QueueFailed, cause, { queue: name }))
         this.queues.set(name, created)
         return created
     }

package/templates/be/patterns/queues/platform/errors/queue.error.ts.tpl

@@ -0,0 +1,19 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the queue capability. */
+export enum QueueErrorCode {
+    /** Stored job data does not satisfy the delivery envelope contract. */
+    MalformedMessage = "QUEUE_MALFORMED_MESSAGE",
+    /** A producer supplied an identity that is unsafe or unbounded. */
+    CorrelationInvalid = "QUEUE_CORRELATION_INVALID",
+}
+
+/** How each queue code travels. */
+export const QUEUE_ERROR_KINDS: Record<QueueErrorCode, ErrorKind> = {
+    [QueueErrorCode.MalformedMessage]: "internal",
+    [QueueErrorCode.CorrelationInvalid]: "invalid",
+}
+
+/** The queue capability's failures, retained by the broker for inspection and retry. */
+export class QueueError extends DomainError<QueueErrorCode> {}

package/templates/be/patterns/queues/platform/messages/queue.messages.ts.tpl

@@ -0,0 +1,13 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of queue failures in Vietnamese and English. */
+export const QUEUE_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.QUEUE_MALFORMED_MESSAGE": "Th\u00f4ng \u0111i\u1ec7p h\u00e0ng \u0111\u1ee3i \u0111\u00e3 l\u01b0u kh\u00f4ng h\u1ee3p l\u1ec7.",
+        "errors.QUEUE_CORRELATION_INVALID": "M\u00e3 t\u01b0\u01a1ng quan c\u1ee7a th\u00f4ng \u0111i\u1ec7p h\u00e0ng \u0111\u1ee3i kh\u00f4ng h\u1ee3p l\u1ec7.",
+    },
+    en: {
+        "errors.QUEUE_MALFORMED_MESSAGE": "The stored queue message is malformed.",
+        "errors.QUEUE_CORRELATION_INVALID": "The queue message correlation id is invalid.",
+    },
+}

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

@@ -10,6 +10,7 @@ export class CreateQueueOutbox@@epochMs13@@ implements MigrationInterface {
     id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
     queue varchar(200) NOT NULL,
     payload jsonb NOT NULL,
+    correlation_id varchar(128) NOT NULL DEFAULT pg_catalog.gen_random_uuid()::text,
     created_at timestamptz NOT NULL,
     sent_at timestamptz
 )`)

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

@@ -3,6 +3,10 @@ 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 upstream correlation id persisted with the job. */
+    @Column({ name: "correlation_id", type: "varchar", length: 128, default: () => "pg_catalog.gen_random_uuid()::text" })
+    correlationId!: string
+
     /** The row id; it becomes the BullMQ job id. */
     @PrimaryGeneratedColumn("uuid", { name: "id" })
     id!: string

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

@@ -1,5 +1,7 @@
 /** One row the relay reads from the queue outbox. */
 export interface QueueRow {
+    /** The correlation id recorded by the producer's transaction. */
+    readonly correlationId: string
     /** 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. */

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

@@ -1,11 +1,11 @@
 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)`
+/** Writes one job in the outbox ($1 queue, $2 payload, $3 instant, $4 correlation id). */
+export const INSERT_QUEUE_ROW = sql`INSERT INTO queue_outbox (queue, payload, created_at, correlation_id)
+    VALUES ($1, $2, $3, $4)`
 
 /** 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
+export const SELECT_WAITING_ROWS = sql`SELECT id, queue, payload, correlation_id AS "correlationId" 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). */

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

@@ -3,6 +3,7 @@ import { FakeClock, fakeTransaction, mockEntityManager } from "@starci/jest-pres
 import { CLOCK } from "@modules/platform/clock"
 import { QueueOutboxService } from "./queue-outbox.service"
 import { INSERT_QUEUE_ROW } from "./persistence/queue.sql"
+import { QueueErrorCode } from "./errors/queue.error"
 
 const AT = "2026-02-03T04:05:06.000Z"
 
@@ -19,12 +20,13 @@ describe("QueueOutboxService", () => {
             const { outbox } = await build()
             const tx = fakeTransaction(mockEntityManager({ query: [INSERT_QUEUE_ROW, []] }))
 
-            await tx.em.transaction((manager) => outbox.write(manager, "mail", { id: "m-1" }))
+            await tx.em.transaction((manager) => outbox.write(manager, "mail", { id: "m-1" }, "request-1"))
 
             expect(tx.em.query).toHaveBeenCalledWith(INSERT_QUEUE_ROW, [
                 "mail",
                 JSON.stringify({ id: "m-1" }),
                 new Date(AT),
+                "request-1",
             ])
             expect(tx.commits).toBe(1)
         })
@@ -36,7 +38,7 @@ describe("QueueOutboxService", () => {
 
             await expect(
                 tx.em.transaction(async (manager) => {
-                    await outbox.write(manager, "mail", { id: "m-1" })
+                    await outbox.write(manager, "mail", { id: "m-1" }, "request-1")
                     return Promise.reject(failure)
                 }),
             ).rejects.toBe(failure)
@@ -44,5 +46,15 @@ describe("QueueOutboxService", () => {
             expect(tx.rollbacks).toBe(1)
             expect(tx.committedWrites).toEqual([])
         })
+
+        it("rejects an unsafe correlation id before writing any SQL", async () => {
+            const { outbox } = await build()
+            const tx = fakeTransaction(mockEntityManager())
+            await expect(
+                tx.em.transaction((manager) => outbox.write(manager, "mail", {}, "bad\nid")),
+            ).rejects.toMatchObject({ code: QueueErrorCode.CorrelationInvalid })
+            expect(tx.em.query).not.toHaveBeenCalled()
+            expect(tx.rollbacks).toBe(1)
+        })
     })
 })

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

@@ -2,7 +2,9 @@ import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
 import { InjectClock } from "@modules/platform/clock"
 import type { Clock } from "@modules/platform/clock"
+import { isCorrelationId } from "@modules/platform/logging"
 import type { QueueOutbox } from "./queue.port"
+import { QueueError, QueueErrorCode } from "./errors/queue.error"
 import { INSERT_QUEUE_ROW } from "./persistence/queue.sql"
 
 @Injectable()
@@ -11,7 +13,8 @@ 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()])
+    async write(tx: EntityManager, queue: string, payload: object, correlationId: string): Promise<void> {
+        if (!isCorrelationId(correlationId)) throw new QueueError({ code: QueueErrorCode.CorrelationInvalid })
+        await tx.query(INSERT_QUEUE_ROW, [queue, JSON.stringify(payload), this.clock.now(), correlationId])
     }
 }

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

@@ -25,7 +25,7 @@ const options: QueueOptions = {
     schedulers: [],
 }
 
-const row = (id: string) => ({ id, queue: "mail", payload: { id: `m-${id}` } })
+const row = (id: string) => ({ id, queue: "mail", payload: { id: `m-${id}` }, correlationId: `request-${id}` })
 
 const build = async (manager: MockEntityManager) => {
     const transport = mock<QueueTransport>()
@@ -43,87 +43,85 @@ const build = async (manager: MockEntityManager) => {
     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)
-        })
+describe("QueueRelayService 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" }, "request-1")
+        expect(transport.add).toHaveBeenNthCalledWith(2, "mail", "2", { id: "m-2" }, "request-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)
+    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)
+        await expect(relay.relay()).resolves.toBe(0)
 
-            expect(transport.add).not.toHaveBeenCalled()
-            expect(tx.em.query).toHaveBeenCalledTimes(1)
-        })
+        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)
+    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)
+        await expect(relay.relay()).rejects.toBe(failure)
 
-            expect(tx.rollbacks).toBe(1)
-            expect(tx.em.query).toHaveBeenCalledTimes(1)
-        })
+        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" })
+describe("QueueRelayService 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

@@ -36,7 +36,7 @@ export class QueueRelayService extends OutboxRelayPolicy<QueueRow> {
     }
 
     protected deliver(rows: ReadonlyArray<QueueRow>): Promise<void> {
-        return eachInOrder(rows, (row) => this.transport.add(row.queue, row.id, row.payload))
+        return eachInOrder(rows, (row) => this.transport.add(row.queue, row.id, row.payload, row.correlationId))
     }
 
     protected async mark(tx: EntityManager, rows: ReadonlyArray<QueueRow>): Promise<void> {

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

@@ -1,9 +1,9 @@
-import type { QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+import type { BULLMQ_JOB_SCHEMA, QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
 
 /** BullMQ as the queue capability sees it: the one port the BullMQ client implements. */
 export interface QueueTransport {
     /** Adds the job to its queue with `jobId`; adding an id BullMQ already holds changes nothing, so a repeated relay pass is harmless. */
-    add(queue: string, jobId: string, payload: object): Promise<void>
+    add(queue: string, jobId: string, payload: object, correlationId: string): Promise<void>
     /** Creates or updates a job scheduler by its id. */
     upsertScheduler(scheduler: QueueSchedulerDefinition): Promise<void>
     /** Starts a worker of the queue the handler names that runs it for every job, `concurrency` at a time. */
@@ -77,15 +77,21 @@ export interface BullmqJobTemplate {
     /** The job name, which is the queue name. */
     readonly name: string
     /** The payload of every tick. */
-    readonly data: object
+    readonly data: BullmqJobData
     /** The options of every tick. */
     readonly opts: BullmqSchedulerJobOptions
 }
 
+/** A BullMQ driver whose infrastructure failures must use the application logger. */
+export interface BullmqErrorSource {
+    /** Subscribes before asynchronous driver errors can fall back to the driver's raw console. */
+    on(event: "error", listener: (cause: Error) => void): unknown
+}
+
 /** A queue as the transport uses it. */
-export interface BullmqQueue {
+export interface BullmqQueue extends BullmqErrorSource {
     /** Adds the job; an id BullMQ already holds makes the add a no-op. */
-    add(name: string, payload: object, options: BullmqJobOptions): Promise<unknown>
+    add(name: string, payload: BullmqJobData, options: BullmqJobOptions): Promise<unknown>
     /** Creates or updates the scheduler by its id. */
     upsertJobScheduler(id: string, repeat: { readonly every: number }, template: BullmqJobTemplate): Promise<unknown>
     /** Closes the queue. */
@@ -96,14 +102,23 @@ export interface BullmqQueue {
 export interface BullmqJob {
     /** The job id; a tick the scheduler fires can have none. */
     readonly id?: string
-    /** The payload the producer wrote. */
-    readonly data: object
+    /** Stored data is untrusted: queued jobs can also carry the raw payload written before envelopes. */
+    readonly data: unknown
     /** How many deliveries were started before this one. */
     readonly attemptsMade: number
 }
 
+/** The durable job data: an enqueued job propagates its id; a scheduler starts a new root per tick. */
+export type BullmqJobData = {
+    /** Distinguishes infrastructure envelopes from arbitrary raw payload fields. */
+    readonly schema: typeof BULLMQ_JOB_SCHEMA
+} & (
+    | { readonly kind: "enqueued"; readonly correlationId: string; readonly payload: object }
+    | { readonly kind: "scheduled"; readonly payload: object }
+)
+
 /** A worker as the transport uses it. */
-export interface BullmqWorker {
+export interface BullmqWorker extends BullmqErrorSource {
     /** Stops the worker; `force` drops the jobs it is still running. */
     close(force?: boolean): Promise<void>
 }

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

@@ -1,7 +1,7 @@
 import { Test } from "@nestjs/testing"
 import { mock } from "@starci/jest-preset"
-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 type { QueueHandler } from "./queue.contracts"
 import { QUEUE_OPTIONS, QUEUE_TRANSPORT } from "./queue.decorators"
 import { QueueLogEvent } from "./queue.log-events"
@@ -27,15 +27,18 @@ const build = async () => {
     const transport = mock<QueueTransport>()
     transport.upsertScheduler.mockResolvedValue(undefined)
     const logger = mock<Logger>()
+    const correlation = mock<CorrelationRunner>()
+    correlation.run.mockImplementation((_id, work) => work())
     const moduleRef = await Test.createTestingModule({
         providers: [
             QueueWorkerService,
             { provide: QUEUE_OPTIONS, useValue: options },
             { provide: QUEUE_TRANSPORT, useValue: transport },
             { provide: LOGGER, useValue: logger },
+            { provide: CORRELATION_RUNNER, useValue: correlation },
         ],
     }).compile()
-    return { workers: moduleRef.get(QueueWorkerService), transport, logger }
+    return { workers: moduleRef.get(QueueWorkerService), transport, logger, correlation }
 }
 
 describe("QueueWorkerService", () => {
@@ -49,22 +52,40 @@ describe("QueueWorkerService", () => {
 
             await workers.onApplicationBootstrap()
 
-            expect(transport.work).toHaveBeenCalledWith(mailHandler, 3)
-            expect(transport.work).toHaveBeenCalledWith(sweepHandler, 3)
+            expect(transport.work).toHaveBeenCalledWith(expect.objectContaining({ queue: "mail" }), 3)
+            expect(transport.work).toHaveBeenCalledWith(expect.objectContaining({ queue: "sweep" }), 3)
             expect(transport.upsertScheduler).toHaveBeenCalledWith(options.schedulers[0])
         })
 
         it("keeps the last handler registered for a queue", async () => {
             const { workers, transport } = await build()
-            const first = handlerOf("mail")
-            const second = handlerOf("mail")
+            const first = mock<QueueHandler>({ queue: "mail" })
+            const second = mock<QueueHandler>({ queue: "mail" })
+            second.handle.mockResolvedValue(undefined)
             workers.add(first)
             workers.add(second)
 
             await workers.onApplicationBootstrap()
 
             expect(transport.work).toHaveBeenCalledTimes(1)
-            expect(transport.work).toHaveBeenCalledWith(second, 3)
+            const delivery = { id: "job-1", queue: "mail", payload: {}, attempt: 1, correlationId: "request-1" }
+            await transport.work.mock.calls[0]?.[0].handle(delivery)
+            expect(second.handle).toHaveBeenCalledWith(delivery)
+            expect(first.handle).not.toHaveBeenCalled()
+        })
+
+        it("runs each delivery within its explicitly carried logging context", async () => {
+            const { workers, transport, correlation } = await build()
+            const handler = mock<QueueHandler>({ queue: "mail" })
+            handler.handle.mockResolvedValue(undefined)
+            workers.add(handler)
+            await workers.onApplicationBootstrap()
+            const delivery = { id: "job-1", queue: "mail", payload: {}, attempt: 2, correlationId: "request-1" }
+
+            await transport.work.mock.calls[0]?.[0].handle(delivery)
+
+            expect(correlation.run).toHaveBeenCalledWith("request-1", expect.any(Function))
+            expect(handler.handle).toHaveBeenCalledWith(delivery)
         })
 
         it("logs a scheduler that cannot be registered and still starts the app", async () => {

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

@@ -1,7 +1,7 @@
 import { Injectable } from "@nestjs/common"
 import type { OnApplicationBootstrap, OnApplicationShutdown } from "@nestjs/common"
-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 { QueueHandler } from "./queue.contracts"
 import { InjectQueueOptions, InjectQueueTransport } from "./queue.decorators"
@@ -22,11 +22,15 @@ export class QueueWorkerService implements QueueWorkerRegistry, OnApplicationBoo
         @InjectQueueOptions() private readonly options: QueueOptions,
         @InjectQueueTransport() private readonly transport: QueueTransport,
         @InjectLogger() private readonly logger: Logger,
+        @InjectCorrelationRunner() private readonly correlation: CorrelationRunner,
     ) {}
 
     /** Registers the handler under the queue it names; a second handler for the same queue replaces the first. */
     add(handler: QueueHandler): void {
-        this.handlers.set(handler.queue, handler)
+        this.handlers.set(handler.queue, {
+            queue: handler.queue,
+            handle: (delivery) => this.correlation.run(delivery.correlationId, () => handler.handle(delivery)),
+        })
     }
 
     /** Starts one worker per registered queue, then registers the schedulers of the options. */