@starci/hfs 4.7.31 → 4.7.33

package/templates/be/patterns/queues/platform-lite/queue-outbox.sql.tpl

@@ -0,0 +1,32 @@
+-- The outbox of the queues: a producer's business transaction writes one row here, so the job exists exactly when
+-- the change commits; the relay hands each unsent row to BullMQ on the declared Redis with the row id as the job id
+-- and the correlation id of the request that wrote it.
+create table public.queue (
+    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,
+    correlation_id varchar(128) not null
+);
+
+create index queue_unsent_idx on public.queue (created_at, id) where sent_at is null;
+
+alter table public.queue enable row level security;
+alter table public.queue force row level security;
+
+create policy queue_app_be_select
+on public.queue for select to app_be
+using (queue is not null);
+
+create policy queue_app_be_insert
+on public.queue for insert to app_be
+with check (queue is not null);
+
+create policy queue_app_be_update
+on public.queue for update to app_be
+using (queue is not null)
+with check (queue is not null);
+
+revoke all on table public.queue from public, anon, authenticated;
+grant select, insert, update on table public.queue to app_be;

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

@@ -0,0 +1,148 @@
+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,
+    redisDb: 0,
+    prefix: "test",
+    relayIntervalMs: 100,
+    relayBatch: 2,
+    concurrency: 1,
+    connections: [],
+    schedulers: [],
+}
+
+const row = (id: string) => ({ id, queue: "mail", payload: { id: `m-${id}` }, correlationId: `request-${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 relay", () => {
+    it("adds the waiting rows to BullMQ with the row id as the job id and marks them sent once Redis has persisted them", 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(transport.persist).toHaveBeenCalledWith([
+            { queue: "mail", jobId: "1" },
+            { queue: "mail", jobId: "2" },
+        ])
+        expect(transport.persist.mock.invocationCallOrder[0]).toBeGreaterThan(
+            transport.add.mock.invocationCallOrder[1] ?? 0,
+        )
+        expect(tx.em.query).toHaveBeenNthCalledWith(2, MARK_ROWS_SENT, [["1", "2"], new Date(AT)])
+        expect(tx.commits).toBe(1)
+    })
+
+    it("leaves the rows waiting when Redis has not persisted their jobs, 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 lost = new Error("job lost in a Redis restart")
+        transport.persist.mockRejectedValue(lost)
+
+        await expect(relay.relay()).rejects.toBe(lost)
+
+        expect(transport.add).toHaveBeenCalledWith("mail", "1", { id: "m-1" }, "request-1")
+        expect(tx.rollbacks).toBe(1)
+        expect(tx.em.query).toHaveBeenCalledTimes(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(transport.persist).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("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-lite/queue-relay.service.ts.tpl

@@ -0,0 +1,51 @@
+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 { eachInOrder } from "@modules/platform/primitives"
+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, waits until Redis has written
+ * those jobs to its append-only file, and only then marks the rows sent in the same transaction (the loop is `OutboxRelayPolicy`'s).
+ * A job Redis loses before that write leaves its row waiting, so the next pass adds it again; a crash between the add and the mark
+ * does the same, 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> {
+        await eachInOrder(rows, (row) => this.transport.add(row.queue, row.id, row.payload, row.correlationId))
+        await this.transport.persist(rows.map((row) => ({ queue: row.queue, jobId: row.id })))
+    }
+
+    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)
+    }
+}

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

@@ -0,0 +1,163 @@
+import type { BULLMQ_JOB_SCHEMA, QueueHandler, QueueSchedulerDefinition } from "./queue.contracts"
+
+/** A job the relay added: its queue and its id, the outbox row id. */
+export interface QueuedJob {
+    /** The queue the job was added to. */
+    readonly queue: string
+    /** The job id, which is the outbox row id. */
+    readonly jobId: string
+}
+
+/** 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, correlationId: string): Promise<void>
+    /**
+     * Resolves once Redis has written the jobs to its append-only file and still holds each of them; it throws otherwise, so the
+     * relay marks an outbox row sent only when its job survives a Redis crash.
+     */
+    persist(jobs: ReadonlyArray<QueuedJob>): 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. */
+    work(handler: QueueHandler, concurrency: number): Promise<void>
+    /** Resolves after `ms` milliseconds: the only clock of the relay loop. */
+    wait(ms: number): Promise<void>
+    /** Closes every queue and worker. */
+    close(): Promise<void>
+}
+
+/** The Redis a driver object connects to. */
+export interface BullmqRedis {
+    /** The host. */
+    readonly host: string
+    /** The port. */
+    readonly port: number
+    /** The Redis database that holds this app's queue state. */
+    readonly db: number
+    /** The password of the declared Redis; absent for a local Redis without auth. */
+    readonly password?: string
+    /** BullMQ answers to commands only through a client that does not retry on its own. */
+    readonly maxRetriesPerRequest: number | null
+}
+
+/** The Redis options every queue and worker of the app shares. */
+export interface BullmqConnection {
+    /** The key prefix of the app. */
+    readonly prefix: string
+    /** The Redis the driver connects to. */
+    readonly connection: BullmqRedis
+}
+
+/** The options a worker is built with: the shared connection plus its concurrency. */
+export interface BullmqWorkerOptions extends BullmqConnection {
+    /** How many jobs the worker runs at a time. */
+    readonly concurrency: number
+}
+
+/** The wait between two tries of a job. */
+export interface BullmqBackoff {
+    /** The backoff shape. */
+    readonly type: string
+    /** The first wait, in milliseconds. */
+    readonly delay: number
+}
+
+/** How long a finished job is kept. */
+export interface BullmqRetention {
+    /** The seconds a finished job is kept. */
+    readonly age: number
+}
+
+/** The options the transport fixes on every job it adds. */
+export interface BullmqJobOptions {
+    /** The id BullMQ dedupes on: the outbox row id. */
+    readonly jobId: string
+    /** How many times BullMQ tries the job. */
+    readonly attempts: number
+    /** The wait between two tries. */
+    readonly backoff: BullmqBackoff
+    /** How long a finished job is kept. */
+    readonly removeOnComplete: BullmqRetention
+}
+
+/** The options a scheduler fixes on the jobs it fires. */
+export interface BullmqSchedulerJobOptions {
+    /** How many times BullMQ tries the tick. */
+    readonly attempts: number
+}
+
+/** The job a scheduler fires. */
+export interface BullmqJobTemplate {
+    /** The job name, which is the queue name. */
+    readonly name: string
+    /** The payload of every tick. */
+    readonly data: BullmqJobData
+    /** The options of every tick. */
+    readonly opts: BullmqSchedulerJobOptions
+}
+
+/** A Redis connection that sends a raw command: BullMQ's ioredis client forwards `call` to ioredis. */
+export interface BullmqCommands {
+    /** Sends one command with its arguments and answers its reply. */
+    call(command: string, ...args: Array<string | number>): Promise<unknown>
+}
+
+/** The Redis backend of a queue: it owns the connection the queue adds its jobs through. */
+export interface BullmqBackend {
+    /** The connection the queue adds its jobs through; BullMQ types it without its raw `call`. */
+    readonly client: Promise<object>
+}
+
+/** 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 extends BullmqErrorSource {
+    /** The Redis backend of the queue. */
+    getBackend(): BullmqBackend
+    /** Adds the job; an id BullMQ already holds makes the add a no-op. */
+    add(name: string, payload: BullmqJobData, options: BullmqJobOptions): Promise<unknown>
+    /** The state of the job, `unknown` when Redis does not hold it. */
+    getJobState(jobId: string): Promise<string>
+    /** Creates or updates the scheduler by its id. */
+    upsertJobScheduler(id: string, repeat: { readonly every: number }, template: BullmqJobTemplate): Promise<unknown>
+    /** Closes the queue. */
+    close(): Promise<void>
+}
+
+/** A job as a worker receives it: the fields the transport translates into a QueueDelivery. */
+export interface BullmqJob {
+    /** The job id; a tick the scheduler fires can have none. */
+    readonly id?: string
+    /** 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 extends BullmqErrorSource {
+    /** Stops the worker; `force` drops the jobs it is still running. */
+    close(force?: boolean): Promise<void>
+}
+
+/** Builds the BullMQ objects; the module provides it so a spec can double it through the injection token. */
+export interface QueueFactory {
+    /** The queue of the name over the shared connection. */
+    queue(name: string, options: BullmqConnection): BullmqQueue
+    /** A worker that runs the processor for every job of the queue. */
+    worker(name: string, processor: (job: BullmqJob) => Promise<void>, options: BullmqWorkerOptions): BullmqWorker
+}

package/templates/be/patterns/queues/platform-lite/queue.config.ts.tpl

@@ -0,0 +1,17 @@
+import type { EnvSource } from "@modules/platform/config"
+import type { QueueOptions } from "./queue.options"
+
+/** What the app's `main.ts` reads for the queues; the connections and the schedulers are the app root's choice. */
+export type QueueConfig = Omit<QueueOptions, "connections" | "schedulers" | "outboxOnly">
+
+/** Reads the queue options: the address of the declared Redis is required, its password comes from a mounted secret, the rest are tunables with literal defaults. */
+export const parseQueueConfig = (env: EnvSource): QueueConfig => ({
+    redisHost: env.string("QUEUE_REDIS_HOST"),
+    redisPort: env.int("QUEUE_REDIS_PORT", 6379),
+    redisDb: env.int("QUEUE_REDIS_DB", 0),
+    ...(env.has("QUEUE_REDIS_PASSWORD") ? { redisPassword: env.secret("QUEUE_REDIS_PASSWORD") } : {}),
+    prefix: env.optional("QUEUE_PREFIX") ?? "queue",
+    relayIntervalMs: env.duration("QUEUE_RELAY_INTERVAL", 200),
+    relayBatch: env.int("QUEUE_RELAY_BATCH", 50),
+    concurrency: env.int("QUEUE_CONCURRENCY", 5),
+})

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

@@ -0,0 +1,25 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the queue capability. */
+export enum QueueErrorCode {
+    /** Redis did not write the jobs the relay added to its append-only file in time, so their outbox rows stay waiting. */
+    NotPersisted = "QUEUE_NOT_PERSISTED",
+    /** Redis no longer holds a job the relay added: it restarted before the job reached its append-only file. */
+    JobLost = "QUEUE_JOB_LOST",
+    /** 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.NotPersisted]: "unavailable",
+    [QueueErrorCode.JobLost]: "unavailable",
+    [QueueErrorCode.MalformedMessage]: "internal",
+    [QueueErrorCode.CorrelationInvalid]: "invalid",
+}
+
+/** The one error class of the queue capability. */
+export class QueueError extends DomainError<QueueErrorCode> {}

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

@@ -0,0 +1,8 @@
+export { QUEUE_ERROR_KINDS } from "./errors/queue.error"
+export { QUEUE_MESSAGES } from "./messages/queue.messages"
+export { parseQueueConfig } from "./queue.config"
+export type { QueueConfig } from "./queue.config"
+export type { QueueDelivery, QueueSchedulerDefinition } from "./queue.contracts"
+export { InjectQueueOutbox, InjectQueueWorkerRegistry, QUEUE_OUTBOX, QUEUE_WORKER_REGISTRY } from "./queue.decorators"
+export { QueueModule } from "./queue.module"
+export type { QueueOutbox, QueueWorkerRegistry } from "./queue.port"

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

@@ -0,0 +1,21 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the queue codes, Vietnamese and English. */
+export const QUEUE_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.QUEUE_NOT_PERSISTED":
+            "Redis chưa ghi các tác vụ vào tệp append-only kịp thời; các dòng outbox vẫn chờ gửi lại.",
+        "errors.QUEUE_JOB_LOST":
+            "Redis không còn giữ một tác vụ vừa thêm vì đã khởi động lại; dòng outbox của nó sẽ được gửi lại.",
+        "errors.QUEUE_MALFORMED_MESSAGE": "Thông điệp hàng đợi đã lưu không hợp lệ.",
+        "errors.QUEUE_CORRELATION_INVALID": "Mã tương quan của thông điệp hàng đợi không hợp lệ.",
+    },
+    en: {
+        "errors.QUEUE_NOT_PERSISTED":
+            "Redis did not write the queued jobs to its append-only file in time; their outbox rows stay waiting.",
+        "errors.QUEUE_JOB_LOST":
+            "Redis no longer holds a job it was handed because it restarted; its outbox row is relayed again.",
+        "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-lite/queue.module.ts.tpl

@@ -0,0 +1,74 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { Queue, Worker } from "bullmq"
+import type { EntityManager } from "typeorm"
+import {
+    QUEUE_FACTORY,
+    QUEUE_OUTBOX,
+    QUEUE_RELAY_MANAGERS,
+    QUEUE_TRANSPORT,
+    QUEUE_WORKER_REGISTRY,
+} from "./queue.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./queue.module-definition"
+import { BullmqQueueTransportClient } from "./bullmq-queue-transport.client"
+import type {
+    BullmqConnection,
+    BullmqJob,
+    BullmqJobData,
+    BullmqQueue,
+    BullmqWorker,
+    BullmqWorkerOptions,
+} from "./queue-transport.port"
+import { QueueOutboxService } from "./queue-outbox.service"
+import { QueueRelayService } from "./queue-relay.service"
+import { QueueWorkerService } from "./queue-worker.service"
+
+@Module({})
+/** The queues of a service: the outbox writer, its relay into BullMQ, the workers and the schedulers, registered once per app over the connections that hold an outbox. */
+export class QueueModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that enqueues or processes jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        const writerProviders = [
+            ...(base.providers ?? []),
+            QueueOutboxService,
+            { provide: QUEUE_OUTBOX, useExisting: QueueOutboxService },
+        ]
+        if (options.outboxOnly === true) {
+            return {
+                ...base,
+                providers: writerProviders,
+                exports: [QUEUE_OUTBOX],
+            }
+        }
+        return {
+            ...base,
+            providers: [
+                ...writerProviders,
+                {
+                    provide: QUEUE_RELAY_MANAGERS,
+                    useFactory: (...managers: Array<EntityManager>) => managers,
+                    inject: [...options.connections],
+                },
+                {
+                    provide: QUEUE_FACTORY,
+                    useValue: {
+                        queue: (name: string, options: BullmqConnection): BullmqQueue =>
+                            new Queue<object>(name, options),
+                        worker: (
+                            name: string,
+                            processor: (job: BullmqJob) => Promise<void>,
+                            options: BullmqWorkerOptions,
+                        ): BullmqWorker => new Worker<BullmqJobData>(name, processor, options),
+                    },
+                },
+                BullmqQueueTransportClient,
+                { provide: QUEUE_TRANSPORT, useExisting: BullmqQueueTransportClient },
+                QueueRelayService,
+                QueueWorkerService,
+                { provide: QUEUE_WORKER_REGISTRY, useExisting: QueueWorkerService },
+            ],
+            exports: [QUEUE_OUTBOX, QUEUE_WORKER_REGISTRY, QUEUE_TRANSPORT],
+        }
+    }
+}

package/templates/be/patterns/queues/platform-lite/queue.options.ts.tpl

@@ -0,0 +1,38 @@
+import type { InjectionToken } from "@nestjs/common"
+import type { Secret } from "@modules/platform/config"
+import type { QueueSchedulerDefinition } from "./queue.contracts"
+
+/** What the queues of one app need: where the declared Redis is, how the relay and the workers run, which connections hold an outbox, and the schedulers it registers. */
+export interface QueueOptions {
+    /** The runtime registration owns the relay, workers and schedulers. */
+    readonly outboxOnly?: false
+    /** The Redis host BullMQ talks to. */
+    readonly redisHost: string
+    /** The Redis port. */
+    readonly redisPort: number
+    /** The Redis database that holds this app's queue state. */
+    readonly redisDb: number
+    /** The Redis password from its sealed secret file; absent for a local Redis without auth. */
+    readonly redisPassword?: Secret
+    /** What every BullMQ key starts with: the shared default in a deployment, the run prefix of a test world. */
+    readonly prefix: string
+    /** The pause between two relay passes over an empty outbox. */
+    readonly relayIntervalMs: number
+    /** The most outbox rows one relay pass hands to BullMQ. */
+    readonly relayBatch: number
+    /** How many jobs one worker of the app runs at once. */
+    readonly concurrency: number
+    /** The tokens of the shared entity managers of the connections that hold a queue outbox of the app: the relay reads each of them. */
+    readonly connections: ReadonlyArray<InjectionToken>
+    /** The job schedulers the app registers at boot; BullMQ upserts them by id, so a pool of replicas fires each one once per interval. */
+    readonly schedulers: ReadonlyArray<QueueSchedulerDefinition>
+}
+
+/** A one-off producer writes an outbox row and exits; the running app owns delivery. */
+export interface QueueOutboxOnlyOptions {
+    /** Registers only the transactional outbox writer, leaving delivery to the running app. */
+    readonly outboxOnly: true
+}
+
+/** Registers either the running queue capability or only its transactional writer. */
+export type QueueRegistrationOptions = QueueOptions | QueueOutboxOnlyOptions

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

@@ -17,7 +17,7 @@ export class @@Queue@@Queue {
     constructor(@InjectQueueOutbox() private readonly outbox: QueueOutbox) {}
 
     /** Enqueues one @@queue@@ job in the transaction of the caller: the job exists exactly when the change that needs it commits. */
-    enqueue@@Queue@@(payload: @@Queue@@Payload, tx: EntityManager): Promise<void> {
-        return this.outbox.write(tx, @@queueUpper@@_QUEUE, payload)
+    enqueue@@Queue@@(payload: @@Queue@@Payload, tx: EntityManager, correlationId: string): Promise<void> {
+        return this.outbox.write(tx, @@queueUpper@@_QUEUE, payload, correlationId)
     }
 }

package/templates/be/patterns/reactors/application.contracts.ts.tpl

@@ -2,6 +2,8 @@ import type { @@Event@@Event } from "@modules/events/@@from@@"
 
 /** What applying one delivered @@event@@ event takes. */
 export interface @@Action@@Request {
+    /** The originating request identity retained by the delivery envelope. */
+    readonly correlationId: string
     /** The id of the delivered event; the domain service claims it in the inbox inside its own transaction. */
     readonly eventId: string
     /** The delivered event. */

package/templates/be/patterns/reactors/consumer.ts.tpl

@@ -14,6 +14,10 @@ export class @@Event@@Consumer implements EventConsumer<@@Event@@Event> {
 
     /** Delivery is at least once: the domain service the command reaches claims `eventId` in the inbox inside its own transaction. */
     async handle(delivery: EventDelivery<@@Event@@Event>): Promise<void> {
-        await this.commandBus.execute(new @@Action@@Command({ request: { eventId: delivery.eventId, event: delivery.event } }))
+        await this.commandBus.execute(
+            new @@Action@@Command({
+                request: { eventId: delivery.eventId, event: delivery.event, correlationId: delivery.correlationId },
+            }),
+        )
     }
 }

package/templates/be/platform/graphql/graphql.contracts.ts

@@ -1,9 +1,10 @@
 import type { Request, Response } from "express"
+import type { CorrelationRequest } from "@modules/platform/logging"
 
 /** The GraphQL context every operation runs with: the HTTP request it arrived on and its response. */
 export interface GraphqlContext {
     /** The HTTP request: the guards read its headers and the principal they establish on it. */
-    readonly req: Request
+    readonly req: Request & CorrelationRequest
     /** The HTTP response. */
     readonly res: Response
 }

package/templates/be/platform/graphql/localize-errors.mapper.spec.ts

@@ -15,7 +15,7 @@ const requestContext = (
     headers: Request["headers"],
 ): GraphQLRequestContextWillSendResponse<GraphqlContext> =>
     mock<GraphQLRequestContextWillSendResponse<GraphqlContext>>({
-        contextValue: { req: mock<Request>({ headers }), res: mock<GraphqlContext["res"]>() },
+        contextValue: { req: mock<GraphqlContext["req"]>({ headers, correlationId: "request-1" }), res: mock<GraphqlContext["res"]>() },
         response,
     })