@starci/hfs 4.0.7 → 4.0.9

package/templates/be/patterns/jobs/platform/jobs.contracts.ts.tpl

@@ -0,0 +1,62 @@
+/** A job a worker claimed: the token it must pass to every write. */
+export interface ClaimedJob {
+    /** The id of the job row. */
+    readonly jobId: string
+    /** The kind of the job: the queue its processor consumes. */
+    readonly kind: string
+    /** The fencing token of this claim; the claim bumped it, so an older worker holds a smaller one. */
+    readonly fencingToken: number
+    /** The last step a worker recorded, or null before the first. */
+    readonly currentStep: string | null
+    /** The payload the producer wrote. */
+    readonly payload: object
+}
+
+/** What a worker asks for when it claims a delivery. */
+export interface ClaimParams {
+    /** The kind of the job. */
+    readonly kind: string
+    /** The key of the delivery: the BullMQ job id. A second claim of the same key bumps the token of the same row. */
+    readonly jobKey: string
+    /** The payload to store on the first claim. */
+    readonly payload: object
+    /** The name of the claiming worker. */
+    readonly workerId: string
+    /** How long the claim lasts. */
+    readonly leaseMs: number
+}
+
+/** The target of one guarded write: the job and the token the writer holds. Required in the type, never optional. */
+export interface GuardedWrite {
+    /** The id of the job row. */
+    readonly jobId: string
+    /** The token the writer received from its claim. */
+    readonly expectedFencingToken: number
+}
+
+/** A guarded write that records a step. */
+export interface AdvanceWrite extends GuardedWrite {
+    /** The step that finished. */
+    readonly step: string
+}
+
+/** A guarded write that fails the job. */
+export interface FailWrite extends GuardedWrite {
+    /** Why the job failed. */
+    readonly reason: string
+}
+
+/** The idempotency key of an external effect: only `JobClaims.runKey` makes one. */
+export type RunKey = string & {
+    /** The brand that keeps a plain string from passing as a run key; it never exists at run time. */
+    readonly __runKey: unique symbol
+}
+
+/** The shape of a run key: `<jobId>:<step>:<fencingToken>`. */
+const RUN_KEY = /^[^:]+:[^:]+:\d+$/u
+
+/** True when the text has the shape of a run key; the one place a string becomes a `RunKey`. */
+export const isRunKey = (text: string): text is RunKey => RUN_KEY.test(text)
+
+/** What a claim answers: the claimed job, or null when the job is done or another worker holds a live claim. */
+export type ClaimResult = ClaimedJob | null

package/templates/be/patterns/jobs/platform/jobs.decorators.ts.tpl

@@ -0,0 +1,31 @@
+import type { EntityManager } from "typeorm"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { JobsOptions } from "./jobs.options"
+import type { JobClaims, JobProcessorRegistry } from "./jobs.port"
+
+/** Token of the options of the jobs, exported so a spec can provide it. */
+export const JOBS_OPTIONS: unique symbol = Symbol("platform.jobs.options")
+
+/** Token of the JobClaims port. */
+export const JOB_CLAIMS: unique symbol = Symbol("platform.jobs.claims")
+
+/** Token of the registry a job module registers its processor with. */
+export const JOB_PROCESSOR_REGISTRY: unique symbol = Symbol("platform.jobs.processor-registry")
+
+/** Token of the entity managers of the connections that hold the job table, in the order the options name them. */
+export const JOBS_MANAGERS: unique symbol = Symbol("platform.jobs.managers")
+
+/** Injects the options of the jobs. Parameter type: JobsOptions. */
+export const InjectJobsOptions = (): TypedParameterDecorator<JobsOptions> => injector<JobsOptions>(JOBS_OPTIONS)
+
+/** Injects the JobClaims port. Parameter type: JobClaims. */
+export const InjectJobClaims = (): TypedParameterDecorator<JobClaims> => injector<JobClaims>(JOB_CLAIMS)
+
+/** Injects the processor registry. Parameter type: JobProcessorRegistry. */
+export const InjectJobProcessorRegistry = (): TypedParameterDecorator<JobProcessorRegistry> =>
+    injector<JobProcessorRegistry>(JOB_PROCESSOR_REGISTRY)
+
+/** Injects the entity managers of the connections that hold the job table. Parameter type: ReadonlyArray<EntityManager>. */
+export const InjectJobsManagers = (): TypedParameterDecorator<ReadonlyArray<EntityManager>> =>
+    injector<ReadonlyArray<EntityManager>>(JOBS_MANAGERS)

package/templates/be/patterns/jobs/platform/jobs.error.ts.tpl

@@ -0,0 +1,22 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the jobs capability. */
+export enum JobsErrorCode {
+    /** A write carried a fencing token that is no longer the job's: a newer worker owns it. */
+    FencedOut = "JOBS_FENCED_OUT",
+    /** A run key could not be made: the job id or the step name carries a separator. */
+    RunKeyInvalid = "JOBS_RUN_KEY_INVALID",
+    /** The jobs capability was registered with no connection to hold the job table. */
+    ConnectionMissing = "JOBS_CONNECTION_MISSING",
+}
+
+/** How each jobs code travels. */
+export const JOBS_ERROR_KINDS: Record<JobsErrorCode, ErrorKind> = {
+    [JobsErrorCode.FencedOut]: "conflict",
+    [JobsErrorCode.RunKeyInvalid]: "internal",
+    [JobsErrorCode.ConnectionMissing]: "internal",
+}
+
+/** The one error class of the jobs capability. */
+export class JobsError extends DomainError<JobsErrorCode> {}

package/templates/be/patterns/jobs/platform/jobs.index.ts.tpl

@@ -0,0 +1,11 @@
+export { JOBS_ERROR_KINDS } from "./errors/jobs.error"
+export { parseJobsConfig } from "./jobs.config"
+export type { JobsConfig } from "./jobs.config"
+export { isRunKey } from "./jobs.contracts"
+export type { ClaimedJob, RunKey } from "./jobs.contracts"
+export { InjectJobClaims, InjectJobProcessorRegistry } from "./jobs.decorators"
+export { JobsModule } from "./jobs.module"
+export type { JobClaims, JobProcessorRegistry, JobStep } from "./jobs.port"
+export { FencedProcessor } from "./fenced.processor"
+export { JOBS_MESSAGES } from "./messages/jobs.messages"
+export { jobsEntities, jobsMigrations } from "./persistence/connection"

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

@@ -0,0 +1,9 @@
+/** Log events of the jobs. */
+export enum JobsLogEvent {
+    /** A write of a stale worker was refused: a newer worker owns the job and this one stopped with no further effect. */
+    FencedOut = "jobs.fenced-out",
+    /** A delivery failed and the job was marked failed for BullMQ to retry. */
+    DeliveryFailed = "jobs.delivery.failed",
+    /** A failed delivery could not even be recorded as failed; the lease will expire and the job will be claimed again. */
+    FailureNotRecorded = "jobs.delivery.failure-not-recorded",
+}

package/templates/be/patterns/jobs/platform/jobs.messages.ts.tpl

@@ -0,0 +1,15 @@
+import type { MessageBundle } from "@modules/platform/i18n"
+
+/** Display text of the jobs codes, Vietnamese and English. */
+export const JOBS_MESSAGES: MessageBundle = {
+    vi: {
+        "errors.JOBS_FENCED_OUT": "Tác vụ {{jobId}} đã được worker khác tiếp nhận; worker này dừng lại.",
+        "errors.JOBS_RUN_KEY_INVALID": "Không tạo được khóa chạy cho tác vụ {{jobId}} ở bước {{step}}.",
+        "errors.JOBS_CONNECTION_MISSING": "Năng lực tác vụ chưa được khai báo kết nối cơ sở dữ liệu.",
+    },
+    en: {
+        "errors.JOBS_FENCED_OUT": "Job {{jobId}} is owned by a newer worker; this worker stops.",
+        "errors.JOBS_RUN_KEY_INVALID": "No run key can be made for job {{jobId}} at step {{step}}.",
+        "errors.JOBS_CONNECTION_MISSING": "The jobs capability was registered with no database connection.",
+    },
+}

package/templates/be/patterns/jobs/platform/jobs.module-definition.ts.tpl

@@ -0,0 +1,10 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import { JOBS_OPTIONS } from "./jobs.decorators"
+import type { JobsOptions } from "./jobs.options"
+
+/** The configurable-module base of the jobs; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<JobsOptions>({
+    optionsInjectionToken: JOBS_OPTIONS,
+})
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/patterns/jobs/platform/jobs.module.ts.tpl

@@ -0,0 +1,32 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { JOB_CLAIMS, JOB_PROCESSOR_REGISTRY, JOBS_MANAGERS } from "./jobs.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./jobs.module-definition"
+import { JobClaimService } from "./job-claim.service"
+import { JobRunnerService } from "./job-runner.service"
+
+@Module({})
+/** The fenced jobs of a service: the claim service that owns the job row and the runner that subscribes processors to their queues. Needs the queue capability registered in the same app. */
+export class JobsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app that runs jobs. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [
+                ...(base.providers ?? []),
+                {
+                    provide: JOBS_MANAGERS,
+                    useFactory: (manager: EntityManager) => [manager],
+                    inject: [options.connection],
+                },
+                JobClaimService,
+                JobRunnerService,
+                { provide: JOB_CLAIMS, useExisting: JobClaimService },
+                { provide: JOB_PROCESSOR_REGISTRY, useExisting: JobRunnerService },
+            ],
+            exports: [JOB_CLAIMS, JOB_PROCESSOR_REGISTRY],
+        }
+    }
+}

package/templates/be/patterns/jobs/platform/jobs.options.ts.tpl

@@ -0,0 +1,11 @@
+import type { InjectionToken } from "@nestjs/common"
+
+/** What the jobs of one app need: the connection that holds the job table, who this worker is, and how long a claim lasts. */
+export interface JobsOptions {
+    /** The token of the shared entity manager of the connection that holds the job table of the app. */
+    readonly connection: InjectionToken
+    /** The name this worker writes into `claimed_by`; it tells operators who held a job, the fence never reads it. */
+    readonly workerId: string
+    /** How long a claim lasts: after it a stalled job may be claimed again, and the old worker is fenced out. */
+    readonly leaseMs: number
+}

package/templates/be/patterns/jobs/platform/jobs.port.ts.tpl

@@ -0,0 +1,36 @@
+import type {
+    AdvanceWrite,
+    ClaimedJob,
+    ClaimParams,
+    ClaimResult,
+    FailWrite,
+    GuardedWrite,
+    RunKey,
+} from "./jobs.contracts"
+import type { FencedProcessor } from "./fenced.processor"
+
+/** The one door to the job row; `platform/jobs` implements it and nothing else writes the table. */
+export interface JobClaims {
+    /** Claims the delivery in one atomic statement and bumps the fencing token; null when the job is done or another worker holds a live claim. */
+    claim(params: ClaimParams): Promise<ClaimResult>
+    /** Records a finished step; throws `JobFencedOut` when the token is stale. */
+    advance(write: AdvanceWrite): Promise<void>
+    /** Completes the job; throws `JobFencedOut` when the token is stale. */
+    complete(write: GuardedWrite): Promise<void>
+    /** Fails the job so BullMQ can retry it; throws `JobFencedOut` when the token is stale. */
+    fail(write: FailWrite): Promise<void>
+    /** The idempotency key of one step of this claim: `<jobId>:<step>:<fencingToken>`. */
+    runKey(job: ClaimedJob, step: string): RunKey
+}
+
+/** One external effect of a job. */
+export interface JobStep {
+    /** Performs the effect of the step for the claimed job. */
+    run(job: ClaimedJob): Promise<void>
+}
+
+/** Where a job module registers its processor. */
+export interface JobProcessorRegistry {
+    /** Subscribes the processor to its queue. */
+    add(processor: FencedProcessor): void
+}

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

@@ -0,0 +1,8 @@
+import { JobEntity } from "./entities/job.entity"
+import { CreateJobs@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-jobs"
+
+/** The entities of the jobs, for every connection that runs jobs. */
+export const jobsEntities = [JobEntity]
+
+/** The migrations of the jobs, in the order they run. */
+export const jobsMigrations = [CreateJobs@@epochMs13@@]

package/templates/be/patterns/jobs/platform/persistence.job.entity.ts.tpl

@@ -0,0 +1,53 @@
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm"
+
+@Entity("jobs")
+/** One background job: its fencing token is bumped by the claim only, and every other write carries the token it holds. */
+export class JobEntity {
+    /** The id of the job. */
+    @PrimaryGeneratedColumn("uuid", { name: "id" })
+    id!: string
+
+    /** The kind of the job: the queue its processor consumes. */
+    @Column({ name: "kind", type: "varchar", length: 200 })
+    kind!: string
+
+    /** The key of the delivery (the BullMQ job id); unique, so a repeated delivery meets the same row. */
+    @Column({ name: "job_key", type: "varchar", length: 200, unique: true })
+    jobKey!: string
+
+    /** The state of the job: running, failed or done. */
+    @Column({ name: "status", type: "varchar", length: 16 })
+    status!: "running" | "failed" | "done"
+
+    /** The last step a worker recorded. */
+    @Column({ name: "current_step", type: "varchar", length: 200, nullable: true })
+    currentStep!: string | null
+
+    /** The fencing token: it only grows, one per claim. */
+    @Column({ name: "fencing_token", type: "bigint" })
+    fencingToken!: string
+
+    /** The worker that holds the claim, for operators. */
+    @Column({ name: "claimed_by", type: "varchar", length: 200, nullable: true })
+    claimedBy!: string | null
+
+    /** When the claim expires; after it a stalled job may be claimed again. */
+    @Column({ name: "lease_expires_at", type: "timestamptz", nullable: true })
+    leaseExpiresAt!: Date | null
+
+    /** The payload of the job: ids, never an entity. */
+    @Column({ name: "payload", type: "jsonb" })
+    payload!: object
+
+    /** Why the last delivery failed. */
+    @Column({ name: "error", type: "text", nullable: true })
+    error!: string | null
+
+    /** When the job was first claimed. */
+    @Column({ name: "created_at", type: "timestamptz" })
+    createdAt!: Date
+
+    /** When the row last changed. */
+    @Column({ name: "updated_at", type: "timestamptz" })
+    updatedAt!: Date
+}

package/templates/be/patterns/jobs/platform/persistence.jobs.rows.ts.tpl

@@ -0,0 +1,13 @@
+/** One row a claim returns. */
+export interface ClaimedRow {
+    /** The id of the job row. */
+    readonly id: string
+    /** The kind of the job. */
+    readonly kind: string
+    /** The fencing token after the claim (a bigint arrives as text). */
+    readonly fencing_token: string
+    /** The last recorded step, or null. */
+    readonly current_step: string | null
+    /** The payload, as the database returns the jsonb value. */
+    readonly payload: object
+}

package/templates/be/patterns/jobs/platform/persistence.jobs.sql.ts.tpl

@@ -0,0 +1,33 @@
+import { sql } from "@modules/platform/database"
+
+/**
+ * Claims a delivery in one statement ($1 kind, $2 job key, $3 worker, $4 lease end, $5 payload, $6 instant). A new key inserts the row
+ * with token 1; an existing key is claimed again only when the job failed or its lease expired, and then the token is bumped by the
+ * store. A done job and a live claim match nothing, so no row comes back.
+ */
+export const CLAIM_JOB = sql`INSERT INTO jobs (kind, job_key, status, fencing_token, claimed_by, lease_expires_at, payload, created_at, updated_at)
+    VALUES ($1, $2, 'running', 1, $3, $4, $5::jsonb, $6, $6)
+    ON CONFLICT (job_key) DO UPDATE
+       SET fencing_token = jobs.fencing_token + 1, claimed_by = $3, lease_expires_at = $4, status = 'running', error = NULL, updated_at = $6
+     WHERE jobs.status = 'failed' OR (jobs.status = 'running' AND jobs.lease_expires_at < $6)
+    RETURNING id, kind, fencing_token, current_step, payload`
+
+/** The guarded writes wrap their UPDATE in a CTE: TypeORM returns a bare `UPDATE ... RETURNING` as `[rows, count]`, a SELECT as rows. */
+
+/** Records a step ($1 job id, $2 expected token, $3 step, $4 instant); no row comes back when the token is stale. */
+export const ADVANCE_JOB = sql`WITH changed AS (UPDATE jobs SET current_step = $3, updated_at = $4
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`
+
+/** Completes the job ($1 job id, $2 expected token, $3 instant). */
+export const COMPLETE_JOB = sql`WITH changed AS (UPDATE jobs SET status = 'done', lease_expires_at = NULL, updated_at = $3
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`
+
+/** Fails the job ($1 job id, $2 expected token, $3 reason, $4 instant). */
+export const FAIL_JOB = sql`WITH changed AS (UPDATE jobs SET status = 'failed', error = $3, lease_expires_at = NULL, updated_at = $4
+    WHERE id = $1 AND fencing_token = $2 AND status = 'running'
+       RETURNING id)
+    SELECT id FROM changed`

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

@@ -0,0 +1,29 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the job table the fenced jobs claim and settle their rows in. */
+export class CreateJobs@@epochMs13@@ implements MigrationInterface {
+    name = "CreateJobs@@epochMs13@@"
+
+    /** Creates the table; the job key is unique and the token starts at 1 with the first claim. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE jobs (
+    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+    kind varchar(200) NOT NULL,
+    job_key varchar(200) NOT NULL UNIQUE,
+    status varchar(16) NOT NULL CHECK (status IN ('running', 'failed', 'done')),
+    current_step varchar(200),
+    fencing_token bigint NOT NULL CHECK (fencing_token >= 1),
+    claimed_by varchar(200),
+    lease_expires_at timestamptz,
+    payload jsonb NOT NULL,
+    error text,
+    created_at timestamptz NOT NULL,
+    updated_at timestamptz NOT NULL
+)`)
+    }
+
+    /** Drops the table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE jobs`)
+    }
+}

package/templates/be/patterns/outbox/platform/index.ts.tpl

@@ -0,0 +1,2 @@
+export { OutboxLogEvent } from "./outbox.log-events"
+export { OutboxRelayPolicy } from "./outbox-relay.policy"

package/templates/be/patterns/outbox/platform/outbox-relay.policy.spec.ts.tpl

@@ -0,0 +1,96 @@
+import { fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import type { MockEntityManager } from "@starci/jest-preset"
+import type { EntityManager } from "typeorm"
+import type { Logger } from "@modules/platform/logging"
+import { OutboxLogEvent } from "./outbox.log-events"
+import { OutboxRelayPolicy } from "./outbox-relay.policy"
+
+interface Row {
+    readonly id: string
+}
+
+class ProbeRelay extends OutboxRelayPolicy<Row> {
+    readonly select = jest.fn<Promise<Array<Row>>, [EntityManager]>()
+    readonly deliver = jest.fn<Promise<void>, [ReadonlyArray<Row>]>()
+    readonly mark = jest.fn<Promise<void>, [EntityManager, ReadonlyArray<Row>]>()
+    readonly idle = jest.fn<Promise<void>, []>()
+
+    constructor(
+        protected readonly managers: ReadonlyArray<EntityManager>,
+        protected readonly logger: Logger,
+        protected readonly outbox = "probe",
+    ) {
+        super()
+    }
+}
+
+const build = (...managers: Array<MockEntityManager>) => {
+    const logger = mock<Logger>()
+    const relay = new ProbeRelay(managers, logger)
+    return { relay, logger }
+}
+
+describe("OutboxRelayPolicy", () => {
+    describe("relay", () => {
+        it("delivers and marks every connection's waiting rows in its own transaction", async () => {
+            const first = fakeTransaction(mockEntityManager())
+            const second = fakeTransaction(mockEntityManager())
+            const { relay } = build(first.em, second.em)
+            const rows = [{ id: "row-1" }, { id: "row-2" }]
+            relay.select.mockResolvedValueOnce(rows).mockResolvedValueOnce([])
+            relay.deliver.mockResolvedValue(undefined)
+            relay.mark.mockResolvedValue(undefined)
+
+            await expect(relay.relay()).resolves.toBe(2)
+
+            expect(relay.deliver).toHaveBeenCalledWith(rows)
+            expect(relay.mark).toHaveBeenCalledWith(expect.any(Object), rows)
+            expect(relay.mark).toHaveBeenCalledTimes(1)
+            expect(first.commits).toBe(1)
+            expect(second.commits).toBe(1)
+        })
+
+        it("leaves the rows unmarked when delivery fails", async () => {
+            const transaction = fakeTransaction(mockEntityManager())
+            const { relay } = build(transaction.em)
+            const failure = new Error("transport down")
+            relay.select.mockResolvedValue([{ id: "row-1" }])
+            relay.deliver.mockRejectedValue(failure)
+
+            await expect(relay.relay()).rejects.toBe(failure)
+
+            expect(relay.mark).not.toHaveBeenCalled()
+            expect(transaction.rollbacks).toBe(1)
+        })
+    })
+
+    describe("the loop", () => {
+        it("repeats immediately after work, idles after an empty or failed pass, logs the failure and stops on shutdown", async () => {
+            const { relay, logger } = build()
+            const failure = new Error("outbox unreadable")
+            jest.spyOn(relay, "relay").mockResolvedValueOnce(1).mockResolvedValueOnce(0).mockRejectedValueOnce(failure)
+            let waits = 0
+            let shutdown: Promise<void> = Promise.resolve()
+            let reachedShutdown: () => void = () => undefined
+            const stopped = new Promise<void>((resolve) => {
+                reachedShutdown = resolve
+            })
+            relay.idle.mockImplementation(() => {
+                waits += 1
+                if (waits === 2) {
+                    shutdown = relay.onApplicationShutdown()
+                    reachedShutdown()
+                }
+                return Promise.resolve()
+            })
+
+            relay.onApplicationBootstrap()
+            await stopped
+            await shutdown
+
+            expect(relay.relay).toHaveBeenCalledTimes(3)
+            expect(relay.idle).toHaveBeenCalledTimes(2)
+            expect(logger.error).toHaveBeenCalledWith(OutboxLogEvent.RelayFailed, failure, { outbox: "probe" })
+        })
+    })
+})

package/templates/be/patterns/outbox/platform/outbox-relay.policy.ts.tpl

@@ -0,0 +1,78 @@
+import type { OnApplicationBootstrap, OnApplicationShutdown } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import type { Logger } from "@modules/platform/logging"
+import { OutboxLogEvent } from "./outbox.log-events"
+
+/**
+ * The relay of an outbox: the one loop the event bus and the queues share. It reads the rows that wait on each connection of the app,
+ * in the order they were written, hands them over and marks them sent in the same transaction. A row that is not committed is not
+ * visible to the relay, so nothing leaves for a rolled-back change; a crash between the delivery and the mark delivers the row again,
+ * which the receiver absorbs. The loop runs from the start of the app to its shutdown and pauses only when the outbox is empty.
+ * A concrete relay says how a batch is read, delivered and marked, which outbox it is and how it waits.
+ */
+export abstract class OutboxRelayPolicy<Row extends { readonly id: string }>
+    implements OnApplicationBootstrap, OnApplicationShutdown
+{
+    private running = false
+    private loop: Promise<void> = Promise.resolve()
+
+    /** The entity managers of the connections that hold an outbox, read in this order. */
+    protected abstract readonly managers: ReadonlyArray<EntityManager>
+
+    /** Where a failed pass is logged. */
+    protected abstract readonly logger: Logger
+
+    /** The name of the outbox this relay serves, written into the log line of a failed pass. */
+    protected abstract readonly outbox: string
+
+    /** One pass over every connection: relays the oldest waiting rows of each and answers how many it relayed. */
+    async relay(): Promise<number> {
+        let relayed = 0
+        for (const manager of this.managers) relayed += await this.relayOf(manager)
+        return relayed
+    }
+
+    /** Starts the relay loop over the outbox of every connection. */
+    onApplicationBootstrap(): void {
+        this.running = true
+        this.loop = this.run()
+    }
+
+    /** Stops the loop and waits for its last pass. */
+    async onApplicationShutdown(): Promise<void> {
+        this.running = false
+        await this.loop
+    }
+
+    /** Reads and locks the oldest rows that wait, at most one batch; a second relay skips the rows this one holds. */
+    protected abstract select(tx: EntityManager): Promise<Array<Row>>
+
+    /** Hands the rows over; a throw rolls the transaction back, so the rows stay waiting. */
+    protected abstract deliver(rows: ReadonlyArray<Row>): Promise<void>
+
+    /** Marks the rows as handed over, in the transaction that read them. */
+    protected abstract mark(tx: EntityManager, rows: ReadonlyArray<Row>): Promise<void>
+
+    /** Waits before the next pass over an empty outbox. */
+    protected abstract idle(): Promise<void>
+
+    private relayOf(manager: EntityManager): Promise<number> {
+        return manager.transaction(async (tx) => {
+            const rows = await this.select(tx)
+            if (rows.length === 0) return 0
+            await this.deliver(rows)
+            await this.mark(tx, rows)
+            return rows.length
+        })
+    }
+
+    private async run(): Promise<void> {
+        while (this.running) {
+            const relayed = await this.relay().catch((cause: unknown) => {
+                this.logger.error(OutboxLogEvent.RelayFailed, cause, { outbox: this.outbox })
+                return 0
+            })
+            if (relayed === 0 && this.running) await this.idle()
+        }
+    }
+}

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

@@ -0,0 +1,5 @@
+/** Log events of the outbox relay. */
+export enum OutboxLogEvent {
+    /** A relay pass over an outbox failed; the next pass tries again. The `outbox` field names which outbox. */
+    RelayFailed = "outbox.relay.failed",
+}

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

@@ -0,0 +1,18 @@
+import type { MigrationInterface, QueryRunner } from "typeorm"
+
+/** Creates the @@name@@ read-model table. */
+export class Create@@Name@@Projection@@epochMs13@@ implements MigrationInterface {
+    name = "Create@@Name@@Projection@@epochMs13@@"
+
+    /** Creates the table. */
+    async up(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`CREATE TABLE @@nameSnake@@ (
+    id uuid PRIMARY KEY
+)`)
+    }
+
+    /** Drops the table. */
+    async down(queryRunner: QueryRunner): Promise<void> {
+        await queryRunner.query(`DROP TABLE @@nameSnake@@`)
+    }
+}

package/templates/be/patterns/projections/persistence.connection.ts.tpl

@@ -0,0 +1,8 @@
+import { @@Name@@ProjectionEntity } from "../@@name@@.projection-entity"
+import { Create@@Name@@Projection@@epochMs13@@ } from "./migrations/@@epochMs13@@-create-@@name@@"
+
+/** The entities of the @@name@@ read model, for the connection that holds them. */
+export const @@nameCamel@@Entities = [@@Name@@ProjectionEntity]
+
+/** The migrations of the @@name@@ read model, in the order they run. */
+export const @@nameCamel@@Migrations = [Create@@Name@@Projection@@epochMs13@@]

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

@@ -0,0 +1,9 @@
+import { Entity, PrimaryColumn } from "typeorm"
+
+@Entity("@@nameSnake@@")
+/** The read-model row of one @@name@@: written only by its projection. */
+export class @@Name@@ProjectionEntity {
+    /** The id of the aggregate the row summarises. */
+    @PrimaryColumn({ name: "id", type: "uuid" })
+    id!: string
+}

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

@@ -0,0 +1,3 @@
+export { @@nameCamel@@Entities, @@nameCamel@@Migrations } from "./persistence/connection"
+export { @@Name@@Module } from "./@@name@@.module"
+export { @@Name@@Projection } from "./@@name@@.projection"

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

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { @@Name@@Options } from "./@@name@@.options"
+
+/** The configurable-module base of the @@name@@ projection; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<@@Name@@Options>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()