@starci/hfs 4.7.32 → 4.7.34

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

@@ -1,3 +1,6 @@
+/** The owned wire protocol marker of current BullMQ job envelopes. */
+export const BULLMQ_JOB_SCHEMA = "starci/queue@1"
+
 /** A recurring task: BullMQ upserts it by `id`, so every replica of an app may register it and the deployment still fires it once per interval. */
 export interface QueueSchedulerDefinition {
     /** The queue the ticks go to; its processor handles every tick like any other job. */
@@ -12,6 +15,8 @@ export interface QueueSchedulerDefinition {
 
 /** One job as a handler receives it. */
 export interface QueueDelivery {
+    /** The upstream correlation id, carried explicitly across the queue. */
+    readonly correlationId: string
     /** The BullMQ job id: the outbox row id of an enqueued job, the tick id of a scheduled one. */
     readonly id: string
     /** The queue. */

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

@@ -5,3 +5,5 @@ export { InjectQueueOutbox, InjectQueueWorkerRegistry, QUEUE_OUTBOX, QUEUE_WORKE
 export { QueueModule } from "./queue.module"
 export type { QueueOutbox, QueueWorkerRegistry } from "./queue.port"
 export { queueEntities, queueMigrations } from "./persistence/connection"
+export { QUEUE_ERROR_KINDS } from "./errors/queue.error"
+export { QUEUE_MESSAGES } from "./messages/queue.messages"

package/templates/be/patterns/queues/platform/queue.log-events.ts.tpl

@@ -2,4 +2,8 @@
 export enum QueueLogEvent {
     /** A scheduler could not be registered at boot. */
     SchedulerFailed = "queue.scheduler.failed",
+    /** The producer's BullMQ driver reported an infrastructure error. */
+    QueueFailed = "queue.driver.failed",
+    /** A worker's BullMQ driver reported an infrastructure error. */
+    WorkerFailed = "queue.worker.failed",
 }

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

@@ -14,6 +14,7 @@ import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
 import type {
     BullmqConnection,
     BullmqJob,
+    BullmqJobData,
     BullmqQueue,
     BullmqWorker,
     BullmqWorkerOptions,
@@ -56,7 +57,7 @@ export class QueueModule extends ConfigurableModuleClass {
                             name: string,
                             processor: (job: BullmqJob) => Promise<void>,
                             options: BullmqWorkerOptions,
-                        ): BullmqWorker => new Worker<object>(name, processor, options),
+                        ): BullmqWorker => new Worker<BullmqJobData>(name, processor, options),
                     },
                 },
                 BullmqQueueTransportClient,

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

@@ -4,7 +4,7 @@ import type { QueueHandler } from "./queue.contracts"
 /** The queue outbox: a typed producer writes a job row in the transaction of the caller, the relay hands it to BullMQ after commit. */
 export interface QueueOutbox {
     /** Writes the job in the outbox of the transaction `tx`, so it exists exactly when the change that needs it commits. */
-    write(tx: EntityManager, queue: string, payload: object): Promise<void>
+    write(tx: EntityManager, queue: string, payload: object, correlationId: string): Promise<void>
 }
 
 /** Where a processor registers the handler of its queue; the workers start when the app has registered every handler. */

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

@@ -0,0 +1,417 @@
+import { Test } from "@nestjs/testing"
+import { fakeIds, mock } from "@starci/jest-preset"
+import { Secret } from "@modules/platform/config"
+import { LOGGER } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { IDS } from "@modules/platform/ids"
+import { QueueError, QueueErrorCode } from "./errors/queue.error"
+import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
+import { BULLMQ_JOB_SCHEMA } from "./queue.contracts"
+import type { QueueHandler } from "./queue.contracts"
+import { QUEUE_FACTORY, QUEUE_OPTIONS } from "./queue.decorators"
+import { QueueLogEvent } from "./queue.log-events"
+import type { QueueOptions } from "./queue.options"
+import { ATTEMPTS, BACKOFF_MS, KEEP_COMPLETED_SECONDS } from "./queue.policy"
+import type { BullmqCommands, BullmqJob, BullmqQueue, BullmqWorker, QueueFactory } from "./queue-transport.port"
+
+const MINTED_ID = "00000000-0000-4000-8000-000000000001"
+
+const options: QueueOptions = {
+    redisHost: "redis.test",
+    redisPort: 6380,
+    redisDb: 7,
+    prefix: "spec.",
+    relayIntervalMs: 100,
+    relayBatch: 50,
+    concurrency: 4,
+    connections: [],
+    schedulers: [],
+}
+
+const build = async (redisPassword?: Secret) => {
+    const commands = mock<BullmqCommands>()
+    const queue = mock<BullmqQueue>()
+    queue.getBackend.mockReturnValue({ client: Promise.resolve(commands) })
+    const worker = mock<BullmqWorker>()
+    const factory = mock<QueueFactory>()
+    const ids = fakeIds()
+    const logger = mock<Logger>()
+    factory.queue.mockReturnValue(queue)
+    factory.worker.mockReturnValue(worker)
+    const moduleRef = await Test.createTestingModule({
+        providers: [
+            BullmqQueueTransportClient,
+            { provide: QUEUE_OPTIONS, useValue: { ...options, redisPassword } },
+            { provide: QUEUE_FACTORY, useValue: factory },
+            { provide: IDS, useValue: ids },
+            { provide: LOGGER, useValue: logger },
+        ],
+    }).compile()
+    return { client: moduleRef.get(BullmqQueueTransportClient), queue, worker, factory, logger, ids, commands }
+}
+
+describe("BullmqQueueTransportClient connection", () => {
+    it("authenticates with the password of the declared Redis read from its sealed secret", async () => {
+        const { client, factory } = await build(new Secret("redis-secret"))
+
+        await client.add("orders", "outbox-1", {}, "request-1")
+
+        expect(factory.queue).toHaveBeenCalledWith("orders", {
+            prefix: "spec.",
+            connection: { host: "redis.test", port: 6380, db: 7, password: "redis-secret", maxRetriesPerRequest: null },
+        })
+    })
+})
+
+describe("BullmqQueueTransportClient jobs and schedulers", () => {
+    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, "request-1")
+        await client.add("orders", "outbox-2", payload, "request-2")
+
+        expect(factory.queue).toHaveBeenCalledTimes(1)
+        expect(factory.queue).toHaveBeenCalledWith("orders", {
+            prefix: "spec.",
+            connection: { host: "redis.test", port: 6380, db: 7, maxRetriesPerRequest: null },
+        })
+        expect(queue.add).toHaveBeenNthCalledWith(
+            1,
+            "orders",
+            { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload, correlationId: "request-1" },
+            {
+                jobId: "outbox-1",
+                attempts: ATTEMPTS,
+                backoff: { type: "exponential", delay: BACKOFF_MS },
+                removeOnComplete: { age: KEEP_COMPLETED_SECONDS },
+            },
+        )
+    })
+
+    it("keeps the job id of an outbox row whatever correlation id it carries", async () => {
+        const { client, queue } = await build()
+
+        await client.add("orders", "outbox-1", {}, "request-1")
+        await client.add("orders", "outbox-1", {}, "request-2")
+
+        expect(queue.add.mock.calls.map(([, , options]) => options.jobId)).toEqual(["outbox-1", "outbox-1"])
+    })
+
+    it("rejects unsafe correlation before writing a new job", async () => {
+        const { client, factory } = await build()
+
+        await expect(client.add("orders", "outbox-1", {}, "unsafe\nrequest")).rejects.toMatchObject({
+            code: QueueErrorCode.CorrelationInvalid,
+        })
+        expect(factory.queue).not.toHaveBeenCalled()
+    })
+
+    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: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: { shard: 2 } },
+                opts: { attempts: ATTEMPTS },
+            },
+        )
+        expect(queue.upsertJobScheduler).toHaveBeenNthCalledWith(
+            2,
+            "cleanup",
+            { every: 120_000 },
+            {
+                name: "billing",
+                data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {} },
+                opts: { attempts: ATTEMPTS },
+            },
+        )
+    })
+})
+
+describe("BullmqQueueTransportClient persistence", () => {
+    const jobs = [
+        { queue: "orders", jobId: "outbox-1" },
+        { queue: "orders", jobId: "outbox-2" },
+        { queue: "billing", jobId: "outbox-3" },
+    ]
+
+    it("waits once per queue for the append-only file, then finds every job still held", async () => {
+        const { client, queue, commands } = await build()
+        commands.call.mockResolvedValue([1, 0])
+        queue.getJobState.mockResolvedValue("waiting")
+
+        await expect(client.persist(jobs)).resolves.toBeUndefined()
+
+        expect(commands.call.mock.calls).toEqual([
+            ["WAITAOF", 1, 0, 5000],
+            ["WAITAOF", 1, 0, 5000],
+        ])
+        expect(queue.getJobState.mock.calls).toEqual([["outbox-1"], ["outbox-2"], ["outbox-3"]])
+    })
+
+    it.each([[[0, 0]], ["OK"]])(
+        "refuses when Redis does not report the jobs written to its append-only file (%j)",
+        async (reply) => {
+            const { client, queue, commands } = await build()
+            commands.call.mockResolvedValue(reply)
+
+            const refusal = client.persist(jobs)
+
+            await expect(refusal).rejects.toBeInstanceOf(QueueError)
+            await expect(refusal).rejects.toMatchObject({
+                code: QueueErrorCode.NotPersisted,
+                params: { queue: "orders" },
+            })
+            expect(queue.getJobState).not.toHaveBeenCalled()
+        },
+    )
+
+    it("refuses when the queue's connection cannot send the wait at all", async () => {
+        const { client, queue } = await build()
+        queue.getBackend.mockReturnValue({ client: Promise.resolve({}) })
+
+        await expect(client.persist(jobs)).rejects.toMatchObject({ code: QueueErrorCode.NotPersisted })
+        expect(queue.getJobState).not.toHaveBeenCalled()
+    })
+
+    it("refuses a job a restarted Redis no longer holds, although the wait answered on its new connection", async () => {
+        const { client, queue, commands } = await build()
+        commands.call.mockResolvedValue([1, 0])
+        queue.getJobState.mockImplementation((jobId) => Promise.resolve(jobId === "outbox-2" ? "unknown" : "waiting"))
+
+        const refusal = client.persist(jobs)
+
+        await expect(refusal).rejects.toBeInstanceOf(QueueError)
+        await expect(refusal).rejects.toMatchObject({
+            code: QueueErrorCode.JobLost,
+            params: { queue: "orders", jobId: "outbox-2" },
+        })
+    })
+})
+
+describe("BullmqQueueTransportClient worker deliveries", () => {
+    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, db: 7, maxRetriesPerRequest: null },
+            concurrency: 3,
+        })
+        const processor = factory.worker.mock.calls[0]?.[1]
+        await processor?.(
+            mock<BullmqJob>({
+                id: "job-1",
+                data: {
+                    schema: BULLMQ_JOB_SCHEMA,
+                    kind: "enqueued",
+                    payload: { orderId: "order-1" },
+                    correlationId: "request-1",
+                },
+                attemptsMade: 2,
+            }),
+        )
+        await processor?.({
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: { orderId: "order-2" } },
+            attemptsMade: 0,
+        } satisfies BullmqJob)
+        await processor?.({
+            id: "tick-3",
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {} },
+            attemptsMade: 1,
+        } satisfies BullmqJob)
+
+        expect(handler.handle).toHaveBeenNthCalledWith(1, {
+            id: "job-1",
+            correlationId: "request-1",
+            queue: "orders",
+            payload: { orderId: "order-1" },
+            attempt: 3,
+        })
+        expect(handler.handle).toHaveBeenNthCalledWith(2, {
+            id: "",
+            correlationId: MINTED_ID,
+            queue: "orders",
+            payload: { orderId: "order-2" },
+            attempt: 1,
+        })
+        expect(handler.handle).toHaveBeenNthCalledWith(3, {
+            id: "tick-3",
+            correlationId: "tick-3",
+            queue: "orders",
+            payload: {},
+            attempt: 2,
+        })
+    })
+})
+
+describe("BullmqQueueTransportClient stored job upgrades", () => {
+    it("preserves raw payloads and the same job correlation through legacy retries", async () => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+        const payload = { orderId: "before-upgrade", kind: "expire-order", payload: { reason: "unpaid" } }
+
+        await processor?.({ id: "legacy-job", data: payload, attemptsMade: 0 })
+        await processor?.({ id: "legacy-job", data: payload, attemptsMade: 1 })
+
+        expect(handler.handle).toHaveBeenNthCalledWith(1, {
+            id: "legacy-job",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-job",
+            attempt: 1,
+        })
+        expect(handler.handle).toHaveBeenNthCalledWith(2, {
+            id: "legacy-job",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-job",
+            attempt: 2,
+        })
+        expect(ids.issued).toEqual([])
+    })
+
+    it.each(["enqueued", "scheduled"])("keeps legacy business fields even when kind is %s", async (kind) => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+        const payload = {
+            schema: "order/business@1",
+            kind,
+            correlationId: "business\nkey",
+            payload: { orderId: "legacy-order" },
+        }
+
+        await processor?.({ id: "legacy-collision", data: payload, attemptsMade: 0 })
+
+        expect(handler.handle).toHaveBeenCalledWith({
+            id: "legacy-collision",
+            queue: "orders",
+            payload,
+            correlationId: "legacy-collision",
+            attempt: 1,
+        })
+        expect(ids.issued).toEqual([])
+    })
+})
+
+describe("BullmqQueueTransportClient correlation roots and marked envelopes", () => {
+    it("mints only when legacy data has no job id and accepts explicit scheduled correlation", async () => {
+        const { client, factory, ids } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+
+        await processor?.({ data: { orderId: "legacy-no-id" }, attemptsMade: 0 })
+        await processor?.({
+            data: { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {}, correlationId: "upstream-tick" },
+            attemptsMade: 0,
+        })
+
+        expect(handler.handle.mock.calls.map(([delivery]) => delivery.correlationId)).toEqual([
+            MINTED_ID,
+            "upstream-tick",
+        ])
+        expect(ids.issued).toEqual([MINTED_ID])
+    })
+
+    it.each<unknown>([
+        null,
+        { schema: "starci/queue@2", kind: "enqueued", payload: {}, correlationId: "request-1" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "unknown", payload: {} },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: {}, correlationId: undefined },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: null, correlationId: "request-1" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "enqueued", payload: {}, correlationId: "bad\nidentity" },
+        { schema: BULLMQ_JOB_SCHEMA, kind: "scheduled", payload: {}, correlationId: undefined },
+    ])("rejects malformed current data before business delivery (%j)", async (data) => {
+        const { client, factory } = await build()
+        const handler = mock<QueueHandler>({ queue: "orders" })
+        await client.work(handler, 3)
+        const processor = factory.worker.mock.calls[0]?.[1]
+
+        await expect(processor?.({ id: "stored-job", data, attemptsMade: 0 })).rejects.toMatchObject({
+            code: QueueErrorCode.MalformedMessage,
+        })
+        expect(handler.handle).not.toHaveBeenCalled()
+    })
+})
+
+describe("BullmqQueueTransportClient driver errors", () => {
+    it("routes queue driver errors through the logger once per queue", async () => {
+        const { client, queue, logger } = await build()
+        await client.add("orders", "outbox-1", {}, "request-1")
+        await client.add("orders", "outbox-2", {}, "request-2")
+        const cause = new Error("redis connection lost")
+
+        const listener = queue.on.mock.calls[0]?.[1]
+        listener?.(cause)
+
+        expect(queue.on).toHaveBeenCalledTimes(1)
+        expect(queue.on).toHaveBeenCalledWith("error", expect.any(Function))
+        expect(logger.error).toHaveBeenCalledWith(QueueLogEvent.QueueFailed, cause, { queue: "orders" })
+    })
+
+    it("routes worker driver errors through the logger", async () => {
+        const { client, worker, logger } = await build()
+        await client.work(mock<QueueHandler>({ queue: "orders" }), 3)
+        const cause = new Error("blocking redis connection lost")
+
+        const listener = worker.on.mock.calls[0]?.[1]
+        listener?.(cause)
+
+        expect(worker.on).toHaveBeenCalledWith("error", expect.any(Function))
+        expect(logger.error).toHaveBeenCalledWith(QueueLogEvent.WorkerFailed, cause, { queue: "orders" })
+    })
+})
+
+describe("BullmqQueueTransportClient wait and shutdown", () => {
+    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", {}, "request-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-lite/bullmq-queue-transport.client.ts.tpl

@@ -0,0 +1,172 @@
+import { Injectable } from "@nestjs/common"
+import { eachInOrder, 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 { QueueError, QueueErrorCode } from "./errors/queue.error"
+import { InjectQueueFactory, InjectQueueOptions } from "./queue.decorators"
+import { BULLMQ_JOB_SCHEMA } from "./queue.contracts"
+import type { QueueDelivery, QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+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 {
+    BullmqCommands,
+    BullmqConnection,
+    BullmqJob,
+    BullmqQueue,
+    BullmqWorker,
+    QueuedJob,
+    QueueFactory,
+    QueueTransport,
+} from "./queue-transport.port"
+
+/** How long the relay waits for Redis to write its jobs to the append-only file; `appendfsync everysec` writes within a second. */
+const PERSIST_TIMEOUT_MS = 5000
+
+/** A WAITAOF reply that counts the local append-only file among the writes it waited for. */
+const writtenLocally = (reply: unknown): boolean => Array.isArray(reply) && Number(reply.at(0)) >= 1
+
+/** True for a connection that sends a raw command. */
+const sendsCommands = (client: object): client is BullmqCommands =>
+    "call" in client && typeof client.call === "function"
+
+@Injectable()
+/** The QueueTransport port over the declared 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,
+        @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, 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 },
+            },
+        )
+    }
+
+    /**
+     * Waits until Redis has written each queue's jobs to its append-only file, then checks it still holds every job: a Redis that
+     * restarted meanwhile answers the wait at once on its new connection, and only a job it reloaded from the file is still there.
+     */
+    async persist(jobs: ReadonlyArray<QueuedJob>): Promise<void> {
+        await eachInOrder([...new Set(jobs.map((job) => job.queue))], async (queue) => {
+            const client = await this.queueOf(queue).getBackend().client
+            const written =
+                sendsCommands(client) && writtenLocally(await client.call("WAITAOF", 1, 0, PERSIST_TIMEOUT_MS))
+            if (!written) throw new QueueError({ code: QueueErrorCode.NotPersisted, params: { queue } })
+        })
+        await eachInOrder(jobs, async (job) => {
+            if ((await this.queueOf(job.queue).getJobState(job.jobId)) === "unknown")
+                throw new QueueError({ code: QueueErrorCode.JobLost, params: { queue: job.queue, jobId: job.jobId } })
+        })
+    }
+
+    /** 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: { 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> {
+        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()
+    }
+
+    /** 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()))
+    }
+
+    /** 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,
+            connection: {
+                host: this.options.redisHost,
+                port: this.options.redisPort,
+                db: this.options.redisDb,
+                ...(this.options.redisPassword === undefined ? {} : { password: this.options.redisPassword.reveal() }),
+                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())
+        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-lite/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, $4 correlation id); the relay hands it to BullMQ after the commit. */
+export const INSERT_QUEUE_ROW = sql`INSERT INTO public.queue (queue, payload, created_at, correlation_id)
+    VALUES ($1, $2::jsonb, $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, coalesce(correlation_id, id::text) AS "correlationId" FROM public.queue
+    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 public.queue SET sent_at = $2 WHERE id = ANY($1::uuid[])`